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, 23 insertions, 4 deletions

diff --git a/source/blender/blenlib/BLI_math_boolean.hh b/source/blender/blenlib/BLI_math_boolean.hh
index 79b1483bfb8..20fd00b2aa4 100644
--- a/source/blender/blenlib/BLI_math_boolean.hh
+++ b/source/blender/blenlib/BLI_math_boolean.hh
@@ -32,20 +32,24 @@
 
 namespace blender {
 
-/* #orient2d gives the exact result, using multi-precision arithmetic when result
+/**
+ * #orient2d gives the exact result, using multi-precision arithmetic when result
  * is close to zero. orient3d_fast just uses double arithmetic, so may be
  * wrong if the answer is very close to zero.
- * Similarly, for #incircle and #incircle_fast. */
+ * Similarly, for #incircle and #incircle_fast.
+ */
 int orient2d(const double2 &a, const double2 &b, const double2 &c);
 int orient2d_fast(const double2 &a, const double2 &b, const double2 &c);
 
 int incircle(const double2 &a, const double2 &b, const double2 &c, const double2 &d);
 int incircle_fast(const double2 &a, const double2 &b, const double2 &c, const double2 &d);
 
-/* #orient3d gives the exact result, using multi-precision arithmetic when result
+/**
+ * #orient3d gives the exact result, using multi-precision arithmetic when result
  * is close to zero. orient3d_fast just uses double arithmetic, so may be
  * wrong if the answer is very close to zero.
- * Similarly, for #insphere and #insphere_fast. */
+ * Similarly, for #insphere and #insphere_fast.
+ */
 int orient3d(const double3 &a, const double3 &b, const double3 &c, const double3 &d);
 int orient3d_fast(const double3 &a, const double3 &b, const double3 &c, const double3 &d);
 
@@ -55,8 +59,23 @@ int insphere_fast(
     const double3 &a, const double3 &b, const double3 &c, const double3 &d, const double3 &e);
 
 #ifdef WITH_GMP
+/**
+ * Return +1 if a, b, c are in CCW order around a circle in the plane.
+ * Return -1 if they are in CW order, and 0 if they are in line.
+ */
 int orient2d(const mpq2 &a, const mpq2 &b, const mpq2 &c);
+/**
+ * Return +1 if d is in the oriented circle through a, b, and c.
+ * The oriented circle goes CCW through a, b, and c.
+ * Return -1 if d is outside, and 0 if it is on the circle.
+ */
 int incircle(const mpq2 &a, const mpq2 &b, const mpq2 &c, const mpq2 &d);
+/**
+ * Return +1 if d is below the plane containing a, b, c (which appear
+ * CCW when viewed from above the plane).
+ * Return -1 if d is above the plane.
+ * Return 0 if it is on the plane.
+ */
 int orient3d(const mpq3 &a, const mpq3 &b, const mpq3 &c, const mpq3 &d);
 #endif
 }  // namespace blender