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, 21 insertions, 0 deletions

diff --git a/source/blender/blenlib/BLI_polyfill_2d_beautify.h b/source/blender/blenlib/BLI_polyfill_2d_beautify.h
index 2c5296269ae..b0b97336a3b 100644
--- a/source/blender/blenlib/BLI_polyfill_2d_beautify.h
+++ b/source/blender/blenlib/BLI_polyfill_2d_beautify.h
@@ -27,6 +27,12 @@ extern "C" {
 struct Heap;
 struct MemArena;
 
+/**
+ * The intention is that this calculates the output of #BLI_polyfill_calc
+ * \note assumes the \a coords form a boundary,
+ * so any edges running along contiguous (wrapped) indices,
+ * are ignored since the edges won't share 2 faces.
+ */
 void BLI_polyfill_beautify(const float (*coords)[2],
                            const unsigned int coords_tot,
                            unsigned int (*tris)[3],
@@ -35,6 +41,21 @@ void BLI_polyfill_beautify(const float (*coords)[2],
                            struct MemArena *arena,
                            struct Heap *eheap);
 
+/**
+ * Assuming we have 2 triangles sharing an edge (2 - 4),
+ * check if the edge running from (1 - 3) gives better results.
+ *
+ * \param lock_degenerate: Use to avoid rotating out of a degenerate state:
+ * - When true, an existing zero area face on either side of the (2 - 4
+ *   split will return a positive value.
+ * - When false, the check must be non-biased towards either split direction.
+ * \param r_area: Return the area of the quad,
+ * This can be useful when comparing the return value with near zero epsilons.
+ * In this case the epsilon can be scaled by the area to avoid the return value
+ * of very large faces not having a reliable way to detect near-zero output.
+ *
+ * \return (negative number means the edge can be rotated, lager == better).
+ */
 float BLI_polyfill_beautify_quad_rotate_calc_ex(const float v1[2],
                                                 const float v2[2],
                                                 const float v3[2],