Cleanup: mostly comments, use doxy syntax & typos

- Use doxy syntax for functions.
- Use `pragma once` for header guard.

1 files changed, 38 insertions, 42 deletions

diff --git a/source/blender/bmesh/tools/bmesh_boolean.cc b/source/blender/bmesh/tools/bmesh_boolean.cc
index 91459e676c1..5d410d60496 100644
--- a/source/blender/bmesh/tools/bmesh_boolean.cc
+++ b/source/blender/bmesh/tools/bmesh_boolean.cc
@@ -17,7 +17,7 @@
 /** \file
  * \ingroup bmesh
  *
- * Main functions for boolean on a BMesh (used by the tool and modifier)
+ * Main functions for boolean on a #BMesh (used by the tool and modifier)
  */
 
 #include "BLI_array.hh"
@@ -34,11 +34,12 @@ namespace blender {
 namespace meshintersect {
 
 #ifdef WITH_GMP
-/* Make a blender::meshintersect::Mesh from BMesh bm.
- * We are given a triangulation of it from the caller via looptris,
+
+/** Make a #blender::meshintersect::Mesh from #BMesh bm.
+ * We are given a triangulation of it from the caller via #looptris,
  * which are looptris_tot triples of loops that together tessellate
  * the faces of bm.
- * Return a second IMesh in *r_triangulated that has the triangulated
+ * Return a second #IMesh in *r_triangulated that has the triangulated
  * mesh, with face "orig" fields that connect the triangles back to
  * the faces in the returned (polygonal) mesh.
  */
@@ -82,8 +83,7 @@ static IMesh mesh_from_bm(BMesh *bm,
   /* Now do the triangulation mesh.
    * The loop_tris have accurate v and f members for the triangles,
    * but their next and e pointers are not correct for the loops
-   * that start added-diagonal edges.
-   */
+   * that start added-diagonal edges. */
   Array<Face *> tri_face(looptris_tot);
   face_vert.resize(3);
   face_edge_orig.resize(3);
@@ -112,9 +112,8 @@ static IMesh mesh_from_bm(BMesh *bm,
 static bool bmvert_attached_to_wire(const BMVert *bmv)
 {
   /* This is not quite right. It returns true if the only edges
-   * Attached to bmv are wire edges. TODO: iterate through edges
-   * attached to bmv and check BM_edge_is_wire.
-   */
+   * Attached to \a bmv are wire edges. TODO: iterate through edges
+   * attached to \a bmv and check #BM_edge_is_wire. */
   return BM_vert_is_wire(bmv);
 }
 
@@ -131,13 +130,14 @@ static bool face_has_verts_in_order(BMesh *bm, BMFace *bmf, const BMVert *v1, co
   return false;
 }
 
-/* Use the unused _BM_ELEM_TAG_ALT bmflag to mark geometry we will keep. */
+/** Use the unused _BM_ELEM_TAG_ALT #BMElem.hflag to mark geometry we will keep. */
 constexpr uint KEEP_FLAG = (1 << 6);
 
-/* Change BMesh bm to have the mesh match m_out. Return true if there were any changes at all.
+/**
+ * Change #BMesh bm to have the mesh match m_out. Return true if there were any changes at all.
  * Vertices, faces, and edges in the current bm that are not used in the output are killed,
  * except we don't kill wire edges and we don't kill hidden geometry.
- * Also, the BM_ELEM_TAG header flag is set for those BMEdges that come from intersections
+ * Also, the #BM_ELEM_TAG header flag is set for those #BMEdge's that come from intersections
  * resulting from the intersection needed by the Boolean operation.
  */
 static bool apply_mesh_output_to_bmesh(BMesh *bm, IMesh &m_out)
@@ -147,8 +147,7 @@ static bool apply_mesh_output_to_bmesh(BMesh *bm, IMesh &m_out)
   m_out.populate_vert();
 
   /* Initially mark all existing verts as "don't keep", except hidden verts
-   * and verts attached to wire edges.
-   */
+   * and verts attached to wire edges. */
   for (int v = 0; v < bm->totvert; ++v) {
     BMVert *bmv = BM_vert_at_index(bm, v);
     if (BM_elem_flag_test(bmv, BM_ELEM_HIDDEN) || bmvert_attached_to_wire(bmv)) {
@@ -159,11 +158,10 @@ static bool apply_mesh_output_to_bmesh(BMesh *bm, IMesh &m_out)
     }
   }
 
-  /* Reuse old or make new BMVerts, depending on if there's an orig or not.
+  /* Reuse old or make new #BMVert's, depending on if there's an orig or not.
    * For those reused, mark them "keep".
-   * Store needed old BMVerts in new_bmvs first, as the table may be unusable after
-   * creating a new BMVert.
-   */
+   * Store needed old #BMVert's in new_bmvs first, as the table may be unusable after
+   * creating a new #BMVert. */
   Array<BMVert *> new_bmvs(m_out.vert_size());
   for (int v : m_out.vert_index_range()) {
     const Vert *vertp = m_out.vert(v);
@@ -194,8 +192,7 @@ static bool apply_mesh_output_to_bmesh(BMesh *bm, IMesh &m_out)
   }
 
   /* Initially mark all existing faces as "don't keep", except hidden faces.
-   * Also, save current BMFace pointers as creating faces will disturb the table.
-   */
+   * Also, save current #BMFace pointers as creating faces will disturb the table. */
   Array<BMFace *> old_bmfs(bm->totface);
   for (int f = 0; f < bm->totface; ++f) {
     BMFace *bmf = BM_face_at_index(bm, f);
@@ -208,14 +205,13 @@ static bool apply_mesh_output_to_bmesh(BMesh *bm, IMesh &m_out)
     }
   }
 
-  /* Save the original BMEdges so we can use them as examples. */
+  /* Save the original #BMEdge's so we can use them as examples. */
   Array<BMEdge *> old_edges(bm->totedge);
   std::copy(bm->etable, bm->etable + bm->totedge, old_edges.begin());
 
-  /* Reuse or make new BMFaces, as the faces are identical to old ones or not.
+  /* Reuse or make new #BMFace's, as the faces are identical to old ones or not.
    * If reusing, mark them as "keep". First find the maximum face length
-   * so we can declare some arrays outside of the face-creating loop.
-   */
+   * so we can declare some arrays outside of the face-creating loop. */
   int maxflen = 0;
   for (const Face *f : m_out.faces()) {
     maxflen = max_ii(maxflen, f->size());
@@ -232,9 +228,8 @@ static bool apply_mesh_output_to_bmesh(BMesh *bm, IMesh &m_out)
       face_bmverts[i] = new_bmvs[v_index];
     }
     BMFace *bmf = BM_face_exists(face_bmverts.data(), flen);
-    /* BM_face_exists checks if the face exists with the vertices in either order.
-     * We can only reuse the face if the orientations are the same.
-     */
+    /* #BM_face_exists checks if the face exists with the vertices in either order.
+     * We can only reuse the face if the orientations are the same. */
     if (bmf != NULL && face_has_verts_in_order(bm, bmf, face_bmverts[0], face_bmverts[1])) {
       BM_elem_flag_enable(bmf, KEEP_FLAG);
     }
@@ -248,7 +243,7 @@ static bool apply_mesh_output_to_bmesh(BMesh *bm, IMesh &m_out)
       else {
         orig_face = NULL;
       }
-      /* Make or find BMEdges. */
+      /* Make or find #BMEdge's. */
       for (int i = 0; i < flen; ++i) {
         BMVert *bmv1 = face_bmverts[i];
         BMVert *bmv2 = face_bmverts[(i + 1) % flen];
@@ -277,7 +272,7 @@ static bool apply_mesh_output_to_bmesh(BMesh *bm, IMesh &m_out)
         BM_elem_select_copy(bm, bmf, orig_face);
       }
       BM_elem_flag_enable(bmf, KEEP_FLAG);
-      /* Now do interpolation of loop data (e.g., UVs) using the example face. */
+      /* Now do interpolation of loop data (e.g., UV's) using the example face. */
       if (orig_face != NULL) {
         BMIter liter;
         BMLoop *l = static_cast<BMLoop *>(BM_iter_new(&liter, bm, BM_LOOPS_OF_FACE, bmf));
@@ -291,9 +286,8 @@ static bool apply_mesh_output_to_bmesh(BMesh *bm, IMesh &m_out)
   }
 
   /* Now kill the unused faces and verts, and clear flags for kept ones. */
-  /* BM_ITER_MESH_MUTABLE macro needs type casts for C++, so expand here.
-   * TODO(howard): make some nice C++ iterators for BMesh.
-   */
+  /* #BM_ITER_MESH_MUTABLE macro needs type casts for C++, so expand here.
+   * TODO(howard): make some nice C++ iterators for #BMesh. */
   BMIter iter;
   BMFace *bmf = static_cast<BMFace *>(BM_iter_new(&iter, bm, BM_FACES_OF_MESH, NULL));
   while (bmf != NULL) {
@@ -306,7 +300,9 @@ static bool apply_mesh_output_to_bmesh(BMesh *bm, IMesh &m_out)
     }
     else {
       BM_face_kill_loose(bm, bmf);
-      // BM_face_kill(bm, bmf);
+#  if 0
+      BM_face_kill(bm, bmf);
+#  endif
       any_change = true;
     }
     bmf = bmf_next;
@@ -385,18 +381,18 @@ static bool bmesh_boolean(BMesh *bm,
 }  // namespace blender
 
 extern "C" {
-/*
+/**
  * Perform the boolean operation specified by boolean_mode on the mesh bm.
- * The inputs to the boolean operation are either one submesh (if use_self is true),
- * or two submeshes. The submeshes are specified by providing a test_fn which takes
+ * The inputs to the boolean operation are either one sub-mesh (if use_self is true),
+ * or two sub-meshes. The sub-meshes are specified by providing a test_fn which takes
  * a face and the supplied user_data and says with 'side' of the boolean operation
  * that face is for: 0 for the first side (side A), 1 for the second side (side B),
  * and -1 if the face is to be ignored completely in the boolean operation.
  *
- * If use_self is true, all operations do the same: the submesh is self-intersected
+ * If use_self is true, all operations do the same: the sub-mesh is self-intersected
  * and all pieces inside that result are removed.
- * Otherwise, the operations can be one of BMESH_ISECT_BOOLEAN_ISECT, BMESH_ISECT_BOOLEAN_UNION,
- * or BMESH_ISECT_BOOLEAN_DIFFERENCE.
+ * Otherwise, the operations can be one of #BMESH_ISECT_BOOLEAN_ISECT, #BMESH_ISECT_BOOLEAN_UNION,
+ * or #BMESH_ISECT_BOOLEAN_DIFFERENCE.
  *
  * (The actual library function called to do the boolean is internally capable of handling
  * n-ary operands, so maybe in the future we can expose that functionality to users.)
@@ -421,7 +417,7 @@ 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
@@ -459,9 +455,9 @@ bool BM_mesh_boolean(BMesh *UNUSED(bm),
   return false;
 }
 
-/*
+/**
  * 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().
+ * 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