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

Some minor improvements to doc-strings too.

Ref T92709

6 files changed, 7 insertions, 52 deletions

diff --git a/source/blender/bmesh/operators/bmo_create.c b/source/blender/bmesh/operators/bmo_create.c
index a740e4d66e8..c337724d096 100644
--- a/source/blender/bmesh/operators/bmo_create.c
+++ b/source/blender/bmesh/operators/bmo_create.c
@@ -31,12 +31,11 @@
 #define ELE_NEW 1
 #define ELE_OUT 2
 
-/* This is what runs when pressing the F key
- * doing the best thing here isn't always easy create vs dissolve, its nice to support
- * but it _really_ gives issues we might have to not call dissolve. - campbell
- */
 void bmo_contextual_create_exec(BMesh *bm, BMOperator *op)
 {
+  /* NOTE(@campbellbarton): doing the best thing here isn't always easy create vs dissolve,
+   * its nice to support but it _really_ gives issues we might have to not call dissolve. */
+
   BMOIter oiter;
   BMHeader *h;
   int totv = 0, tote = 0, totf = 0;
diff --git a/source/blender/bmesh/operators/bmo_dissolve.c b/source/blender/bmesh/operators/bmo_dissolve.c
index 360dcc2c79e..82d277ec3af 100644
--- a/source/blender/bmesh/operators/bmo_dissolve.c
+++ b/source/blender/bmesh/operators/bmo_dissolve.c
@@ -488,7 +488,6 @@ void bmo_dissolve_verts_exec(BMesh *bm, BMOperator *op)
   /* done with cleanup */
 }
 
-/* Limited Dissolve */
 void bmo_dissolve_limit_exec(BMesh *bm, BMOperator *op)
 {
   BMOpSlot *einput = BMO_slot_get(op->slots_in, "edges");
diff --git a/source/blender/bmesh/operators/bmo_primitive.c b/source/blender/bmesh/operators/bmo_primitive.c
index d8047499780..69404c8ba0e 100644
--- a/source/blender/bmesh/operators/bmo_primitive.c
+++ b/source/blender/bmesh/operators/bmo_primitive.c
@@ -787,14 +787,6 @@ void bmo_create_grid_exec(BMesh *bm, BMOperator *op)
   }
 }
 
-/**
- * Fills first available UV-map with grid-like UV's for all faces with `oflag` set.
- *
- * \param bm: The BMesh to operate on
- * \param x_segments: The x-resolution of the grid
- * \param y_segments: The y-resolution of the grid
- * \param oflag: The flag to check faces with.
- */
 void BM_mesh_calc_uvs_grid(BMesh *bm,
                            const uint x_segments,
                            const uint y_segments,
@@ -1130,12 +1122,6 @@ static void bm_mesh_calc_uvs_sphere_face(BMFace *f, const int cd_loop_uv_offset)
   }
 }
 
-/**
- * Fills first available UV-map with spherical projected UVs for all faces with `oflag` set.
- *
- * \param bm: The BMesh to operate on
- * \param oflag: The flag to check faces with.
- */
 void BM_mesh_calc_uvs_sphere(BMesh *bm, const short oflag, const int cd_loop_uv_offset)
 {
   BMFace *f;
@@ -1343,14 +1329,6 @@ void bmo_create_circle_exec(BMesh *bm, BMOperator *op)
   BMO_slot_buffer_from_enabled_flag(bm, op, op->slots_out, "verts.out", BM_VERT, VERT_MARK);
 }
 
-/**
- * Fills first available UV-map with 2D projected UVs for all faces with `oflag` set.
- *
- * \param bm: The BMesh to operate on.
- * \param mat: The transform matrix applied to the created circle.
- * \param radius: The size of the circle.
- * \param oflag: The flag to check faces with.
- */
 void BM_mesh_calc_uvs_circle(
     BMesh *bm, float mat[4][4], const float radius, const short oflag, const int cd_loop_uv_offset)
 {
@@ -1534,17 +1512,6 @@ void bmo_create_cone_exec(BMesh *bm, BMOperator *op)
   BMO_slot_buffer_from_enabled_flag(bm, op, op->slots_out, "verts.out", BM_VERT, VERT_MARK);
 }
 
