Comments: clarify math lib

2 files changed, 22 insertions, 1 deletions

diff --git a/source/blender/blenlib/intern/math_geom.c b/source/blender/blenlib/intern/math_geom.c
index 4db9015d9e2..496e5362cc4 100644
--- a/source/blender/blenlib/intern/math_geom.c
+++ b/source/blender/blenlib/intern/math_geom.c
@@ -160,6 +160,12 @@ float area_poly_v3(const float verts[][3], unsigned int nr)
 	return normal_poly_v3(n, verts, nr) * 0.5f;
 }
 
+/**
+ * Scalar cross product of a 2d polygon.
+ *
+ * - equivalent to ``area * 2``
+ * - useful for checking polygon winding (a positive value is clockwise).
+ */
 float cross_poly_v2(const float verts[][2], unsigned int nr)
 {
 	unsigned int a;
@@ -1786,7 +1792,10 @@ float closest_to_line_v2(float cp[2], const float p[2], const float l1[2], const
 	return lambda;
 }
 
-/* little sister we only need to know lambda */
+/**
+ * A simplified version of #closest_to_line_v3
+ * we only need to return the ``lambda``
+ */
 float line_point_factor_v3(const float p[3], const float l1[3], const float l2[3])
 {
 	float h[3], u[3];
diff --git a/source/blender/blenlib/intern/math_vector_inline.c b/source/blender/blenlib/intern/math_vector_inline.c
index 5529433f6c9..da9d5bd3f49 100644
--- a/source/blender/blenlib/intern/math_vector_inline.c
+++ b/source/blender/blenlib/intern/math_vector_inline.c
@@ -957,6 +957,18 @@ MINLINE bool compare_v4v4(const float v1[4], const float v2[4], const float limi
 	return false;
 }
 
+/**
+ * <pre>
+ *        + l1
+ *        |
+ * neg <- | -> pos
+ *        |
+ *        + l2
+ * </pre>
+ *
+ * \return Positive value when 'pt' is left-of-line
+ * (looking from 'l1' -> 'l2').
+ */
 MINLINE float line_point_side_v2(const float l1[2], const float l2[2], const float pt[2])
 {
 	return (((l1[0] - pt[0]) * (l2[1] - pt[1])) -