Cleanup: move public doc-strings into headers for various API's

Some doc-strings were skipped because of blank-lines between
the doc-string and the symbol and needed to be moved manually.

- 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.

Ref T92709

3 files changed, 43 insertions, 42 deletions

diff --git a/source/blender/bmesh/intern/bmesh_construct.c b/source/blender/bmesh/intern/bmesh_construct.c
index 789165f2e40..5a9d1ba7bc4 100644
--- a/source/blender/bmesh/intern/bmesh_construct.c
+++ b/source/blender/bmesh/intern/bmesh_construct.c
@@ -391,9 +391,6 @@ static void bm_face_attrs_copy(
   f_dst->mat_nr = f_src->mat_nr;
 }
 
-/* BMESH_TODO: Special handling for hide flags? */
-/* BMESH_TODO: swap src/dst args, everywhere else in bmesh does other way round */
-
 void BM_elem_attrs_copy_ex(BMesh *bm_src,
                            BMesh *bm_dst,
                            const void *ele_src_v,
@@ -401,6 +398,9 @@ void BM_elem_attrs_copy_ex(BMesh *bm_src,
                            const char hflag_mask,
                            const uint64_t cd_mask_exclude)
 {
+  /* TODO: Special handling for hide flags? */
+  /* TODO: swap src/dst args, everywhere else in bmesh does other way round. */
+
   const BMHeader *ele_src = ele_src_v;
   BMHeader *ele_dst = ele_dst_v;
 
diff --git a/source/blender/bmesh/intern/bmesh_query.c b/source/blender/bmesh/intern/bmesh_query.c
index 7936ca18f5c..fe2142670a2 100644
--- a/source/blender/bmesh/intern/bmesh_query.c
+++ b/source/blender/bmesh/intern/bmesh_query.c
@@ -472,31 +472,6 @@ BMLoop *BM_edge_other_loop(BMEdge *e, BMLoop *l)
   return l_other;
 }
 
-/**
- * Utility function to step around a fan of loops,
- * using an edge to mark the previous side.
- *
- * \note all edges must be manifold,
- * once a non manifold edge is hit, return NULL.
- *
- * <pre>
- *                ,.,-->|
- *            _,-'      |
- *          ,'          | (notice how 'e_step'
- *         /            |  and 'l' define the
- *        /             |  direction the arrow
- *       |     return   |  points).
- *       |     loop --> |
- * ---------------------+---------------------
- *         ^      l --> |
- *         |            |
- *  assign e_step       |
- *                      |
- *   begin e_step ----> |
- *                      |
- * </pre>
- */
-
 BMLoop *BM_vert_step_fan_loop(BMLoop *l, BMEdge **e_step)
 {
   BMEdge *e_prev = *e_step;
@@ -1420,18 +1395,6 @@ float BM_edge_calc_face_angle_signed(const BMEdge *e)
   return BM_edge_calc_face_angle_signed_ex(e, DEG2RADF(90.0f));
 }
 
-/**
- * \brief BMESH EDGE/FACE TANGENT
- *
- * Calculate the tangent at this loop corner or fallback to the face normal on straight lines.
- * This vector always points inward into the face.
- *
- * \brief BM_edge_calc_face_tangent
- * \param e:
- * \param e_loop: The loop to calculate the tangent at,
- * used to get the face and winding direction.
- * \param r_tangent: The loop corner tangent to set
- */
 void BM_edge_calc_face_tangent(const BMEdge *e, const BMLoop *e_loop, float r_tangent[3])
 {
   float tvec[3];
@@ -2142,7 +2105,6 @@ double BM_mesh_calc_volume(BMesh *bm, bool is_signed)
   return vol;
 }
 
-/* NOTE: almost duplicate of #BM_mesh_calc_edge_groups, keep in sync. */
 int BM_mesh_calc_face_groups(BMesh *bm,
                              int *r_groups_array,
                              int (**r_group_index)[2],
@@ -2152,6 +2114,8 @@ int BM_mesh_calc_face_groups(BMesh *bm,
                              const char hflag_test,
                              const char htype_step)
 {
+  /* NOTE: almost duplicate of #BM_mesh_calc_edge_groups, keep in sync. */
+
 #ifdef DEBUG
   int group_index_len = 1;
 #else
@@ -2290,7 +2254,6 @@ int BM_mesh_calc_face_groups(BMesh *bm,
   return group_curr;
 }
 
-/* NOTE: almost duplicate of #BM_mesh_calc_face_groups, keep in sync. */
 int BM_mesh_calc_edge_groups(BMesh *bm,
                              int *r_groups_array,
                              int (**r_group_index)[2],
@@ -2298,6 +2261,8 @@ int BM_mesh_calc_edge_groups(BMesh *bm,
                              void *user_data,
                              const char hflag_test)
 {
+  /* NOTE: almost duplicate of #BM_mesh_calc_face_groups, keep in sync. */
+
 #ifdef DEBUG
   int group_index_len = 1;
 #else
diff --git a/source/blender/bmesh/intern/bmesh_query.h b/source/blender/bmesh/intern/bmesh_query.h
index 9c4dc169589..261ecefdd47 100644
--- a/source/blender/bmesh/intern/bmesh_query.h
+++ b/source/blender/bmesh/intern/bmesh_query.h
@@ -173,6 +173,30 @@ BMLoop *BM_loop_other_vert_loop_by_edge(BMLoop *l, BMEdge *e) ATTR_WARN_UNUSED_R
  * </pre>
  */
 BMLoop *BM_loop_other_vert_loop(BMLoop *l, BMVert *v) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
+/**
+ * Utility function to step around a fan of loops,
+ * using an edge to mark the previous side.
+ *
+ * \note all edges must be manifold,
+ * once a non manifold edge is hit, return NULL.
+ *
+ * \code{.unparsed}
+ *                ,.,-->|
+ *            _,-'      |
+ *          ,'          | (notice how 'e_step'
+ *         /            |  and 'l' define the
+ *        /             |  direction the arrow
+ *       |     return   |  points).
+ *       |     loop --> |
+ * ---------------------+---------------------
+ *         ^      l --> |
+ *         |            |
+ *  assign e_step       |
+ *                      |
+ *   begin e_step ----> |
+ *                      |
+ * \endcode
+ */
 BMLoop *BM_vert_step_fan_loop(BMLoop *l, BMEdge **e_step) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
 
 /**
@@ -470,6 +494,18 @@ float BM_edge_calc_face_angle_with_imat3(const BMEdge *e,
                                          const float imat3[3][3]) ATTR_WARN_UNUSED_RESULT
     ATTR_NONNULL();
 float BM_edge_calc_face_angle_signed(const BMEdge *e) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
+/**
+ * \brief BMESH EDGE/FACE TANGENT
+ *
+ * Calculate the tangent at this loop corner or fallback to the face normal on straight lines.
+ * This vector always points inward into the face.
+ *
+ * \brief BM_edge_calc_face_tangent
+ * \param e:
+ * \param e_loop: The loop to calculate the tangent at,
+ * used to get the face and winding direction.
+ * \param r_tangent: The loop corner tangent to set
+ */
 void BM_edge_calc_face_tangent(const BMEdge *e, const BMLoop *e_loop, float r_tangent[3])
     ATTR_NONNULL();
 float BM_vert_calc_edge_angle(const BMVert *v) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();