-/**
- * Fills first available UV-map with cylinder/cone-like UVs for all faces with `oflag` set.
- *
- * \param bm: The BMesh to operate on.
- * \param mat: The transform matrix applied to the created cone/cylinder.
- * \param radius_top: The size of the top end of the cone/cylinder.
- * \param radius_bottom: The size of the bottom end of the cone/cylinder.
- * \param segments: The number of subdivisions in the sides of the cone/cylinder.
- * \param cap_ends: Whether the ends of the cone/cylinder are filled or not.
- * \param oflag: The flag to check faces with.
- */
 void BM_mesh_calc_uvs_cone(BMesh *bm,
                            float mat[4][4],
                            const float radius_top,
@@ -1710,15 +1677,6 @@ void bmo_create_cube_exec(BMesh *bm, BMOperator *op)
   BMO_slot_buffer_from_enabled_flag(bm, op, op->slots_out, "verts.out", BM_VERT, VERT_MARK);
 }
 
-/**
- * Fills first available UV-map with cube-like UVs for all faces with `oflag` set.
- *
- * \note Expects tagged faces to be six quads.
- * \note Caller must order faces for correct alignment.
- *
- * \param bm: The BMesh to operate on.
- * \param oflag: The flag to check faces with.
- */
 void BM_mesh_calc_uvs_cube(BMesh *bm, const short oflag)
 {
   BMFace *f;
diff --git a/source/blender/bmesh/operators/bmo_split_edges.c b/source/blender/bmesh/operators/bmo_split_edges.c
index d030a6e11b0..5a00094ef45 100644
--- a/source/blender/bmesh/operators/bmo_split_edges.c
+++ b/source/blender/bmesh/operators/bmo_split_edges.c
@@ -27,7 +27,6 @@
 
 #include "intern/bmesh_operators_private.h" /* own include */
 
-/* keep this operator fast, its used in a modifier */
 void bmo_split_edges_exec(BMesh *bm, BMOperator *op)
 {
   const bool use_verts = BMO_slot_bool_get(op->slots_in, "use_verts");
diff --git a/source/blender/bmesh/operators/bmo_subdivide_edgering.c b/source/blender/bmesh/operators/bmo_subdivide_edgering.c
index 6a80f360f59..7f0bfc5e2c9 100644
--- a/source/blender/bmesh/operators/bmo_subdivide_edgering.c
+++ b/source/blender/bmesh/operators/bmo_subdivide_edgering.c
@@ -1061,9 +1061,10 @@ static bool bm_edge_rim_test_cb(BMEdge *e, void *bm_v)
   return BMO_edge_flag_test_bool(bm, e, EDGE_RIM);
 }
 
-/* keep this operator fast, its used in a modifier */
 void bmo_subdivide_edgering_exec(BMesh *bm, BMOperator *op)
 {
+  /* NOTE: keep this operator fast, its used in a modifier. */
+
   ListBase eloops_rim = {NULL};
   BMOIter siter;
   BMEdge *e;
diff --git a/source/blender/bmesh/operators/bmo_unsubdivide.c b/source/blender/bmesh/operators/bmo_unsubdivide.c
index c5de6df34a7..f11e359e962 100644
--- a/source/blender/bmesh/operators/bmo_unsubdivide.c
+++ b/source/blender/bmesh/operators/bmo_unsubdivide.c
@@ -29,11 +29,10 @@
 
 #include "intern/bmesh_operators_private.h" /* own include */
 
-/* - BMVert.flag & BM_ELEM_TAG:  shows we touched this vert
- * - BMVert.index == -1:         shows we will remove this vert
- */
 void bmo_unsubdivide_exec(BMesh *bm, BMOperator *op)
 {
+  /* - `BMVert.flag & BM_ELEM_TAG`: Shows we touched this vert.
+   * - `BMVert.index == -1`:        Shows we will remove this vert. */
   BMVert *v;
   BMIter iter;