Cleanup: correct unbalanced doxygen groups

Also add groups in some files.

14 files changed, 201 insertions, 102 deletions

diff --git a/source/blender/blenlib/BLI_dlrbTree.h b/source/blender/blenlib/BLI_dlrbTree.h
index 5226d1999be..72f18244d5b 100644
--- a/source/blender/blenlib/BLI_dlrbTree.h
+++ b/source/blender/blenlib/BLI_dlrbTree.h
@@ -213,6 +213,8 @@ DLRBT_Node *BLI_dlrbTree_add(DLRBT_Tree *tree,
  */
 void BLI_dlrbTree_insert(DLRBT_Tree *tree, DLRBT_Node *node);
 
+/** \} */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/source/blender/blenlib/BLI_ghash.h b/source/blender/blenlib/BLI_ghash.h
index b688712469f..0194f9aad40 100644
--- a/source/blender/blenlib/BLI_ghash.h
+++ b/source/blender/blenlib/BLI_ghash.h
@@ -43,6 +43,10 @@ extern "C" {
 #  endif
 #endif
 
+/* -------------------------------------------------------------------- */
+/** \name GHash Types
+ * \{ */
+
 typedef unsigned int (*GHashHashFP)(const void *key);
 /** returns false when equal */
 typedef bool (*GHashCmpFP)(const void *a, const void *b);
@@ -74,6 +78,8 @@ enum {
 #endif
 };
 
+/** \} */
+
 /* -------------------------------------------------------------------- */
 /** \name GHash API
  *
@@ -340,12 +346,11 @@ BLI_INLINE bool BLI_ghashIterator_done(const GHashIterator *ghi)
 /** \} */
 
 /* -------------------------------------------------------------------- */
-/** \name GSet API
+/** \name GSet Types
  * A 'set' implementation (unordered collection of unique elements).
  *
  * Internally this is a 'GHash' without any keys,
  * which is why this API's are in the same header & source file.
- *
  * \{ */
 
 typedef struct GSet GSet;
@@ -357,10 +362,13 @@ typedef GHashKeyCopyFP GSetKeyCopyFP;
 
 typedef GHashIterState GSetIterState;
 
+/** \} */
+
 /** \name GSet Public API
  *
  * Use ghash API to give 'set' functionality
  * \{ */
+
 GSet *BLI_gset_new_ex(GSetHashFP hashfp,
                       GSetCmpFP cmpfp,
                       const char *info,
@@ -521,6 +529,7 @@ double BLI_gset_calc_quality_ex(GSet *gs,
 double BLI_ghash_calc_quality(GHash *gh);
 double BLI_gset_calc_quality(GSet *gs);
 #endif /* GHASH_INTERNAL_API */
+
 /** \} */
 
 /* -------------------------------------------------------------------- */
diff --git a/source/blender/blenlib/BLI_math_geom.h b/source/blender/blenlib/BLI_math_geom.h
index a4c3c43ebd3..55d118d17de 100644
--- a/source/blender/blenlib/BLI_math_geom.h
+++ b/source/blender/blenlib/BLI_math_geom.h
@@ -37,8 +37,6 @@
 extern "C" {
 #endif
 
-/** \} */
-
 /* -------------------------------------------------------------------- */
 /** \name Polygons
  * \{ */
diff --git a/source/blender/blenlib/BLI_math_matrix.h b/source/blender/blenlib/BLI_math_matrix.h
index 4beb2508937..3d8fe6f564a 100644
--- a/source/blender/blenlib/BLI_math_matrix.h
+++ b/source/blender/blenlib/BLI_math_matrix.h
@@ -32,8 +32,6 @@
 extern "C" {
 #endif
 
-/** \} */
-
 /* -------------------------------------------------------------------- */
 /** \name Init
  * \{ */
diff --git a/source/blender/blenlib/BLI_math_rotation.h b/source/blender/blenlib/BLI_math_rotation.h
index bf447d954bc..9ff841f612f 100644
--- a/source/blender/blenlib/BLI_math_rotation.h
+++ b/source/blender/blenlib/BLI_math_rotation.h
@@ -32,6 +32,10 @@
 extern "C" {
 #endif
 
+/* -------------------------------------------------------------------- */
+/** \name Conversion Defines
+ * \{ */
+
 #define RAD2DEG(_rad) ((_rad) * (180.0 / M_PI))
 #define DEG2RAD(_deg) ((_deg) * (M_PI / 180.0))
 
diff --git a/source/blender/blenlib/BLI_math_time.h b/source/blender/blenlib/BLI_math_time.h
index 643d1b51a08..52857773797 100644
--- a/source/blender/blenlib/BLI_math_time.h
+++ b/source/blender/blenlib/BLI_math_time.h
@@ -42,7 +42,12 @@ extern "C" {
 
 /** \} */
 
-/** Explode given time value expressed in seconds, into a set of days, hours, minutes, seconds
+/* -------------------------------------------------------------------- */
+/** \name Time API
+ * \{ */
+
+/**
+ * Explode given time value expressed in seconds, into a set of days, hours, minutes, seconds
  * and/or milliseconds (depending on which return parameters are not NULL).
  *
  * \note The smallest given return parameter will get the potential fractional remaining time
diff --git a/source/blender/blenlib/BLI_string.h b/source/blender/blenlib/BLI_string.h
index d949e0e7b69..6a39d0a4215 100644
--- a/source/blender/blenlib/BLI_string.h
+++ b/source/blender/blenlib/BLI_string.h
@@ -491,6 +491,7 @@ int BLI_string_find_split_words(const char *str,
  * Avoid repeating destination with `sizeof(..)`.
  * \note `ARRAY_SIZE` allows pointers on some platforms.
  * \{ */
+
 #define STRNCPY(dst, src) BLI_strncpy(dst, src, ARRAY_SIZE(dst))
 #define STRNCPY_RLEN(dst, src) BLI_strncpy_rlen(dst, src, ARRAY_SIZE(dst))
 #define SNPRINTF(dst, format, ...) BLI_snprintf(dst, ARRAY_SIZE(dst), format, __VA_ARGS__)
@@ -500,6 +501,7 @@ int BLI_string_find_split_words(const char *str,
   len += BLI_strncpy_rlen(dst + len, suffix, ARRAY_SIZE(dst) - len)
 #define STR_CONCATF(dst, len, format, ...) \
   len += BLI_snprintf_rlen(dst + len, ARRAY_SIZE(dst) - len, format, __VA_ARGS__)
+
 /** \} */
 
 /* -------------------------------------------------------------------- */
diff --git a/source/blender/blenlib/BLI_string_utf8.h b/source/blender/blenlib/BLI_string_utf8.h
index 1216af9216a..17a41b2cccf 100644
--- a/source/blender/blenlib/BLI_string_utf8.h
+++ b/source/blender/blenlib/BLI_string_utf8.h
@@ -224,8 +224,10 @@ int BLI_str_utf8_offset_from_column(const char *str, int column) ATTR_WARN_UNUSE
  * Avoid repeating destination with `sizeof(..)`.
  * \note `ARRAY_SIZE` allows pointers on some platforms.
  * \{ */
+
 #define STRNCPY_UTF8(dst, src) BLI_strncpy_utf8(dst, src, ARRAY_SIZE(dst))
 #define STRNCPY_UTF8_RLEN(dst, src) BLI_strncpy_utf8_rlen(dst, src, ARRAY_SIZE(dst))
+
 /** \} */
 
 #ifdef __cplusplus
diff --git a/source/blender/blenlib/intern/BLI_ghash.c b/source/blender/blenlib/intern/BLI_ghash.c
index 859784222e4..8e2a8ab7639 100644
--- a/source/blender/blenlib/intern/BLI_ghash.c
+++ b/source/blender/blenlib/intern/BLI_ghash.c
@@ -949,6 +949,8 @@ void BLI_ghashIterator_free(GHashIterator *ghi)
 /** \} */
 
 /* -------------------------------------------------------------------- */
+/** \name GSet Public API
+ * \{ */
 
 GSet *BLI_gset_new_ex(GSetHashFP hashfp,
                       GSetCmpFP cmpfp,
diff --git a/source/blender/blenlib/intern/boxpack_2d.c b/source/blender/blenlib/intern/boxpack_2d.c
index 85b7ba54406..5d35feee699 100644
--- a/source/blender/blenlib/intern/boxpack_2d.c
+++ b/source/blender/blenlib/intern/boxpack_2d.c
@@ -120,6 +120,7 @@ static float box_ymax_get(const BoxPack *box)
 {
   return box->v[TR]->y;
 }
+
 /** \} */
 
 /* -------------------------------------------------------------------- */
@@ -165,6 +166,7 @@ static void box_ymax_set(BoxPack *box, const float f)
   box->v[TR]->y = f;
   box_v34y_update(box);
 }
+
 /** \} */
 
 /* -------------------------------------------------------------------- */
@@ -275,6 +277,7 @@ static int vertex_sort(const void *p1, const void *p2, void *vs_ctx_p)
   }
   return 0;
 }
+
 /** \} */
 
 void BLI_box_pack_2d(BoxPack *boxarray, const uint len, float *r_tot_x, float *r_tot_y)
diff --git a/source/blender/blenlib/intern/math_geom.c b/source/blender/blenlib/intern/math_geom.c
index e2bf842b8d0..a155877513a 100644
--- a/source/blender/blenlib/intern/math_geom.c
+++ b/source/blender/blenlib/intern/math_geom.c
@@ -718,6 +718,7 @@ float dist_squared_ray_to_aabb_v3_simple(const float ray_origin[3],
   dist_squared_ray_to_aabb_v3_precalc(&data, ray_origin, ray_direction);
   return dist_squared_ray_to_aabb_v3(&data, bb_min, bb_max, r_point, r_depth);
 }
+
 /** \} */
 
 /* -------------------------------------------------------------------- */
@@ -917,6 +918,7 @@ float dist_squared_to_projected_aabb_simple(const float projmat[4][4],
   bool dummy[3] = {true, true, true};
   return dist_squared_to_projected_aabb(&data, bbmin, bbmax, dummy);
 }
+
 /** \} */
 
 void closest_on_tri_to_point_v3(
diff --git a/source/blender/blenlib/intern/math_matrix.c b/source/blender/blenlib/intern/math_matrix.c
index e562ed8c1f5..eaf76696a0a 100644
--- a/source/blender/blenlib/intern/math_matrix.c
+++ b/source/blender/blenlib/intern/math_matrix.c
@@ -634,6 +634,7 @@ void _va_mul_m3_series_9(float r[3][3],
   mul_m3_m3m3(r, r, m7);
   mul_m3_m3m3(r, r, m8);
 }
+
 /** \} */
 
 /* -------------------------------------------------------------------- */
@@ -722,6 +723,7 @@ void _va_mul_m4_series_9(float r[4][4],
   mul_m4_m4m4(r, r, m7);
   mul_m4_m4m4(r, r, m8);
 }
+
 /** \} */
 
 void mul_v2_m3v2(float r[2], const float m[3][3], const float v[2])
diff --git a/source/blender/blenlib/intern/string.c b/source/blender/blenlib/intern/string.c
index 35711c9432f..2c626773871 100644
--- a/source/blender/blenlib/intern/string.c
+++ b/source/blender/blenlib/intern/string.c
@@ -42,6 +42,10 @@
 
 // #define DEBUG_STRSIZE
 
+/* -------------------------------------------------------------------- */
+/** \name String Duplicate/Copy
+ * \{ */
+
 char *BLI_strdupn(const char *str, const size_t len)
 {
   char *n = MEM_mallocN(len + 1, "strdup");
@@ -150,6 +154,12 @@ size_t BLI_strcpy_rlen(char *__restrict dst, const char *__restrict src)
   return srclen;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name String Printing
+ * \{ */
+
 size_t BLI_vsnprintf(char *__restrict buffer,
                      size_t maxncpy,
                      const char *__restrict format,
@@ -247,6 +257,12 @@ char *BLI_sprintfN(const char *__restrict format, ...)
   return n;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name String Escape/Un-Escape
+ * \{ */
+
 size_t BLI_str_escape(char *__restrict dst, const char *__restrict src, const size_t dst_maxncpy)
 {
 
@@ -349,6 +365,12 @@ const char *BLI_str_escape_find_quote(const char *str)
   return (*str == '"') ? str : NULL;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name String Quote/Un-Quote
+ * \{ */
+
 bool BLI_str_quoted_substr_range(const char *__restrict str,
                                  const char *__restrict prefix,
                                  int *__restrict r_start,
@@ -432,6 +454,12 @@ bool BLI_str_quoted_substr(const char *__restrict str,
   return is_complete;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name String Replace
+ * \{ */
+
 char *BLI_str_replaceN(const char *__restrict str,
                        const char *__restrict substr_old,
                        const char *__restrict substr_new)
@@ -513,6 +541,10 @@ bool BLI_str_replace_table_exact(char *string,
 
 /** \} */
 
+/* -------------------------------------------------------------------- */
+/** \name String Comparison/Matching
+ * \{ */
+
 int BLI_strcaseeq(const char *a, const char *b)
 {
   return (BLI_strcasecmp(a, b) == 0);
@@ -806,6 +838,79 @@ int BLI_strcmp_ignore_pad(const char *str1, const char *str2, const char pad)
   }
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name String Comparison at Start/End
+ * \{ */
+
+int BLI_str_index_in_array_n(const char *__restrict str,
+                             const char **__restrict str_array,
+                             const int str_array_len)
+{
+  int index;
+  const char **str_iter = str_array;
+
+  for (index = 0; index < str_array_len; str_iter++, index++) {
+    if (STREQ(str, *str_iter)) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+int BLI_str_index_in_array(const char *__restrict str, const char **__restrict str_array)
+{
+  int index;
+  const char **str_iter = str_array;
+
+  for (index = 0; *str_iter; str_iter++, index++) {
+    if (STREQ(str, *str_iter)) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+bool BLI_str_startswith(const char *__restrict str, const char *__restrict start)
+{
+  for (; *str && *start; str++, start++) {
+    if (*str != *start) {
+      return false;
+    }
+  }
+
+  return (*start == '\0');
+}
+
+bool BLI_strn_endswith(const char *__restrict str, const char *__restrict end, size_t slength)
+{
+  size_t elength = strlen(end);
+
+  if (elength < slength) {
+    const char *iter = &str[slength - elength];
+    while (*iter) {
+      if (*iter++ != *end++) {
+        return false;
+      }
+    }
+    return true;
+  }
+  return false;
+}
+
+bool BLI_str_endswith(const char *__restrict str, const char *__restrict end)
+{
+  const size_t slength = strlen(str);
+  return BLI_strn_endswith(str, end, slength);
+}
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name String Length
+ * \{ */
+
 size_t BLI_strnlen(const char *s, const size_t maxlen)
 {
   size_t len;
@@ -818,6 +923,12 @@ size_t BLI_strnlen(const char *s, const size_t maxlen)
   return len;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name String Case Conversion
+ * \{ */
+
 void BLI_str_tolower_ascii(char *str, const size_t len)
 {
   size_t i;
@@ -840,6 +951,12 @@ void BLI_str_toupper_ascii(char *str, const size_t len)
   }
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name String Stripping
+ * \{ */
+
 void BLI_str_rstrip(char *str)
 {
   for (int i = (int)strlen(str) - 1; i >= 0; i--) {
@@ -872,66 +989,11 @@ int BLI_str_rstrip_float_zero(char *str, const char pad)
   return totstrip;
 }
 
-int BLI_str_index_in_array_n(const char *__restrict str,
-                             const char **__restrict str_array,
-                             const int str_array_len)
-{
-  int index;
-  const char **str_iter = str_array;
-
-  for (index = 0; index < str_array_len; str_iter++, index++) {
-    if (STREQ(str, *str_iter)) {
-      return index;
-    }
-  }
-  return -1;
-}
-
-int BLI_str_index_in_array(const char *__restrict str, const char **__restrict str_array)
-{
-  int index;
-  const char **str_iter = str_array;
-
-  for (index = 0; *str_iter; str_iter++, index++) {
-    if (STREQ(str, *str_iter)) {
-      return index;
-    }
-  }
-  return -1;
-}
-
-bool BLI_str_startswith(const char *__restrict str, const char *__restrict start)
-{
-  for (; *str && *start; str++, start++) {
-    if (*str != *start) {
-      return false;
-    }
-  }
-
-  return (*start == '\0');
-}
-
-bool BLI_strn_endswith(const char *__restrict str, const char *__restrict end, size_t slength)
-{
-  size_t elength = strlen(end);
-
-  if (elength < slength) {
-    const char *iter = &str[slength - elength];
-    while (*iter) {
-      if (*iter++ != *end++) {
-        return false;
-      }
-    }
-    return true;
-  }
-  return false;
-}
+/** \} */
 
-bool BLI_str_endswith(const char *__restrict str, const char *__restrict end)
-{
-  const size_t slength = strlen(str);
-  return BLI_strn_endswith(str, end, slength);
-}
+/* -------------------------------------------------------------------- */
+/** \name String Split (Partition)
+ * \{ */
 
 size_t BLI_str_partition(const char *str, const char delim[], const char **sep, const char **suf)
 {
@@ -993,6 +1055,47 @@ size_t BLI_str_partition_ex(const char *str,
   return end ? (size_t)(end - str) : strlen(str);
 }
 
+int BLI_string_find_split_words(
+    const char *str, const size_t len, const char delim, int r_words[][2], int words_max)
+{
+  int n = 0, i;
+  bool charsearch = true;
+
+  /* Skip leading spaces */
+  for (i = 0; (i < len) && (str[i] != '\0'); i++) {
+    if (str[i] != delim) {
+      break;
+    }
+  }
+
+  for (; (i < len) && (str[i] != '\0') && (n < words_max); i++) {
+    if ((str[i] != delim) && (charsearch == true)) {
+      r_words[n][0] = i;
+      charsearch = false;
+    }
+    else {
+      if ((str[i] == delim) && (charsearch == false)) {
+        r_words[n][1] = i - r_words[n][0];
+        n++;
+        charsearch = true;
+      }
+    }
+  }
+
+  if (charsearch == false) {
+    r_words[n][1] = i - r_words[n][0];
+    n++;
+  }
+
+  return n;
+}
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name String Formatting (Numeric)
+ * \{ */
+
 static size_t BLI_str_format_int_grouped_ex(char src[16], char dst[16], int num_len)
 {
   char *p_src = src;
@@ -1082,37 +1185,4 @@ void BLI_str_format_attribute_domain_size(char dst[7], int number_to_format)
   BLI_snprintf(dst, dst_len, "%.*f%s", decimals, number_to_format_converted, units[order]);
 }
 
-int BLI_string_find_split_words(
-    const char *str, const size_t len, const char delim, int r_words[][2], int words_max)
-{
-  int n = 0, i;
-  bool charsearch = true;
-
-  /* Skip leading spaces */
-  for (i = 0; (i < len) && (str[i] != '\0'); i++) {
-    if (str[i] != delim) {
-      break;
-    }
-  }
-
-  for (; (i < len) && (str[i] != '\0') && (n < words_max); i++) {
-    if ((str[i] != delim) && (charsearch == true)) {
-      r_words[n][0] = i;
-      charsearch = false;
-    }
-    else {
-      if ((str[i] == delim) && (charsearch == false)) {
-        r_words[n][1] = i - r_words[n][0];
-        n++;
-        charsearch = true;
-      }
-    }
-  }
-
-  if (charsearch == false) {
-    r_words[n][1] = i - r_words[n][0];
-    n++;
-  }
-
-  return n;
-}
+/** \} */
diff --git a/source/blender/blenlib/tests/BLI_color_test.cc b/source/blender/blenlib/tests/BLI_color_test.cc
index a91c743b133..5194d8048bf 100644
--- a/source/blender/blenlib/tests/BLI_color_test.cc
+++ b/source/blender/blenlib/tests/BLI_color_test.cc
@@ -6,8 +6,8 @@
 
 namespace blender::tests {
 
-/**
- * \name Conversions
+/* -------------------------------------------------------------------- */
+/** \name Conversions
  * \{ */
 
 TEST(color, ThemeByteToFloat)