[gimp] app: add comment to gimp_transform_polygon()

[N/A <ell src gnome org>]

commit 91b35591c61b3aa50b7f17bfaaeb479dcadff23b
Author: Ell <ell_se yahoo com>
Date:   Wed Jan 31 10:03:29 2018 -0500

    app: add comment to gimp_transform_polygon()
    
    .. describing the function, and, in particular, specifying upper
    bounds for the resulting number of vertices.

 app/core/gimp-transform-utils.c |   12 ++++++++++++
 1 files changed, 12 insertions(+), 0 deletions(-)
---
diff --git a/app/core/gimp-transform-utils.c b/app/core/gimp-transform-utils.c
index 6bbe394..c571d00 100644
--- a/app/core/gimp-transform-utils.c
+++ b/app/core/gimp-transform-utils.c
@@ -551,6 +551,18 @@ gimp_transform_polygon_is_convex (gdouble x1,
   return (z1 * z2 > 0) && (z3 * z4 > 0);
 }
 
+/* transforms the polygon or polyline, whose vertices are given by 'vertices',
+ * by 'matrix', performing clipping by the near plane.  'closed' indicates
+ * whether the vertices represent a polygon ('closed == TRUE') or a polyline
+ * ('closed == FALSE').
+ *
+ * returns the transformed vertices in 't_vertices', and their count in
+ * 'n_t_vertices'.  the minimal possible number of transformed vertices is 0,
+ * which happens when the entire input is clipped.  in general, the maximal
+ * possible number of transformed vertices is '3 * n_vertices / 2' (rounded
+ * down), however, for convex polygons the number is 'n_vertices + 1', and for
+ * a single line segment the number is 2.
+ */
 void
 gimp_transform_polygon (const GimpMatrix3 *matrix,
                         const GimpVector2 *vertices,