diff --git a/README.md b/README.md
index adf2abe5..62bd7194 100644
--- a/README.md
+++ b/README.md
@@ -68,7 +68,7 @@ Path arithmetic:
 ```Rust
 use flo_curves::bezier::path::*;
 
-let rectangle_with_hole = path_sub::<_,_, SimpleBezierPath>(&vec![rectangle], &vec![circle])
+let rectangle_with_hole = path_sub::<SimpleBezierPath>(&vec![rectangle], &vec![circle], 0.01);
 ```
 
 ---
diff --git a/src/bezier/path/mod.rs b/src/bezier/path/mod.rs
index d2bcdac7..4ccd563d 100644
--- a/src/bezier/path/mod.rs
+++ b/src/bezier/path/mod.rs
@@ -1,18 +1,38 @@
 //!
 //! # Manipulates multiple Bezier curves joined into a path
+//!
+//! ```
+//! # use flo_curves::*;
+//! # use flo_curves::arc::*;
+//! # use flo_curves::bezier;
+//! # use flo_curves::bezier::path::*;
+//! # 
+//! let rectangle = BezierPathBuilder::<SimpleBezierPath>::start(Coord2(1.0, 1.0))
+//!     .line_to(Coord2(5.0, 1.0))
+//!     .line_to(Coord2(5.0, 5.0))
+//!     .line_to(Coord2(1.0, 5.0))
+//!     .line_to(Coord2(1.0, 1.0))
+//!     .build();
+//! let circle = Circle::new(Coord2(3.0, 3.0), 1.0).to_path::<SimpleBezierPath>();
+//!
+//! let rectangle_with_hole = path_sub::<SimpleBezierPath>(&vec![rectangle], &vec![circle], 0.01);
+//! ```
 //! 
-//! The `BezierPath` trait provides a way to represent a bezier path. `flo_curves` considers a path to be a single 
-//! closed loop, unlike many libraries which allow for open paths and paths with subpaths. Instead, a path with 
-//! multiple subpaths is represented as a collection - ie `Vec<impl Path>`. This reduces the number of edge cases
-//! the library has to deal with.
-//! 
-//! The `path_add()`, `path_sub()` and `path_intersect()` functions can be used to perform path arithmetic: combining
-//! multiple paths into a single result. The `GraphPath` type is used to implement these functions: it can represent
-//! paths where points can have more than one following edge attached to them and provides functions for implementing
-//! similar operations.
-//! 
-//! `BezierPathBuilder` provides a way to quickly build paths from any type implementing the factory trait without
-//! needing to generate all of the primitives manually.
+//! Anything that implements the `BezierPath` trait can be treated as a path. The `SimpleBezierPath` type is provided
+//! as a convenient default implementation of this trait. These paths represent a single perimeter of a region.
+//!
+//! The arithmetic operations such as `path_sub()`, `path_add()`, `path_intersect()` all work with collections of these
+//! perimeters, stored in a `Vec`. A path with a hole in the middle will have two perimeters, for example. 
+//!
+//! These perimeters must not be self-intersecting: `flo_curves` doesn't use a winding rule as such but instead considers
+//! all edges to be exterior edges (which is very similar to an even-odd winding rule). A couple of methods are provided
+//! for fixing paths with self-intersections: `path_remove_interior_points()` will find the outermost perimeter of a shape
+//! - which is useful for tidying up the subpaths. `path_remove_overlapped_points()` will combine subpaths so that
+//! there are no overlapping edges. These two functions provide much finer control than is possible through the traditional
+//! idea of the winding rule.
+//!
+//! There are a few more advanced algorithms: for example, the `flood_fill_concave()` function provides a vector
+//! implementation of the flood fill algorithm, returning a path that fills a space defined by a ray-casting function.
 //!
 
 mod path;