Cleanup: doxygen comments

Also correct some outdated symbol references,
add missing 'name' commands.

8 files changed, 43 insertions, 25 deletions

diff --git a/source/blender/blenlib/intern/delaunay_2d.c b/source/blender/blenlib/intern/delaunay_2d.c
index 9c1e52b53a4..27f7a2a4430 100644
--- a/source/blender/blenlib/intern/delaunay_2d.c
+++ b/source/blender/blenlib/intern/delaunay_2d.c
@@ -115,8 +115,10 @@ static void validate_face_centroid(SymEdge *se);
 static void validate_cdt(CDT_state *cdt, bool check_all_tris);
 #endif
 
-/** return 1 if a,b,c forms CCW angle, -1 if a CW angle, 0 if straight.
- * For straight test, allow b to be withing eps of line. */
+/**
+ * Return 1 if a,b,c forms CCW angle, -1 if a CW angle, 0 if straight.
+ * For straight test, allow b to be withing eps of line.
+ */
 static int CCW_test(const double a[2], const double b[2], const double c[2], const double eps)
 {
   double det;
@@ -902,7 +904,8 @@ static LocateResult locate_point(CDT_state *cdt, const double p[2])
   return lr;
 }
 
-/** Return true if circumcircle(v1, v2, v3) does not contain p.
+/**
+ * Return true if circumcircle(v1, v2, v3) does not contain p.
  * To avoid possible infinite flip loops, we will say true even if p is inside the circle
  * but less than epsilon from the boundary; or if v1, v2, v3, form a straight line.
  */
