Docs: comment polyfill2d functions

source/blender/blenlib/intern/polyfill2d.c

@@ -768,11 +768,7 @@ static void pf_ear_tip_cut(PolyFill *pf, PolyIndex *pi_ear_tip)
 }
 
 /**
- * Triangulates the given (convex or concave) simple polygon to a list of triangle vertices.
+ * Initializes the #PolyFill structure before tessellating with #polyfill_calc.
- *
- * \param coords pairs describing vertices of the polygon, in either clockwise or counterclockwise order.
- * \return triples of triangle indices in clockwise order.
- *         Note the returned array is reused for later calls to the same method.
  */
 static void polyfill_prepare(
         PolyFill *pf,
@@ -862,6 +858,9 @@ static void polyfill_calc(
 	pf_triangulate(pf);
 }
 
+/**
+ * A version of #BLI_polyfill_calc that uses a memory arena to avoid re-allocations.
+ */
 void BLI_polyfill_calc_arena(
         const float (*coords)[2],
         const unsigned int coords_tot,
@@ -905,6 +904,19 @@ void BLI_polyfill_calc_arena(
 #endif
 }
 
+/**
+ * Triangulates the given (convex or concave) simple polygon to a list of triangle vertices.
+ *
+ * \param coords: 2D coordinates describing vertices of the polygon,
+ * in either clockwise or counterclockwise order.
+ * \param coords_tot: Total points in the array.
+ * \param coords_sign: Pass this when we know the sign in advance to avoid extra calculations.
+ *
+ * \param r_tris: This array is filled in with triangle indices in clockwise order.
+ * The length of the array must be ``coords_tot - 2``.
+ * Indices are guaranteed to be assigned to unique triangles, with valid indices,
+ * even in the case of degenerate input (self intersecting polygons, zero area ears... etc).
+ */
 void BLI_polyfill_calc(
         const float (*coords)[2],
         const unsigned int coords_tot,