Docs: use doxygen formatting for BLI

Differentiate doc-strings from title/section text.

30 files changed, 116 insertions, 77 deletions

diff --git a/source/blender/blenlib/BLI_assert.h b/source/blender/blenlib/BLI_assert.h
index 6019f0f3566..e32a19cfc25 100644
--- a/source/blender/blenlib/BLI_assert.h
+++ b/source/blender/blenlib/BLI_assert.h
@@ -30,6 +30,7 @@ extern "C" {
 #endif
 
 /* Utility functions. */
+
 void _BLI_assert_print_pos(const char *file, const int line, const char *function, const char *id);
 void _BLI_assert_print_extra(const char *str);
 void _BLI_assert_print_backtrace(void);
diff --git a/source/blender/blenlib/BLI_color.hh b/source/blender/blenlib/BLI_color.hh
index d93bd7f6f76..dce625777b9 100644
--- a/source/blender/blenlib/BLI_color.hh
+++ b/source/blender/blenlib/BLI_color.hh
@@ -73,27 +73,27 @@ namespace blender {
  * - Add non RGB spaces/storages ColorXyz.
  */
 
-/* Enumeration containing the different alpha modes. */
+/** Enumeration containing the different alpha modes. */
 enum class eAlpha {
-  /* Color and alpha are unassociated. */
+  /** Color and alpha are unassociated. */
   Straight,
-  /* Color and alpha are associated. */
+  /** Color and alpha are associated. */
   Premultiplied,
 };
 std::ostream &operator<<(std::ostream &stream, const eAlpha &space);
 
-/* Enumeration containing internal spaces. */
+/** Enumeration containing internal spaces. */
 enum class eSpace {
-  /* Blender theme color space (sRGB). */
+  /** Blender theme color space (sRGB). */
   Theme,
-  /* Blender internal scene linear color space (maps to SceneReference role in OCIO). */
+  /** Blender internal scene linear color space (maps to SceneReference role in OCIO). */
   SceneLinear,
-  /* Blender internal scene linear color space compressed to be stored in 4 uint8_t. */
+  /** Blender internal scene linear color space compressed to be stored in 4 uint8_t. */
   SceneLinearByteEncoded,
 };
 std::ostream &operator<<(std::ostream &stream, const eSpace &space);
 
-/* Template class to store RGBA values with different precision, space and alpha association. */
+/** Template class to store RGBA values with different precision, space and alpha association. */
 template<typename ChannelStorageType, eSpace Space, eAlpha Alpha> class ColorRGBA {
  public:
   ChannelStorageType r, g, b, a;
@@ -153,11 +153,13 @@ template<typename ChannelStorageType, eSpace Space, eAlpha Alpha> class ColorRGB
 };
 
 /* Forward declarations of concrete color classes. */
+
 template<eAlpha Alpha> class ColorSceneLinear4f;
 template<eAlpha Alpha> class ColorSceneLinearByteEncoded4b;
 template<typename ChannelStorageType> class ColorTheme4;
 
 /* Forward declaration of precision conversion methods. */
+
 BLI_INLINE ColorTheme4<float> BLI_color_convert_to_theme4f(const ColorTheme4<uint8_t> &srgb4b);
 BLI_INLINE ColorTheme4<uint8_t> BLI_color_convert_to_theme4b(const ColorTheme4<float> &srgb4f);
 
@@ -354,6 +356,7 @@ BLI_color_convert_to_theme4b(const ColorSceneLinear4f<eAlpha::Straight> &scene_l
 }
 
 /* Internal roles. For convenience to shorten the type names and hide complexity. */
+
 using ColorGeometry4f = ColorSceneLinear4f<eAlpha::Premultiplied>;
 using ColorGeometry4b = ColorSceneLinearByteEncoded4b<eAlpha::Premultiplied>;
 
diff --git a/source/blender/blenlib/BLI_compiler_compat.h b/source/blender/blenlib/BLI_compiler_compat.h
index bd8f84cedd6..023fea3853e 100644
--- a/source/blender/blenlib/BLI_compiler_compat.h
+++ b/source/blender/blenlib/BLI_compiler_compat.h
@@ -34,7 +34,7 @@
 
 #if (defined(__GNUC__) || defined(__clang__)) && defined(__cplusplus)
 extern "C++" {
-/* Some magic to be sure we don't have reference in the type. */
+/** Some magic to be sure we don't have reference in the type. */
 template<typename T> static inline T decltype_helper(T x)
 {
   return x;
diff --git a/source/blender/blenlib/BLI_delaunay_2d.h b/source/blender/blenlib/BLI_delaunay_2d.h
index 658dcadadce..db0df95499f 100644
--- a/source/blender/blenlib/BLI_delaunay_2d.h
+++ b/source/blender/blenlib/BLI_delaunay_2d.h
@@ -222,7 +222,7 @@ void BLI_delaunay_2d_cdt_free(CDT_result *result);
 
 namespace blender::meshintersect {
 
-/* vec2<Arith_t> is a 2d vector with Arith_t as the type for coordinates. */
+/** #vec2<Arith_t> is a 2d vector with #Arith_t as the type for coordinates. */
 template<typename Arith_t> struct vec2_impl;
 template<> struct vec2_impl<double> {
   typedef double2 type;
diff --git a/source/blender/blenlib/BLI_dlrbTree.h b/source/blender/blenlib/BLI_dlrbTree.h
index 72f18244d5b..3cf849efaef 100644
--- a/source/blender/blenlib/BLI_dlrbTree.h
+++ b/source/blender/blenlib/BLI_dlrbTree.h
@@ -40,7 +40,7 @@ extern "C" {
 /** \name Base Structs
  * \{ */
 
-/* Basic Layout for a Node */
+/** Basic Layout for a Node. */
 typedef struct DLRBT_Node {
   /* ListBase capabilities */
   struct DLRBT_Node *next, *prev;
@@ -53,7 +53,7 @@ typedef struct DLRBT_Node {
   /* ... for nice alignment, next item should usually be a char too... */
 } DLRBT_Node;
 
-/* Red/Black defines for tree_col */
+/** Red/Black defines for tree_col. */
 typedef enum eDLRBT_Colors {
   DLRBT_BLACK = 0,
   DLRBT_RED,
@@ -61,7 +61,7 @@ typedef enum eDLRBT_Colors {
 
 /* -------- */
 
-/* The Tree Data */
+/** The Tree Data. */
 typedef struct DLRBT_Tree {
   /* ListBase capabilities */
   void *first, *last; /* these should be based on DLRBT_Node-s */
diff --git a/source/blender/blenlib/BLI_endian_switch.h b/source/blender/blenlib/BLI_endian_switch.h
index b512133b34c..e6ccbe4629a 100644
--- a/source/blender/blenlib/BLI_endian_switch.h
+++ b/source/blender/blenlib/BLI_endian_switch.h
@@ -30,6 +30,7 @@ extern "C" {
 #endif
 
 /* BLI_endian_switch_inline.h */
+
 BLI_INLINE void BLI_endian_switch_int16(short *val) ATTR_NONNULL(1);
 BLI_INLINE void BLI_endian_switch_uint16(unsigned short *val) ATTR_NONNULL(1);
 BLI_INLINE void BLI_endian_switch_int32(int *val) ATTR_NONNULL(1);
@@ -40,6 +41,7 @@ BLI_INLINE void BLI_endian_switch_uint64(uint64_t *val) ATTR_NONNULL(1);
 BLI_INLINE void BLI_endian_switch_double(double *val) ATTR_NONNULL(1);
 
 /* endian_switch.c */
+
 void BLI_endian_switch_int16_array(short *val, const int size) ATTR_NONNULL(1);
 void BLI_endian_switch_uint16_array(unsigned short *val, const int size) ATTR_NONNULL(1);
 void BLI_endian_switch_int32_array(int *val, const int size) ATTR_NONNULL(1);
diff --git a/source/blender/blenlib/BLI_endian_switch_inline.h b/source/blender/blenlib/BLI_endian_switch_inline.h
index ec4cfe4801a..31be7fd47e4 100644
--- a/source/blender/blenlib/BLI_endian_switch_inline.h
+++ b/source/blender/blenlib/BLI_endian_switch_inline.h
@@ -33,6 +33,7 @@ extern "C" {
  * use bit shifting instead. */
 
 /* *** 16 *** */
+
 BLI_INLINE void BLI_endian_switch_int16(short *val)
 {
   BLI_endian_switch_uint16((unsigned short *)val);
@@ -48,6 +49,7 @@ BLI_INLINE void BLI_endian_switch_uint16(unsigned short *val)
 }
 
 /* *** 32 *** */
+
 BLI_INLINE void BLI_endian_switch_int32(int *val)
 {
   BLI_endian_switch_uint32((unsigned int *)val);
@@ -67,6 +69,7 @@ BLI_INLINE void BLI_endian_switch_float(float *val)
 }
 
 /* *** 64 *** */
+
 BLI_INLINE void BLI_endian_switch_int64(int64_t *val)
 {
   BLI_endian_switch_uint64((uint64_t *)val);
diff --git a/source/blender/blenlib/BLI_filereader.h b/source/blender/blenlib/BLI_filereader.h
index da223cddf40..f232ad72cc4 100644
--- a/source/blender/blenlib/BLI_filereader.h
+++ b/source/blender/blenlib/BLI_filereader.h
@@ -47,7 +47,7 @@ typedef ssize_t (*FileReaderReadFn)(struct FileReader *reader, void *buffer, siz
 typedef off64_t (*FileReaderSeekFn)(struct FileReader *reader, off64_t offset, int whence);
 typedef void (*FileReaderCloseFn)(struct FileReader *reader);
 
-/* General structure for all FileReaders, implementations add custom fields at the end. */
+/** General structure for all #FileReaders, implementations add custom fields at the end. */
 typedef struct FileReader {
   FileReaderReadFn read;
   FileReaderSeekFn seek;
@@ -64,16 +64,16 @@ typedef struct FileReader {
  * take over the base FileReader and will clean it up when their clean() is called.
  */
 
-/* Create FileReader from raw file descriptor. */
+/** Create #FileReader from raw file descriptor. */
 FileReader *BLI_filereader_new_file(int filedes) ATTR_WARN_UNUSED_RESULT;
-/* Create FileReader from raw file descriptor using memory-mapped IO. */
+/** Create #FileReader from raw file descriptor using memory-mapped IO. */
 FileReader *BLI_filereader_new_mmap(int filedes) ATTR_WARN_UNUSED_RESULT;
-/* Create FileReader from a region of memory. */
+/** Create #FileReader from a region of memory. */
 FileReader *BLI_filereader_new_memory(const void *data, size_t len) ATTR_WARN_UNUSED_RESULT
     ATTR_NONNULL();
-/* Create FileReader from applying `Zstd` decompression on an underlying file. */
+/** Create #FileReader from applying `Zstd` decompression on an underlying file. */
 FileReader *BLI_filereader_new_zstd(FileReader *base) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
-/* Create FileReader from applying `Gzip` decompression on an underlying file. */
+/** Create #FileReader from applying `Gzip` decompression on an underlying file. */
 FileReader *BLI_filereader_new_gzip(FileReader *base) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
 
 #ifdef __cplusplus
diff --git a/source/blender/blenlib/BLI_ghash.h b/source/blender/blenlib/BLI_ghash.h
index 0194f9aad40..fca705535a3 100644
--- a/source/blender/blenlib/BLI_ghash.h
+++ b/source/blender/blenlib/BLI_ghash.h
@@ -450,7 +450,7 @@ void *BLI_gset_pop_key(GSet *gs, const void *key) ATTR_WARN_UNUSED_RESULT;
 
 /* rely on inline api for now */
 
-/* so we can cast but compiler sees as different */
+/** Use a GSet specific type so we can cast but compiler sees as different */
 typedef struct GSetIterator {
   GHashIterator _ghi
 #if defined(__GNUC__) && !defined(__clang__)
diff --git a/source/blender/blenlib/BLI_kdtree_impl.h b/source/blender/blenlib/BLI_kdtree_impl.h
index 26a22fc2ac4..35dbf141c92 100644
--- a/source/blender/blenlib/BLI_kdtree_impl.h
+++ b/source/blender/blenlib/BLI_kdtree_impl.h
@@ -74,7 +74,7 @@ int BLI_kdtree_nd_(calc_duplicates_fast)(const KDTree *tree,
 
 int BLI_kdtree_nd_(deduplicate)(KDTree *tree);
 
-/* Versions of find/range search that take a squared distance callback to support bias. */
+/** Versions of find/range search that take a squared distance callback to support bias. */
 int BLI_kdtree_nd_(find_nearest_n_with_len_squared_cb)(
     const KDTree *tree,
     const float co[KD_DIMS],
diff --git a/source/blender/blenlib/BLI_linklist_lockfree.h b/source/blender/blenlib/BLI_linklist_lockfree.h
index 142fa1cf243..d2083bdd44e 100644
--- a/source/blender/blenlib/BLI_linklist_lockfree.h
+++ b/source/blender/blenlib/BLI_linklist_lockfree.h
@@ -48,18 +48,19 @@ typedef void (*LockfreeeLinkNodeFreeFP)(void *link);
 /* NOTE: These functions are NOT safe for use from threads. */
 /* NOTE: !!! I REPEAT: DO NOT USE THEM WITHOUT EXTERNAL LOCK !!! */
 
-/* Make list ready for lock-free access. */
+/** Make list ready for lock-free access. */
 void BLI_linklist_lockfree_init(LockfreeLinkList *list);
 
-/* Completely free the whole list, it is NOT re-usable after this. */
+/** Completely free the whole list, it is NOT re-usable after this. */
 void BLI_linklist_lockfree_free(LockfreeLinkList *list, LockfreeeLinkNodeFreeFP free_func);
 
-/* Remove all the elements from the list, keep it usable for further
- * inserts.
+/**
+ * Remove all the elements from the list, keep it usable for further inserts.
  */
 void BLI_linklist_lockfree_clear(LockfreeLinkList *list, LockfreeeLinkNodeFreeFP free_func);
 
-/* Begin iteration of lock-free linked list, starting with a
+/**
+ * Begin iteration of lock-free linked list, starting with a
  * first user=defined node. Will ignore the dummy node.
  */
 LockfreeLinkNode *BLI_linklist_lockfree_begin(LockfreeLinkList *list);
diff --git a/source/blender/blenlib/BLI_math_base.h b/source/blender/blenlib/BLI_math_base.h
index 83822481112..6c82bd89e64 100644
--- a/source/blender/blenlib/BLI_math_base.h
+++ b/source/blender/blenlib/BLI_math_base.h
@@ -76,8 +76,7 @@
 
 #if defined(__GNUC__)
 #  define NAN_FLT __builtin_nanf("")
-#else
-/* evil quiet NaN definition */
+#else /* evil quiet NaN definition */
 static const int NAN_INT = 0x7FC00000;
 #  define NAN_FLT (*((float *)(&NAN_INT)))
 #endif
@@ -97,7 +96,8 @@ extern "C" {
 
 /******************************* Float ******************************/
 
-/* powf is really slow for raising to integer powers. */
+/* `powf` is really slow for raising to integer powers. */
+
 MINLINE float pow2f(float x);
 MINLINE float pow3f(float x);
 MINLINE float pow4f(float x);
diff --git a/source/blender/blenlib/BLI_math_bits.h b/source/blender/blenlib/BLI_math_bits.h
index e881f1a0e4e..70a54879446 100644
--- a/source/blender/blenlib/BLI_math_bits.h
+++ b/source/blender/blenlib/BLI_math_bits.h
@@ -28,24 +28,29 @@ extern "C" {
 #endif
 
 /* Search the value from LSB to MSB for a set bit. Returns index of this bit. */
+
 MINLINE int bitscan_forward_i(int a);
 MINLINE unsigned int bitscan_forward_uint(unsigned int a);
 MINLINE unsigned int bitscan_forward_uint64(unsigned long long a);
 
 /* Similar to above, but also clears the bit. */
+
 MINLINE int bitscan_forward_clear_i(int *a);
 MINLINE unsigned int bitscan_forward_clear_uint(unsigned int *a);
 
 /* Search the value from MSB to LSB for a set bit. Returns index of this bit. */
+
 MINLINE int bitscan_reverse_i(int a);
 MINLINE unsigned int bitscan_reverse_uint(unsigned int a);
 MINLINE unsigned int bitscan_reverse_uint64(unsigned long long a);
 
 /* Similar to above, but also clears the bit. */
+
 MINLINE int bitscan_reverse_clear_i(int *a);
 MINLINE unsigned int bitscan_reverse_clear_uint(unsigned int *a);
 
 /* NOTE: Those functions returns 2 to the power of index of highest order bit. */
+
 MINLINE unsigned int highest_order_bit_uint(unsigned int n);
 MINLINE unsigned short highest_order_bit_s(unsigned short n);
 
diff --git a/source/blender/blenlib/BLI_math_geom.h b/source/blender/blenlib/BLI_math_geom.h
index 55d118d17de..c2a5ffafa64 100644
--- a/source/blender/blenlib/BLI_math_geom.h
+++ b/source/blender/blenlib/BLI_math_geom.h
@@ -441,7 +441,9 @@ void isect_seg_seg_v3(const float a0[3],
                       float r_a[3],
                       float r_b[3]);
 
-/* intersect Line-Line, shorts */
+/**
+ * Intersect Line-Line, integer.
+ */
 int isect_seg_seg_v2_int(const int v1[2], const int v2[2], const int v3[2], const int v4[2]);
 /**
  * Get intersection point of two 2D segments.
@@ -929,7 +931,7 @@ void interp_weights_quad_v3(float w[4],
 void interp_weights_poly_v3(float w[], float v[][3], const int n, const float co[3]);
 void interp_weights_poly_v2(float w[], float v[][2], const int n, const float co[2]);
 
-/* (x1, v1)(t1=0)------(x2, v2)(t2=1), 0<t<1 --> (x, v)(t) */
+/** `(x1, v1)(t1=0)------(x2, v2)(t2=1), 0<t<1 --> (x, v)(t)`. */
 void interp_cubic_v3(float x[3],
                      float v[3],
                      const float x1[3],
diff --git a/source/blender/blenlib/BLI_math_matrix.h b/source/blender/blenlib/BLI_math_matrix.h
index 3d8fe6f564a..90b74e2f504 100644
--- a/source/blender/blenlib/BLI_math_matrix.h
+++ b/source/blender/blenlib/BLI_math_matrix.h
@@ -56,16 +56,18 @@ void copy_m4_m2(float m1[4][4], const float m2[2][2]);
 void copy_m4_m4_db(double m1[4][4], const double m2[4][4]);
 
 /* double->float */
+
 void copy_m3_m3d(float m1[3][3], const double m2[3][3]);
 
 /* float->double */
+
 void copy_m3d_m3(double m1[3][3], const float m2[3][3]);
 void copy_m4d_m4(double m1[4][4], const float m2[4][4]);
 
 void swap_m3m3(float m1[3][3], float m2[3][3]);
 void swap_m4m4(float m1[4][4], float m2[4][4]);
 
-/* Build index shuffle matrix */
+/** Build index shuffle matrix. */
 void shuffle_m4(float R[4][4], const int index[4]);
 
 /** \} */
@@ -112,7 +114,8 @@ void mul_m4db_m4db_m4fl_uniq(double R[4][4], const double A[4][4], const float B
 void mul_m4_m4_pre(float R[4][4], const float A[4][4]);
 void mul_m4_m4_post(float R[4][4], const float B[4][4]);
 
-/* mul_m3_series */
+/* Implement #mul_m3_series macro. */
+
 void _va_mul_m3_series_3(float R[3][3], const float M1[3][3], const float M2[3][3]) ATTR_NONNULL();
 void _va_mul_m3_series_4(float R[3][3],
                          const float M1[3][3],
@@ -153,7 +156,9 @@ void _va_mul_m3_series_9(float R[3][3],
                          const float M6[3][3],
                          const float M7[3][3],
                          const float M8[3][3]) ATTR_NONNULL();
-/* mul_m4_series */
+
+/* Implement #mul_m4_series macro. */
+
 void _va_mul_m4_series_3(float R[4][4], const float M1[4][4], const float M2[4][4]) ATTR_NONNULL();
 void _va_mul_m4_series_4(float R[4][4],
                          const float M1[4][4],
@@ -266,11 +271,13 @@ bool invert_m4_m4(float R[4][4], const float A[4][4]);
  */
 bool invert_m4_m4_fallback(float R[4][4], const float A[4][4]);
 
-/* double arithmetic (mixed float/double) */
+/* Double arithmetic (mixed float/double). */
+
 void mul_m4_v4d(const float M[4][4], double r[4]);
 void mul_v4d_m4v4d(double r[4], const float M[4][4], const double v[4]);
 
-/* double matrix functions (no mixing types) */
+/* Double matrix functions (no mixing types). */
+
 void mul_v3_m3v3_db(double r[3], const double M[3][3], const double a[3]);
 void mul_m3_v3_db(const double M[3][3], double r[3]);
 
@@ -282,7 +289,9 @@ void mul_m3_v3_db(const double M[3][3], double r[3]);
 
 void transpose_m3(float R[3][3]);
 void transpose_m3_m3(float R[3][3], const float M[3][3]);
-/* seems obscure but in-fact a common operation */
+/**
+ * \note Seems obscure but in-fact a common operation.
+ */
 void transpose_m3_m4(float R[3][3], const float M[4][4]);
 void transpose_m4(float R[4][4]);
 void transpose_m4_m4(float R[4][4], const float M[4][4]);
diff --git a/source/blender/blenlib/BLI_math_rotation.h b/source/blender/blenlib/BLI_math_rotation.h
index 5e72d502262..8106251684d 100644
--- a/source/blender/blenlib/BLI_math_rotation.h
+++ b/source/blender/blenlib/BLI_math_rotation.h
@@ -57,7 +57,8 @@ void unit_axis_angle(float axis[3], float *angle);
 void unit_qt(float q[4]);
 void copy_qt_qt(float q[4], const float a[4]);
 
-/* arithmetic */
+/* Arithmetic. */
+
 void mul_qt_qtqt(float q[4], const float a[4], const float b[4]);
 /**
  * \note
@@ -106,7 +107,8 @@ float dot_qtqt(const float a[4], const float b[4]);
 float normalize_qt(float q[4]);
 float normalize_qt_qt(float r[4], const float q[4]);
 
-/* comparison */
+/* Comparison. */
+
 bool is_zero_qt(const float q[4]);
 
 /* interpolation */
@@ -122,7 +124,8 @@ void interp_dot_slerp(const float t, const float cosom, float r_w[2]);
 void interp_qt_qtqt(float q[4], const float a[4], const float b[4], const float t);
 void add_qt_qtqt(float q[4], const float a[4], const float b[4], const float t);
 
-/* conversion */
+/* Conversion. */
+
 void quat_to_mat3(float mat[3][3], const float q[4]);
 void quat_to_mat4(float mat[4][4], const float q[4]);
 
@@ -188,7 +191,8 @@ float angle_signed_qtqt(const float q1[4], const float q2[4]);
  */
 void mat3_to_quat_is_ok(float q[4], const float mat[3][3]);
 
-/* other */
+/* Other. */
+
 void print_qt(const char *str, const float q[4]);
 
 #define print_qt_id(q) print_qt(STRINGIFY(q), q)
@@ -199,7 +203,8 @@ void print_qt(const char *str, const float q[4]);
 /** \name Axis Angle
  * \{ */
 
-/* conversion */
+/* Conversion. */
+
 void axis_angle_normalized_to_quat(float r[4], const float axis[3], const float angle);
 void axis_angle_to_quat(float r[4], const float axis[3], const float angle);
 /**
@@ -271,32 +276,25 @@ void expmap_to_quat(float r[4], const float expmap[3]);
 /** \name XYZ Eulers
  * \{ */
 
-/* XYZ order. */
 void eul_to_quat(float quat[4], const float eul[3]);
-/* XYZ order */
 void eul_to_mat3(float mat[3][3], const float eul[3]);
-/* XYZ order */
 void eul_to_mat4(float mat[4][4], const float eul[3]);
 
-/* XYZ order */
 void mat3_normalized_to_eul(float eul[3], const float mat[3][3]);
-/* XYZ order */
 void mat4_normalized_to_eul(float eul[3], const float mat[4][4]);
 void mat3_to_eul(float eul[3], const float mat[3][3]);
 void mat4_to_eul(float eul[3], const float mat[4][4]);
-/* XYZ order */
 void quat_to_eul(float eul[3], const float quat[4]);
 
-/* XYZ order */
 void mat3_normalized_to_compatible_eul(float eul[3], const float old[3], float mat[3][3]);
 void mat3_to_compatible_eul(float eul[3], const float old[3], float mat[3][3]);
 void quat_to_compatible_eul(float eul[3], const float oldrot[3], const float quat[4]);
-/* order independent! */
-void compatible_eul(float eul[3], const float old[3]);
-
-/* XYZ order */
 void rotate_eul(float eul[3], const char axis, const float angle);
 
+/* Order independent. */
+
+void compatible_eul(float eul[3], const float old[3]);
+
 void add_eul_euleul(float r_eul[3], float a[3], float b[3], const short order);
 void sub_eul_euleul(float r_eul[3], float a[3], float b[3], const short order);
 
diff --git a/source/blender/blenlib/BLI_math_vector.h b/source/blender/blenlib/BLI_math_vector.h
index 8f955076baf..61090e30f7b 100644
--- a/source/blender/blenlib/BLI_math_vector.h
+++ b/source/blender/blenlib/BLI_math_vector.h
@@ -79,7 +79,9 @@ MINLINE void copy_v4_v4_char(char r[4], const char a[4]);
 MINLINE void copy_v2_v2_short(short r[2], const short a[2]);
 MINLINE void copy_v3_v3_short(short r[3], const short a[3]);
 MINLINE void copy_v4_v4_short(short r[4], const short a[4]);
+
 /* int */
+
 MINLINE void zero_v3_int(int r[3]);
 MINLINE void copy_v2_v2_int(int r[2], const int a[2]);
 MINLINE void copy_v3_v3_int(int r[3], const int a[3]);
diff --git a/source/blender/blenlib/BLI_mempool.h b/source/blender/blenlib/BLI_mempool.h
index d6abae36e00..a3cf2a77646 100644
--- a/source/blender/blenlib/BLI_mempool.h
+++ b/source/blender/blenlib/BLI_mempool.h
@@ -103,14 +103,14 @@ void BLI_mempool_set_memory_debug(void);
  * \note this may easy to produce bugs with.
  */
 
-/* Private structure. */
+/**  \note Private structure. */
 typedef struct BLI_mempool_iter {
   BLI_mempool *pool;
   struct BLI_mempool_chunk *curchunk;
   unsigned int curindex;
 } BLI_mempool_iter;
 
-/* flag */
+/** #BLI_mempool.flag */
 enum {
   BLI_MEMPOOL_NOP = 0,
   /** allow iterating on this mempool.
diff --git a/source/blender/blenlib/BLI_quadric.h b/source/blender/blenlib/BLI_quadric.h
index fdb7d1e67ac..450653a20ea 100644
--- a/source/blender/blenlib/BLI_quadric.h
+++ b/source/blender/blenlib/BLI_quadric.h
@@ -31,18 +31,21 @@ typedef struct Quadric {
   double a2, ab, ac, ad, b2, bc, bd, c2, cd, d2;
 } Quadric;
 
-/* conversion */
+/* Conversion. */
+
 void BLI_quadric_from_plane(Quadric *q, const double v[4]);
 void BLI_quadric_to_vector_v3(const Quadric *q, double v[3]);
 
 void BLI_quadric_clear(Quadric *q);
 
-/* math */
+/* Math operations. */
+
 void BLI_quadric_add_qu_qu(Quadric *a, const Quadric *b);
 void BLI_quadric_add_qu_ququ(Quadric *r, const Quadric *a, const Quadric *b);
 void BLI_quadric_mul(Quadric *a, const double scalar);
 
-/* solve */
+/* Solve. */
+
 double BLI_quadric_evaluate(const Quadric *q, const double v[3]);
 bool BLI_quadric_optimize(const Quadric *q, double v[3], const double epsilon);
 
diff --git a/source/blender/blenlib/BLI_scanfill.h b/source/blender/blenlib/BLI_scanfill.h
index 744d30397d4..ec7fa8f27a0 100644
--- a/source/blender/blenlib/BLI_scanfill.h
+++ b/source/blender/blenlib/BLI_scanfill.h
@@ -91,6 +91,7 @@ typedef struct ScanFillFace {
 } ScanFillFace;
 
 /* scanfill.c */
+
 struct ScanFillVert *BLI_scanfill_vert_add(ScanFillContext *sf_ctx, const float vec[3]);
 struct ScanFillEdge *BLI_scanfill_edge_add(ScanFillContext *sf_ctx,
                                            struct ScanFillVert *v1,
diff --git a/source/blender/blenlib/BLI_session_uuid.h b/source/blender/blenlib/BLI_session_uuid.h
index 887044e9b54..29e291add5a 100644
--- a/source/blender/blenlib/BLI_session_uuid.h
+++ b/source/blender/blenlib/BLI_session_uuid.h
@@ -33,18 +33,19 @@ extern "C" {
 
 #include "DNA_session_uuid_types.h"
 
-/* Generate new UUID which is unique throughout the Blender session. */
+/** Generate new UUID which is unique throughout the Blender session. */
 SessionUUID BLI_session_uuid_generate(void);
 
-/* Check whether the UUID is properly generated. */
+/** Check whether the UUID is properly generated. */
 bool BLI_session_uuid_is_generated(const SessionUUID *uuid);
 
-/* Check whether two UUIDs are identical. */
+/** Check whether two UUIDs are identical. */
 bool BLI_session_uuid_is_equal(const SessionUUID *lhs, const SessionUUID *rhs);
 
 uint64_t BLI_session_uuid_hash_uint64(const SessionUUID *uuid);
 
 /* Utility functions to make it possible to create GHash/GSet with UUID as a key. */
+
 uint BLI_session_uuid_ghash_hash(const void *uuid_v);
 bool BLI_session_uuid_ghash_compare(const void *lhs_v, const void *rhs_v);
 
diff --git a/source/blender/blenlib/BLI_sort.h b/source/blender/blenlib/BLI_sort.h
index 969816086e2..31a052eb79d 100644
--- a/source/blender/blenlib/BLI_sort.h
+++ b/source/blender/blenlib/BLI_sort.h
@@ -30,7 +30,7 @@
 #  define BLI_qsort_r qsort_r
 #endif
 
-/* Quick sort re-entrant */
+/** Quick sort (re-entrant). */
 typedef int (*BLI_sort_cmp_t)(const void *a, const void *b, void *ctx);
 
 void BLI_qsort_r(void *a, size_t n, size_t es, BLI_sort_cmp_t cmp, void *thunk)
diff --git a/source/blender/blenlib/BLI_sys_types.h b/source/blender/blenlib/BLI_sys_types.h
index 2740e3740f2..95327ff33b8 100644
--- a/source/blender/blenlib/BLI_sys_types.h
+++ b/source/blender/blenlib/BLI_sys_types.h
@@ -72,8 +72,8 @@ typedef uint64_t u_int64_t;
 #include <stddef.h> /* size_t define */
 
 #ifndef __cplusplus
+/* The <uchar.h> standard header is missing on some systems. */
 #  if defined(__APPLE__) || defined(__NetBSD__)
-/* The <uchar.h> standard header is missing on macOS. */
 typedef unsigned int char32_t;
 #  else
 #    include <uchar.h>
diff --git a/source/blender/blenlib/BLI_system.h b/source/blender/blenlib/BLI_system.h
index 0d5b2e6e2df..2e5e07d8407 100644
--- a/source/blender/blenlib/BLI_system.h
+++ b/source/blender/blenlib/BLI_system.h
@@ -30,7 +30,7 @@ int BLI_cpu_support_sse2(void);
 int BLI_cpu_support_sse41(void);
 void BLI_system_backtrace(FILE *fp);
 
-/* Get CPU brand, result is to be MEM_freeN()-ed. */
+/** Get CPU brand, result is to be MEM_freeN()-ed. */
 char *BLI_cpu_brand_string(void);
 
 /**
@@ -45,15 +45,19 @@ char *BLI_cpu_brand_string(void);
  */
 void BLI_hostname_get(char *buffer, size_t bufsize);
 
-/* Get maximum addressable memory in megabytes. */
+/** Get maximum addressable memory in megabytes. */
 size_t BLI_system_memory_max_in_megabytes(void);
+/** Get maximum addressable memory in megabytes (clamped to #INT_MAX). */
 int BLI_system_memory_max_in_megabytes_int(void);
 
 /* For `getpid`. */
 #ifdef WIN32
 #  define BLI_SYSTEM_PID_H <process.h>
 
-/* void* since we really do not want to drag Windows.h in to get the proper typedef. */
+/**
+ * \note Use `void *` for `exception` since we really do not want to drag Windows.h
+ * in to get the proper `typedef`.
+ */
 void BLI_windows_handle_exception(void *exception);
 
 #else
diff --git a/source/blender/blenlib/BLI_task.h b/source/blender/blenlib/BLI_task.h
index a67de2e2910..616237bc261 100644
--- a/source/blender/blenlib/BLI_task.h
+++ b/source/blender/blenlib/BLI_task.h
@@ -303,7 +303,7 @@ void BLI_task_parallel_mempool(struct BLI_mempool *mempool,
                                TaskParallelMempoolFunc func,
                                const TaskParallelSettings *settings);
 
-/* TODO(sergey): Think of a better place for this. */
+/** TODO(sergey): Think of a better place for this. */
 BLI_INLINE void BLI_parallel_range_settings_defaults(TaskParallelSettings *settings)
 {
   memset(settings, 0, sizeof(*settings));
diff --git a/source/blender/blenlib/BLI_threads.h b/source/blender/blenlib/BLI_threads.h
index 6e60430ea38..7bae16f25ef 100644
--- a/source/blender/blenlib/BLI_threads.h
+++ b/source/blender/blenlib/BLI_threads.h
@@ -31,7 +31,7 @@
 extern "C" {
 #endif
 
-/* for tables, button in UI, etc */
+/** For tables, button in UI, etc. */
 #define BLENDER_MAX_THREADS 1024
 
 struct ListBase;
diff --git a/source/blender/blenlib/BLI_timer.h b/source/blender/blenlib/BLI_timer.h
index c219b5502f3..b1cc8d5514f 100644
--- a/source/blender/blenlib/BLI_timer.h
+++ b/source/blender/blenlib/BLI_timer.h
@@ -29,8 +29,11 @@
 extern "C" {
 #endif
 
-/* ret < 0: the timer will be removed.
- * ret >= 0: the timer will be called again in ret seconds */
+/**
+ * \return A value of:
+ * - <  0: the timer will be removed.
+ * - >= 0: the timer will be called again in this number of seconds.
+ */
 typedef double (*BLI_timer_func)(uintptr_t uuid, void *user_data);
 typedef void (*BLI_timer_data_free)(uintptr_t uuid, void *user_data);
 
@@ -45,10 +48,10 @@ void BLI_timer_register(uintptr_t uuid,
 
 bool BLI_timer_is_registered(uintptr_t uuid);
 
-/* Returns False when the timer does not exist (anymore). */
+/** Returns False when the timer does not exist (anymore). */
 bool BLI_timer_unregister(uintptr_t uuid);
 
-/* Execute all registered functions that are due. */
+/** Execute all registered functions that are due. */
 void BLI_timer_execute(void);
 
 void BLI_timer_free(void);
diff --git a/source/blender/blenlib/BLI_virtual_array.hh b/source/blender/blenlib/BLI_virtual_array.hh
index 5103ac4b668..3ed9f14712e 100644
--- a/source/blender/blenlib/BLI_virtual_array.hh
+++ b/source/blender/blenlib/BLI_virtual_array.hh
@@ -44,7 +44,7 @@
 
 namespace blender {
 
-/* Forward declarations for generic virtual arrays. */
+/** Forward declarations for generic virtual arrays. */
 namespace fn {
 class GVArray;
 class GVMutableArray;
@@ -194,7 +194,7 @@ template<typename T> class VArrayImpl {
   }
 };
 
-/* Similar to #VArrayImpl, but adds methods that allow modifying the referenced elements. */
+/** Similar to #VArrayImpl, but adds methods that allow modifying the referenced elements. */
 template<typename T> class VMutableArrayImpl : public VArrayImpl<T> {
  public:
   using VArrayImpl<T>::VArrayImpl;
diff --git a/source/blender/blenlib/BLI_virtual_vector_array.hh b/source/blender/blenlib/BLI_virtual_vector_array.hh
index ab5afd2d80a..7672a76d5de 100644
--- a/source/blender/blenlib/BLI_virtual_vector_array.hh
+++ b/source/blender/blenlib/BLI_virtual_vector_array.hh
@@ -29,7 +29,7 @@
 
 namespace blender {
 
-/* A readonly virtual array of vectors. */
+/** A read-only virtual array of vectors. */
 template<typename T> class VVectorArray {
  protected:
   int64_t size_;
diff --git a/source/blender/blenlib/BLI_winstuff.h b/source/blender/blenlib/BLI_winstuff.h
index cbf1716602a..568734ee8a7 100644
--- a/source/blender/blenlib/BLI_winstuff.h
+++ b/source/blender/blenlib/BLI_winstuff.h
@@ -88,7 +88,7 @@ typedef SSIZE_T ssize_t;
 #  endif
 #endif
 
-/* Directory reading compatibility with UNIX. */
+/** Directory reading compatibility with UNIX. */
 struct dirent {
   int d_ino;
   int d_off;
@@ -96,7 +96,7 @@ struct dirent {
   char *d_name;
 };
 
-/* intentionally opaque to users */
+/** Intentionally opaque to users. */
 typedef struct __dirstream DIR;
 
 DIR *opendir(const char *path);
@@ -105,6 +105,7 @@ int closedir(DIR *dp);
 const char *dirname(char *path);
 
 /* Windows utility functions. */
+
 bool BLI_windows_register_blend_extension(const bool background);
 void BLI_windows_get_default_root_dir(char root_dir[4]);
 int BLI_windows_get_executable_dir(char *str);