diff --git a/source/blender/blenlib/intern/hash_md5.c b/source/blender/blenlib/intern/hash_md5.c
index f9e9b3bfbf9..5ec1c91a735 100644
--- a/source/blender/blenlib/intern/hash_md5.c
+++ b/source/blender/blenlib/intern/hash_md5.c
@@ -94,8 +94,9 @@ struct md5_ctx {
  * (RFC 1321, 3.1: Step 1) */
 static const unsigned char fillbuf[64] = {0x80, 0 /* , 0, 0, ...  */};
 
-/** Initialize structure containing state of computation.
- *  (RFC 1321, 3.3: Step 3)
+/**
+ * Initialize structure containing state of computation.
+ * (RFC 1321, 3.3: Step 3)
  */
 static void md5_init_ctx(struct md5_ctx *ctx)
 {
@@ -283,8 +284,9 @@ static void *md5_read_ctx(const struct md5_ctx *ctx, void *resbuf)
 
 /* Top level public functions. */
 
-/** Compute MD5 message digest for bytes read from 'stream'.
- *  The resulting message digest number will be written into the 16 bytes beginning at 'resblock'.
+/**
+ * Compute MD5 message digest for bytes read from 'stream'.
+ * The resulting message digest number will be written into the 16 bytes beginning at 'resblock'.
  * \return Non-zero if an error occurred.
  */
 int BLI_hash_md5_stream(FILE *stream, void *resblock)
diff --git a/source/blender/blenlib/intern/kdtree_impl.h b/source/blender/blenlib/intern/kdtree_impl.h
index 32e8a4e90f5..404e136a0a6 100644
--- a/source/blender/blenlib/intern/kdtree_impl.h
+++ b/source/blender/blenlib/intern/kdtree_impl.h
@@ -58,8 +58,10 @@ struct KDTree {
 
 #define KD_NODE_UNSET ((uint)-1)
 
-/** When set we know all values are unbalanced,
- * otherwise clear them when re-balancing: see T62210. */
+/**
+ * When set we know all values are unbalanced,
+ * otherwise clear them when re-balancing: see T62210.
+ */
 #define KD_NODE_ROOT_IS_INIT ((uint)-2)
 
 /* -------------------------------------------------------------------- */
diff --git a/source/blender/blenlib/intern/math_base_inline.c b/source/blender/blenlib/intern/math_base_inline.c
index 0309876d8fb..4c86b9d3396 100644
--- a/source/blender/blenlib/intern/math_base_inline.c
+++ b/source/blender/blenlib/intern/math_base_inline.c
@@ -526,15 +526,19 @@ MINLINE int signum_i(float a)
   }
 }
 
-/** Returns number of (base ten) *significant* digits of integer part of given float
- * (negative in case of decimal-only floats, 0.01 returns -1 e.g.). */
+/**
+ * Returns number of (base ten) *significant* digits of integer part of given float
+ * (negative in case of decimal-only floats, 0.01 returns -1 e.g.).
+ */
 MINLINE int integer_digits_f(const float f)
 {
   return (f == 0.0f) ? 0 : (int)floor(log10(fabs(f))) + 1;
 }
 
-/** Returns number of (base ten) *significant* digits of integer part of given double
- * (negative in case of decimal-only floats, 0.01 returns -1 e.g.). */
+/**
+ * Returns number of (base ten) *significant* digits of integer part of given double
+ * (negative in case of decimal-only floats, 0.01 returns -1 e.g.).
+ */
 MINLINE int integer_digits_d(const double d)
 {
   return (d == 0.0) ? 0 : (int)floor(log10(fabs(d))) + 1;
diff --git a/source/blender/blenlib/intern/math_geom.c b/source/blender/blenlib/intern/math_geom.c
index 67ef4d57b4b..27715ed49b5 100644
--- a/source/blender/blenlib/intern/math_geom.c
+++ b/source/blender/blenlib/intern/math_geom.c
@@ -2996,8 +2996,9 @@ int isect_line_line_v3(const float v1[3],
   return isect_line_line_epsilon_v3(v1, v2, v3, v4, r_i1, r_i2, epsilon);
 }
 
-/** Intersection point strictly between the two lines
- * \return false when no intersection is found
+/**
+ * Intersection point strictly between the two lines
+ * \return false when no intersection is found.
  */
 bool isect_line_line_strict_v3(const float v1[3],
                                const float v2[3],
@@ -3188,7 +3189,7 @@ bool isect_ray_aabb_v3(const struct IsectRayAABB_Precalc *data,
  * Test a bounding box (AABB) for ray intersection.
  * Assumes the ray is already local to the boundbox space.
  *
- * \note: \a direction should be normalized
+ * \note \a direction should be normalized
  * if you intend to use the \a tmin or \a tmax distance results!
  */
 bool isect_ray_aabb_v3_simple(const float orig[3],
@@ -3791,7 +3792,7 @@ bool barycentric_coords_v2(
 }
 
 /**
- * \note: using #cross_tri_v2 means locations outside the triangle are correctly weighted
+ * \note Using #cross_tri_v2 means locations outside the triangle are correctly weighted.
  *
  * \note This is *exactly* the same calculation as #resolve_tri_uv_v2,
  * although it has double precision and is used for texture baking, so keep both.
diff --git a/source/blender/blenlib/intern/math_matrix.c b/source/blender/blenlib/intern/math_matrix.c
index 48884082dd8..5118d8a698e 100644
--- a/source/blender/blenlib/intern/math_matrix.c
+++ b/source/blender/blenlib/intern/math_matrix.c
@@ -1964,8 +1964,10 @@ void mat4_to_size(float size[3], const float mat[4][4])
   size[2] = len_v3(mat[2]);
 }
 
-/** Extract scale factors from the matrix, with correction to ensure
- *  exact volume in case of a sheared matrix. */
+/**
+ * Extract scale factors from the matrix, with correction to ensure
+ * exact volume in case of a sheared matrix.
+ */
 void mat4_to_size_fix_shear(float size[3], const float mat[4][4])
 {
   mat4_to_size(size, mat);
diff --git a/source/blender/blenlib/intern/math_rotation.c b/source/blender/blenlib/intern/math_rotation.c
index 37c0c05b061..94f0f523c6e 100644
--- a/source/blender/blenlib/intern/math_rotation.c
+++ b/source/blender/blenlib/intern/math_rotation.c
@@ -77,7 +77,7 @@ void mul_qt_qtqt(float q[4], const float q1[4], const float q2[4])
 }
 
 /**
- * \note:
+ * \note
  * Assumes a unit quaternion?
  *
  * in fact not, but you may want to use a unit quat, read on...
@@ -93,7 +93,7 @@ void mul_qt_qtqt(float q[4], const float q1[4], const float q2[4])
  * For people used to python mathutils, its like:
  * def mul_qt_v3(q, v): (q * Quaternion((0.0, v[0], v[1], v[2])) * q.conjugated())[1:]
  *
- * \note: multiplying by 3x3 matrix is ~25% faster.
+ * \note Multiplying by 3x3 matrix is ~25% faster.
  */
 void mul_qt_v3(const float q[4], float v[3])
 {
diff --git a/source/blender/blenlib/intern/path_util.c b/source/blender/blenlib/intern/path_util.c
index 725b6f8937a..dff1f77c1ab 100644
--- a/source/blender/blenlib/intern/path_util.c
+++ b/source/blender/blenlib/intern/path_util.c
@@ -57,8 +57,10 @@
 
 #ifdef WIN32
 
-/** Return true if the path is absolute ie starts with a drive specifier
- * (eg A:\) or is a UNC path. */
+/**
+ * Return true if the path is absolute ie starts with a drive specifier
+ * (eg A:\) or is a UNC path.
+ */
 static bool BLI_path_is_abs(const char *name);
 
 #endif /* WIN32 */
@@ -444,8 +446,10 @@ static int BLI_path_unc_prefix_len(const char *path)
 
 #if defined(WIN32)
 
-/** Return true if the path is absolute ie starts with a drive specifier
- * (eg A:\) or is a UNC path. */
+/**
+ * Return true if the path is absolute ie starts with a drive specifier
+ * (eg A:\) or is a UNC path.
+ */
 static bool BLI_path_is_abs(const char *name)
 {
   return (name[1] == ':' && (name[2] == '\\' || name[2] == '/')) || BLI_path_is_unc(name);