diff --git a/libweston/vertex-clipping.c b/libweston/vertex-clipping.c
index d4ab871f..f34cdf60 100644
--- a/libweston/vertex-clipping.c
+++ b/libweston/vertex-clipping.c
@@ -291,6 +291,9 @@ clip_polygon_bottom(struct clip_context *ctx, const struct polygon8 *src,
 	return ctx->vertices - dst;
 }
 
+/* General purpose polygon clipping algorithm based on Sutherland-Hodgman:
+ * https://www.codeguru.com/cplusplus/polygon-clipping/
+ */
 WESTON_EXPORT_FOR_TESTS int
 clipper_clip(const struct clipper_vertex *polygon,
 	     size_t polygon_len,
@@ -360,7 +363,7 @@ clipper_quad_clip(struct clipper_quad *quad,
 {
 	int i, n;
 
-	/* Simple case: quad edges are parallel to clipping box edges, there
+	/* Aligned case: quad edges are parallel to clipping box edges, there
 	 * will be either four or zero edges. We just need to clamp the quad
 	 * edges to the clipping box edges and test for non-zero area:
 	 */
@@ -378,18 +381,14 @@ clipper_quad_clip(struct clipper_quad *quad,
 			return 0;
 	}
 
-	/* Transformed case: first, simple bounding box check to discard early a
+	/* Unaligned case: first, simple bounding box check to discard early a
 	 * quad that does not intersect with the clipping box:
 	 */
 	if ((quad->bbox[0].x >= box[1].x) || (quad->bbox[1].x <= box[0].x) ||
 	    (quad->bbox[0].y >= box[1].y) || (quad->bbox[1].y <= box[0].y))
 		return 0;
 
-	/* Then, use a general polygon clipping algorithm to clip the quad with
-	 * each side of the surface rect. The algorithm is Sutherland-Hodgman,
-	 * as explained in
-	 * https://www.codeguru.com/cplusplus/polygon-clipping/
-	 * but without looking at any of that code.
+	/* Then use our general purpose clipping algorithm:
 	 */
 	n = clipper_clip(quad->polygon, 4, box, vertices);
 
diff --git a/libweston/vertex-clipping.h b/libweston/vertex-clipping.h
index 2b0d9929..5e63cf6f 100644
--- a/libweston/vertex-clipping.h
+++ b/libweston/vertex-clipping.h
@@ -39,6 +39,15 @@ struct clipper_quad {
 	bool axis_aligned;
 };
 
+/*
+ * General purpose clipping function. Compute the boundary vertices of the
+ * intersection of a 'polygon' and a clipping 'box'. 'polygon' points to an
+ * array of 'polygon_len' vertices, less than or equal to 8, defining a convex
+ * polygon of any winding order. 'box' points to an array of 2 vertices where
+ * the values of the 1st vertex are less than or equal to the values of the 2nd
+ * vertex. Up to 16 resulting vertices, using 'polygon' winding order, are
+ * written to 'vertices'. The return value is the number of vertices created.
+ */
 int
 clipper_clip(const struct clipper_vertex *polygon,
 	     size_t polygon_len,