Cleanup: move public doc-strings into headers for 'blenlib'

- Added space below non doc-string comments to make it clear
  these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.
- Minor improvements to doc-strings.

Ref T92709

1 files changed, 16 insertions, 0 deletions

diff --git a/source/blender/blenlib/BLI_polyfill_2d.h b/source/blender/blenlib/BLI_polyfill_2d.h
index ca63ea5af87..d16c102ec86 100644
--- a/source/blender/blenlib/BLI_polyfill_2d.h
+++ b/source/blender/blenlib/BLI_polyfill_2d.h
@@ -26,6 +26,9 @@ extern "C" {
 
 struct MemArena;
 
+/**
+ * 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,
                              const int coords_sign,
@@ -33,6 +36,19 @@ void BLI_polyfill_calc_arena(const float (*coords)[2],
 
                              struct MemArena *arena);
 
+/**
+ * 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,
                        const int coords_sign,