Cleanup: move public doc-strings into headers for 'bmesh'

Some minor improvements to doc-strings too.

Ref T92709

23 files changed, 90 insertions, 88 deletions

diff --git a/source/blender/bmesh/tools/bmesh_beautify.c b/source/blender/bmesh/tools/bmesh_beautify.c
index d5c5063f2cb..b7cf9c88282 100644
--- a/source/blender/bmesh/tools/bmesh_beautify.c
+++ b/source/blender/bmesh/tools/bmesh_beautify.c
@@ -235,12 +235,6 @@ static float bm_edge_calc_rotate_beauty__angle(const float v1[3],
   return FLT_MAX;
 }
 
-/**
- * Assuming we have 2 triangles sharing an edge (2 - 4),
- * check if the edge running from (1 - 3) gives better results.
- *
- * \return (negative number means the edge can be rotated, lager == better).
- */
 float BM_verts_calc_rotate_beauty(const BMVert *v1,
                                   const BMVert *v2,
                                   const BMVert *v3,
@@ -374,9 +368,6 @@ static void bm_edge_update_beauty_cost(BMEdge *e,
 /* -------------------------------------------------------------------- */
 /* Beautify Fill */
 
-/**
- * \note This function sets the edge indices to invalid values.
- */
 void BM_mesh_beautify_fill(BMesh *bm,
                            BMEdge **edge_array,
                            const int edge_array_len,
diff --git a/source/blender/bmesh/tools/bmesh_beautify.h b/source/blender/bmesh/tools/bmesh_beautify.h
index d0fef828e7c..2e7950118c1 100644
--- a/source/blender/bmesh/tools/bmesh_beautify.h
+++ b/source/blender/bmesh/tools/bmesh_beautify.h
@@ -27,6 +27,9 @@ enum {
   EDGE_RESTRICT_DEGENERATE = (1 << 1),
 };
 
+/**
+ * \note This function sets the edge indices to invalid values.
+ */
 void BM_mesh_beautify_fill(BMesh *bm,
                            BMEdge **edge_array,
                            const int edge_array_len,
@@ -35,6 +38,12 @@ void BM_mesh_beautify_fill(BMesh *bm,
                            const short oflag_edge,
                            const short oflag_face);
 
+/**
+ * Assuming we have 2 triangles sharing an edge (2 - 4),
+ * check if the edge running from (1 - 3) gives better results.
+ *
+ * \return (negative number means the edge can be rotated, lager == better).
+ */
 float BM_verts_calc_rotate_beauty(const BMVert *v1,
                                   const BMVert *v2,
                                   const BMVert *v3,
diff --git a/source/blender/bmesh/tools/bmesh_bevel.c b/source/blender/bmesh/tools/bmesh_bevel.c
index 6cf3641fed2..2f471bf0b81 100644
--- a/source/blender/bmesh/tools/bmesh_bevel.c
+++ b/source/blender/bmesh/tools/bmesh_bevel.c
@@ -7443,18 +7443,6 @@ static void bevel_limit_offset(BevelParams *bp, BMesh *bm)
   }
 }
 
-/**
- * - Currently only bevels BM_ELEM_TAG'd verts and edges.
- *
- * - Newly created faces, edges, and verts are BM_ELEM_TAG'd too,
- *   the caller needs to ensure these are cleared before calling
- *   if its going to use this tag.
- *
- * - If limit_offset is set, adjusts offset down if necessary
- *   to avoid geometry collisions.
- *
- * \warning all tagged edges _must_ be manifold.
- */
 void BM_mesh_bevel(BMesh *bm,
                    const float offset,
                    const int offset_type,
diff --git a/source/blender/bmesh/tools/bmesh_bevel.h b/source/blender/bmesh/tools/bmesh_bevel.h
index de57e1c62a9..03c10ee9f80 100644
--- a/source/blender/bmesh/tools/bmesh_bevel.h
+++ b/source/blender/bmesh/tools/bmesh_bevel.h
@@ -23,6 +23,18 @@
 struct CurveProfile;
 struct MDeformVert;
 
+/**
+ * - Currently only bevels BM_ELEM_TAG'd verts and edges.
+ *
+ * - Newly created faces, edges, and verts are BM_ELEM_TAG'd too,
+ *   the caller needs to ensure these are cleared before calling
+ *   if its going to use this tag.
+ *
+ * - If limit_offset is set, adjusts offset down if necessary
+ *   to avoid geometry collisions.
+ *
+ * \warning all tagged edges _must_ be manifold.
+ */
 void BM_mesh_bevel(BMesh *bm,
                    const float offset,
                    const int offset_type,
diff --git a/source/blender/bmesh/tools/bmesh_bisect_plane.c b/source/blender/bmesh/tools/bmesh_bisect_plane.c
index 8f03b86b859..c9a5c047462 100644
--- a/source/blender/bmesh/tools/bmesh_bisect_plane.c
+++ b/source/blender/bmesh/tools/bmesh_bisect_plane.c
@@ -411,11 +411,6 @@ finally:
 /** \name Public BMesh Bisect Function
  * \{ */
 
-/**
- * \param use_snap_center: Snap verts onto the plane.
- * \param use_tag: Only bisect tagged edges and faces.
- * \param oflag_center: Operator flag, enabled for geometry on the axis (existing and created)
- */
 void BM_mesh_bisect_plane(BMesh *bm,
                           const float plane[4],
                           const bool use_snap_center,
diff --git a/source/blender/bmesh/tools/bmesh_bisect_plane.h b/source/blender/bmesh/tools/bmesh_bisect_plane.h
index f64b5d8097c..120935296b7 100644
--- a/source/blender/bmesh/tools/bmesh_bisect_plane.h
+++ b/source/blender/bmesh/tools/bmesh_bisect_plane.h
@@ -20,6 +20,11 @@
  * \ingroup bmesh
  */
 
+/**
+ * \param use_snap_center: Snap verts onto the plane.
+ * \param use_tag: Only bisect tagged edges and faces.
+ * \param oflag_center: Operator flag, enabled for geometry on the axis (existing and created)
+ */
 void BM_mesh_bisect_plane(BMesh *bm,
                           const float plane[4],
                           const bool use_snap_center,
diff --git a/source/blender/bmesh/tools/bmesh_boolean.cc b/source/blender/bmesh/tools/bmesh_boolean.cc
index 487ef6427af..e244bc377db 100644
--- a/source/blender/bmesh/tools/bmesh_boolean.cc
+++ b/source/blender/bmesh/tools/bmesh_boolean.cc
@@ -456,14 +456,6 @@ bool BM_mesh_boolean(BMesh *bm,
       static_cast<blender::meshintersect::BoolOpType>(boolean_mode));
 }
 
-/**
- * Perform a Knife Intersection operation on the mesh bm.
- * There are either one or two operands, the same as described above for BM_mesh_boolean().
- * If use_separate_all is true, each edge that is created from the intersection should
- * be used to separate all its incident faces. TODO: implement that.
- * TODO: need to ensure that "selected/non-selected" flag of original faces gets propagated
- * to the intersection result faces.
- */
 bool BM_mesh_boolean_knife(BMesh *bm,
                            struct BMLoop *(*looptris)[3],
                            const int looptris_tot,
diff --git a/source/blender/bmesh/tools/bmesh_boolean.h b/source/blender/bmesh/tools/bmesh_boolean.h
index ed77242e14c..4dacc7b1095 100644
--- a/source/blender/bmesh/tools/bmesh_boolean.h
+++ b/source/blender/bmesh/tools/bmesh_boolean.h
@@ -35,6 +35,16 @@ bool BM_mesh_boolean(BMesh *bm,
                      const bool hole_tolerant,
                      const int boolean_mode);
 
+/**
+ * Perform a Knife Intersection operation on the mesh `bm`.
+ * There are either one or two operands, the same as described above for #BM_mesh_boolean().
+ *
+ * \param use_separate_all: When true, each edge that is created from the intersection should
+ * be used to separate all its incident faces. TODO: implement that.
+ *
+ * TODO: need to ensure that "selected/non-selected" flag of original faces gets propagated
+ * to the intersection result faces.
+ */
 bool BM_mesh_boolean_knife(BMesh *bm,
                            struct BMLoop *(*looptris)[3],
                            const int looptris_tot,
diff --git a/source/blender/bmesh/tools/bmesh_decimate.h b/source/blender/bmesh/tools/bmesh_decimate.h
index c62288c269a..1de241a1326 100644
--- a/source/blender/bmesh/tools/bmesh_decimate.h
+++ b/source/blender/bmesh/tools/bmesh_decimate.h
@@ -20,6 +20,20 @@
  * \ingroup bmesh
  */
 
+/**
+ * \brief BM_mesh_decimate
+ * \param bm: The mesh
+ * \param factor: face count multiplier [0 - 1]
+ * \param vweights: Optional array of vertex  aligned weights [0 - 1],
+ *        a vertex group is the usual source for this.
+ * \param symmetry_axis: Axis of symmetry, -1 to disable mirror decimate.
+ * \param symmetry_eps: Threshold when matching mirror verts.
+ *
+ * \note The caller is responsible for recalculating face and vertex normals.
+ * - Vertex normals are maintained while decimating,
+ *   although they won't necessarily match the final recalculated normals.
+ * - Face normals are not maintained at all.
+ */
 void BM_mesh_decimate_collapse(BMesh *bm,
                                const float factor,
                                float *vweights,
@@ -28,6 +42,8 @@ void BM_mesh_decimate_collapse(BMesh *bm,
                                const int symmetry_axis,
                                const float symmetry_eps);
 
+/**
+ * \param tag_only: so we can call this from an operator */
 void BM_mesh_decimate_unsubdivide_ex(BMesh *bm, const int iterations, const bool tag_only);
 void BM_mesh_decimate_unsubdivide(BMesh *bm, const int iterations);
 
diff --git a/source/blender/bmesh/tools/bmesh_decimate_collapse.c b/source/blender/bmesh/tools/bmesh_decimate_collapse.c
index 97fccbe01fd..e90e50ef8ff 100644
--- a/source/blender/bmesh/tools/bmesh_decimate_collapse.c
+++ b/source/blender/bmesh/tools/bmesh_decimate_collapse.c
@@ -1277,20 +1277,6 @@ static bool bm_decim_edge_collapse(BMesh *bm,
 /* Main Decimate Function
  * ********************** */
 
-/**
- * \brief BM_mesh_decimate
- * \param bm: The mesh
- * \param factor: face count multiplier [0 - 1]
- * \param vweights: Optional array of vertex  aligned weights [0 - 1],
- *        a vertex group is the usual source for this.
- * \param symmetry_axis: Axis of symmetry, -1 to disable mirror decimate.
- * \param symmetry_eps: Threshold when matching mirror verts.
- *
- * \note The caller is responsible for recalculating face and vertex normals.
- * - Vertex normals are maintained while decimating,
- *   although they won't necessarily match the final recalculated normals.
- * - Face normals are not maintained at all.
- */
 void BM_mesh_decimate_collapse(BMesh *bm,
                                const float factor,
                                float *vweights,
diff --git a/source/blender/bmesh/tools/bmesh_decimate_unsubdivide.c b/source/blender/bmesh/tools/bmesh_decimate_unsubdivide.c
index c96a7be1adf..ca0f31fdf75 100644
--- a/source/blender/bmesh/tools/bmesh_decimate_unsubdivide.c
+++ b/source/blender/bmesh/tools/bmesh_decimate_unsubdivide.c
@@ -168,8 +168,6 @@ enum {
  * - BMVert.index == -1:         shows we will remove this vert
  */
 
-/**
- * \param tag_only: so we can call this from an operator */
 void BM_mesh_decimate_unsubdivide_ex(BMesh *bm, const int iterations, const bool tag_only)
 {
 #ifdef USE_WALKER
diff --git a/source/blender/bmesh/tools/bmesh_edgenet.c b/source/blender/bmesh/tools/bmesh_edgenet.c
index 242b269ed47..4cad1d3cb3c 100644
--- a/source/blender/bmesh/tools/bmesh_edgenet.c
+++ b/source/blender/bmesh/tools/bmesh_edgenet.c
@@ -422,15 +422,6 @@ static LinkNode *bm_edgenet_path_calc_best(BMEdge *e,
   return path;
 }
 
-/**
- * Fill in faces from an edgenet made up of boundary and wire edges.
- *
- * \note New faces currently don't have their normals calculated and are flipped randomly.
- *       The caller needs to flip faces correctly.
- *
- * \param bm: The mesh to operate on.
- * \param use_edge_tag: Only fill tagged edges.
- */
 void BM_mesh_edgenet(BMesh *bm, const bool use_edge_tag, const bool use_new_face_tag)
 {
   VertNetInfo *vnet_info = MEM_callocN(sizeof(*vnet_info) * (size_t)bm->totvert, __func__);
diff --git a/source/blender/bmesh/tools/bmesh_edgenet.h b/source/blender/bmesh/tools/bmesh_edgenet.h
index 7855b2e2886..20edb30442c 100644
--- a/source/blender/bmesh/tools/bmesh_edgenet.h
+++ b/source/blender/bmesh/tools/bmesh_edgenet.h
@@ -20,4 +20,13 @@
  * \ingroup bmesh
  */
 
+/**
+ * Fill in faces from an edgenet made up of boundary and wire edges.
+ *
+ * \note New faces currently don't have their normals calculated and are flipped randomly.
+ *       The caller needs to flip faces correctly.
+ *
+ * \param bm: The mesh to operate on.
+ * \param use_edge_tag: Only fill tagged edges.
+ */
 void BM_mesh_edgenet(BMesh *bm, const bool use_edge_tag, const bool use_new_face_tag);
diff --git a/source/blender/bmesh/tools/bmesh_edgesplit.c b/source/blender/bmesh/tools/bmesh_edgesplit.c
index 388e7f41aba..cd5200a660d 100644
--- a/source/blender/bmesh/tools/bmesh_edgesplit.c
+++ b/source/blender/bmesh/tools/bmesh_edgesplit.c
@@ -28,11 +28,6 @@
 
 #include "bmesh_edgesplit.h" /* own include */
 
-/**
- * \param use_verts: Use flagged verts instead of edges.
- * \param tag_only: Only split tagged edges.
- * \param copy_select: Copy selection history.
- */
 void BM_mesh_edgesplit(BMesh *bm,
                        const bool use_verts,
                        const bool tag_only,
diff --git a/source/blender/bmesh/tools/bmesh_edgesplit.h b/source/blender/bmesh/tools/bmesh_edgesplit.h
index 4d3db67ef5f..bcbb3ab7857 100644
--- a/source/blender/bmesh/tools/bmesh_edgesplit.h
+++ b/source/blender/bmesh/tools/bmesh_edgesplit.h
@@ -24,6 +24,11 @@
 extern "C" {
 #endif
 
+/**
+ * \param use_verts: Use flagged verts instead of edges.
+ * \param tag_only: Only split tagged edges.
+ * \param copy_select: Copy selection history.
+ */
 void BM_mesh_edgesplit(BMesh *bm,
                        const bool use_verts,
                        const bool tag_only,
diff --git a/source/blender/bmesh/tools/bmesh_intersect.c b/source/blender/bmesh/tools/bmesh_intersect.c
index 947442c7bd8..6824dd5008a 100644
--- a/source/blender/bmesh/tools/bmesh_intersect.c
+++ b/source/blender/bmesh/tools/bmesh_intersect.c
@@ -947,14 +947,6 @@ static int isect_bvhtree_point_v3(BVHTree *tree, const float **looptris, const f
 
 #endif /* USE_BVH */
 
-/**
- * Intersect tessellated faces
- * leaving the resulting edges tagged.
- *
- * \param test_fn: Return value: -1: skip, 0: tree_a, 1: tree_b (use_self == false)
- * \param boolean_mode: -1: no-boolean, 0: intersection... see #BMESH_ISECT_BOOLEAN_ISECT.
- * \return true if the mesh is changed (intersections cut or faces removed from boolean).
- */
 bool BM_mesh_intersect(BMesh *bm,
                        struct BMLoop *(*looptris)[3],
                        const int looptris_tot,
diff --git a/source/blender/bmesh/tools/bmesh_intersect.h b/source/blender/bmesh/tools/bmesh_intersect.h
index d09ea67a3bb..a6c91715f31 100644
--- a/source/blender/bmesh/tools/bmesh_intersect.h
+++ b/source/blender/bmesh/tools/bmesh_intersect.h
@@ -24,6 +24,14 @@
 extern "C" {
 #endif
 
+/**
+ * Intersect tessellated faces
+ * leaving the resulting edges tagged.
+ *
+ * \param test_fn: Return value: -1: skip, 0: tree_a, 1: tree_b (use_self == false)
+ * \param boolean_mode: -1: no-boolean, 0: intersection... see #BMESH_ISECT_BOOLEAN_ISECT.
+ * \return true if the mesh is changed (intersections cut or faces removed from boolean).
+ */
 bool BM_mesh_intersect(BMesh *bm,
                        struct BMLoop *(*looptris)[3],
                        const int looptris_tot,
diff --git a/source/blender/bmesh/tools/bmesh_region_match.c b/source/blender/bmesh/tools/bmesh_region_match.c
index 924538490ad..8a909cbc9fd 100644
--- a/source/blender/bmesh/tools/bmesh_region_match.c
+++ b/source/blender/bmesh/tools/bmesh_region_match.c
@@ -1332,12 +1332,6 @@ static void bm_vert_fasthash_destroy(UUIDFashMatch *fm)
 
 #endif /* USE_PIVOT_FASTMATCH */
 
-/**
- * Take a face-region and return a list of matching face-regions.
- *
- * \param faces_region: A single, contiguous face-region.
- * \return A list of matching null-terminated face-region arrays.
- */
 int BM_mesh_region_match(BMesh *bm,
                          BMFace **faces_region,
                          uint faces_region_len,
diff --git a/source/blender/bmesh/tools/bmesh_region_match.h b/source/blender/bmesh/tools/bmesh_region_match.h
index 799af938c31..7b7233783ce 100644
--- a/source/blender/bmesh/tools/bmesh_region_match.h
+++ b/source/blender/bmesh/tools/bmesh_region_match.h
@@ -20,6 +20,12 @@
  * \ingroup bmesh
  */
 
+/**
+ * Take a face-region and return a list of matching face-regions.
+ *
+ * \param faces_region: A single, contiguous face-region.
+ * \return A list of matching null-terminated face-region arrays.
+ */
 int BM_mesh_region_match(BMesh *bm,
                          BMFace **faces_region,
                          uint faces_region_len,
diff --git a/source/blender/bmesh/tools/bmesh_separate.c b/source/blender/bmesh/tools/bmesh_separate.c
index 3c69ea111bf..e00829604d5 100644
--- a/source/blender/bmesh/tools/bmesh_separate.c
+++ b/source/blender/bmesh/tools/bmesh_separate.c
@@ -32,10 +32,6 @@
 #include "bmesh_separate.h" /* own include */
 #include "intern/bmesh_private.h"
 
-/**
- * Split all faces that match `filter_fn`.
- * \note
- */
 void BM_mesh_separate_faces(BMesh *bm, BMFaceFilterFunc filter_fn, void *user_data)
 {
   BMFace **faces_array_all = MEM_mallocN(bm->totface * sizeof(BMFace *), __func__);
diff --git a/source/blender/bmesh/tools/bmesh_separate.h b/source/blender/bmesh/tools/bmesh_separate.h
index 9260903a8fa..8c599eef2b0 100644
--- a/source/blender/bmesh/tools/bmesh_separate.h
+++ b/source/blender/bmesh/tools/bmesh_separate.h
@@ -20,4 +20,8 @@
  * \ingroup bmesh
  */
 
+/**
+ * Split all faces that match `filter_fn`.
+ * \note
+ */
 void BM_mesh_separate_faces(BMesh *bm, BMFaceFilterFunc filter_fn, void *user_data);
diff --git a/source/blender/bmesh/tools/bmesh_wireframe.c b/source/blender/bmesh/tools/bmesh_wireframe.c
index af4a4424103..67010fc89c7 100644
--- a/source/blender/bmesh/tools/bmesh_wireframe.c
+++ b/source/blender/bmesh/tools/bmesh_wireframe.c
@@ -152,12 +152,6 @@ static bool bm_loop_is_radial_boundary(BMLoop *l_first)
   return true;
 }
 
-/**
- * \param defgrp_index: Vertex group index, -1 for no vertex groups.
- *
- * \note All edge tags must be cleared.
- * \note Behavior matches MOD_solidify.c
- */
 void BM_mesh_wireframe(BMesh *bm,
                        const float offset,
                        const float offset_fac,
diff --git a/source/blender/bmesh/tools/bmesh_wireframe.h b/source/blender/bmesh/tools/bmesh_wireframe.h
index b2c2f5f5523..5b64a16435f 100644
--- a/source/blender/bmesh/tools/bmesh_wireframe.h
+++ b/source/blender/bmesh/tools/bmesh_wireframe.h
@@ -22,6 +22,12 @@
 
 #pragma once
 
+/**
+ * \param defgrp_index: Vertex group index, -1 for no vertex groups.
+ *
+ * \note All edge tags must be cleared.
+ * \note Behavior matches MOD_solidify.c
+ */
 void BM_mesh_wireframe(BMesh *bm,
                        const float offset,
                        const float offset_fac,