Cleanup: spelling in comments, use doxy sections

15 files changed, 34 insertions, 29 deletions

diff --git a/source/blender/blenkernel/BKE_DerivedMesh.h b/source/blender/blenkernel/BKE_DerivedMesh.h
index 59f0c86684d..4274ca97fd1 100644
--- a/source/blender/blenkernel/BKE_DerivedMesh.h
+++ b/source/blender/blenkernel/BKE_DerivedMesh.h
@@ -68,8 +68,8 @@ struct Object;
 struct Scene;
 
 /*
- * NOTE: all mface interfaces now officially operate on tessellated data.
- *       Also, the mface origindex layer indexes mpolys, not mfaces.
+ * NOTE: all #MFace interfaces now officially operate on tessellated data.
+ *       Also, the #MFace orig-index layer indexes #MPoly, not #MFace.
  */
 
 /* keep in sync with MFace/MPoly types */
diff --git a/source/blender/blenkernel/intern/mesh.cc b/source/blender/blenkernel/intern/mesh.cc
index 0becea62810..7c86aff6624 100644
--- a/source/blender/blenkernel/intern/mesh.cc
+++ b/source/blender/blenkernel/intern/mesh.cc
@@ -116,7 +116,7 @@ static void mesh_copy_data(Main *bmain, ID *id_dst, const ID *id_src, const int
   CustomData_MeshMasks mask = CD_MASK_MESH;
 
   if (mesh_src->id.tag & LIB_TAG_NO_MAIN) {
-    /* For copies in depsgraph, keep data like origindex and orco. */
+    /* For copies in depsgraph, keep data like #CD_ORIGINDEX and #CD_ORCO. */
     CustomData_MeshMasks_update(&mask, &CD_MASK_DERIVEDMESH);
   }
 
diff --git a/source/blender/blenkernel/intern/particle_distribute.c b/source/blender/blenkernel/intern/particle_distribute.c
index 4be48efb2b5..c461b7f108d 100644
--- a/source/blender/blenkernel/intern/particle_distribute.c
+++ b/source/blender/blenkernel/intern/particle_distribute.c
@@ -1216,8 +1216,8 @@ static int psys_thread_context_init_distribute(ParticleThreadContext *ctx,
   MEM_freeN(element_sum);
   MEM_freeN(element_map);
 
-  /* For hair, sort by origindex (allows optimization's in rendering), */
-  /* however with virtual parents the children need to be in random order. */
+  /* For hair, sort by #CD_ORIGINDEX (allows optimization's in rendering),
+   * however with virtual parents the children need to be in random order. */
   if (part->type == PART_HAIR && !(part->childtype == PART_CHILD_FACES && part->parents != 0.0f)) {
     const int *orig_index = NULL;
 
diff --git a/source/blender/blenkernel/intern/subdiv_mesh.c b/source/blender/blenkernel/intern/subdiv_mesh.c
index e846dc2d807..ca4130d6bc4 100644
--- a/source/blender/blenkernel/intern/subdiv_mesh.c
+++ b/source/blender/blenkernel/intern/subdiv_mesh.c
@@ -44,7 +44,7 @@ typedef struct SubdivMeshContext {
   /* UV layers interpolation. */
   int num_uv_layers;
   MLoopUV *uv_layers[MAX_MTFACE];
-  /* Orco interpolation. */
+  /* Original coordinates (ORCO) interpolation. */
   float (*orco)[3];
   float (*cloth_orco)[3];
   /* Per-subdivided vertex counter of averaged values. */
diff --git a/source/blender/bmesh/intern/bmesh_mesh_convert.cc b/source/blender/bmesh/intern/bmesh_mesh_convert.cc
index bb1fe749e6b..884f6b5388a 100644
--- a/source/blender/bmesh/intern/bmesh_mesh_convert.cc
+++ b/source/blender/bmesh/intern/bmesh_mesh_convert.cc
@@ -931,7 +931,7 @@ void BM_mesh_bm_to_me(Main *bmain, BMesh *bm, Mesh *me, const struct BMeshToMesh
   me->totloop = bm->totloop;
   me->totpoly = bm->totface;
   /* Will be overwritten with a valid value if 'dotess' is set, otherwise we
-   * end up with 'me->totface' and me->mface == nullptr which can crash T28625. */
+   * end up with 'me->totface' and `me->mface == nullptr` which can crash T28625. */
   me->totface = 0;
   me->act_face = -1;
 
diff --git a/source/blender/depsgraph/intern/builder/deg_builder.cc b/source/blender/depsgraph/intern/builder/deg_builder.cc
index 56117a00b73..a3cd821e82f 100644
--- a/source/blender/depsgraph/intern/builder/deg_builder.cc
+++ b/source/blender/depsgraph/intern/builder/deg_builder.cc
@@ -54,9 +54,9 @@ bool deg_check_base_in_depsgraph(const Depsgraph *graph, Base *base)
   return id_node->has_base;
 }
 
-/*******************************************************************************
- * Base class for builders.
- */
+/* -------------------------------------------------------------------- */
+/** \name Base Class for Builders
+ * \{ */
 
 DepsgraphBuilder::DepsgraphBuilder(Main *bmain, Depsgraph *graph, DepsgraphBuilderCache *cache)
     : bmain_(bmain), graph_(graph), cache_(cache)
@@ -120,9 +120,11 @@ bool DepsgraphBuilder::check_pchan_has_bbone_segments(Object *object, const char
   return check_pchan_has_bbone_segments(object, pchan);
 }
 
-/*******************************************************************************
- * Builder finalizer.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Builder Finalizer.
+ * \{ */
 
 namespace {
 
@@ -137,7 +139,7 @@ void deg_graph_build_flush_visibility(Depsgraph *graph)
     for (ComponentNode *comp_node : id_node->components.values()) {
       comp_node->affects_directly_visible |= id_node->is_directly_visible;
 
-      /* Enforce "visibility" of the syncronization component.
+      /* Enforce "visibility" of the synchronization component.
        *
        * This component is never connected to other ID nodes, and hence can not be handled in the
        * same way as other components needed for evaluation. It is only needed for proper
@@ -213,7 +215,7 @@ void deg_graph_build_flush_visibility(Depsgraph *graph)
 
 void deg_graph_build_finalize(Main *bmain, Depsgraph *graph)
 {
-  /* Make sure dependencies of visible ID datablocks are visible. */
+  /* Make sure dependencies of visible ID data-blocks are visible. */
   deg_graph_build_flush_visibility(graph);
   deg_graph_remove_unused_noops(graph);
 
@@ -248,4 +250,6 @@ void deg_graph_build_finalize(Main *bmain, Depsgraph *graph)
   }
 }
 
+/** \} */
+
 }  // namespace blender::deg
diff --git a/source/blender/draw/engines/eevee/eevee_private.h b/source/blender/draw/engines/eevee/eevee_private.h
index 0a7c8e185c4..a978d6fe75e 100644
--- a/source/blender/draw/engines/eevee/eevee_private.h
+++ b/source/blender/draw/engines/eevee/eevee_private.h
@@ -671,7 +671,7 @@ typedef struct EEVEE_HairMotionData {
   /** Allocator will alloc enough slot for all particle systems. Or 1 if it's a curves object. */
   int psys_len;
   struct {
-    /* The vbos and textures are not owned. */
+    /* The VBO's and textures are not owned. */
     EEVEE_HairMotionStepData step_data[2]; /* Data for time = t +/- step. */
   } psys[0];
 } EEVEE_HairMotionData;
diff --git a/source/blender/draw/intern/draw_cache_impl_subdivision.cc b/source/blender/draw/intern/draw_cache_impl_subdivision.cc
index f94a3f0b9d8..99da06aa6b1 100644
--- a/source/blender/draw/intern/draw_cache_impl_subdivision.cc
+++ b/source/blender/draw/intern/draw_cache_impl_subdivision.cc
@@ -781,7 +781,7 @@ struct DRWCacheBuildingContext {
 
   DRWSubdivCache *cache;
 
-  /* Pointers into DRWSubdivCache buffers for easier access during traversal. */
+  /* Pointers into #DRWSubdivCache buffers for easier access during traversal. */
   CompressedPatchCoord *patch_coords;
   int *subdiv_loop_vert_index;
   int *subdiv_loop_subdiv_vert_index;
@@ -793,9 +793,9 @@ struct DRWCacheBuildingContext {
   int *vert_origindex_map;
   int *edge_origindex_map;
 
-  /* Origindex layers from the mesh to directly look up during traversal the origindex from the
-   * base mesh for edit data so that we do not have to handle yet another GPU buffer and do this in
-   * the shaders. */
+  /* #CD_ORIGINDEX layers from the mesh to directly look up during traversal the original-index
+     from the base mesh for edit data so that we do not have to handle yet another GPU buffer and
+     do this in the shaders. */
   const int *v_origindex;
   const int *e_origindex;
 };
diff --git a/source/blender/editors/curves/intern/curves_ops.cc b/source/blender/editors/curves/intern/curves_ops.cc
index d35e58d5eba..0e12257be58 100644
--- a/source/blender/editors/curves/intern/curves_ops.cc
+++ b/source/blender/editors/curves/intern/curves_ops.cc
@@ -234,7 +234,7 @@ static void try_convert_single_object(Object &curves_ob,
   /* The old hair system still uses #MFace, so make sure those are available on the mesh. */
   BKE_mesh_tessface_calc(&surface_me);
 
-  /* Prepare utility data structure to map hair roots to mfaces. */
+  /* Prepare utility data structure to map hair roots to #MFace's. */
   const Span<int> mface_to_poly_map{
       static_cast<const int *>(CustomData_get_layer(&surface_me.fdata, CD_ORIGINDEX)),
       surface_me.totface};
diff --git a/source/blender/editors/mesh/editface.cc b/source/blender/editors/mesh/editface.cc
index cb5d48d1023..69fe69fe117 100644
--- a/source/blender/editors/mesh/editface.cc
+++ b/source/blender/editors/mesh/editface.cc
@@ -158,7 +158,7 @@ void paintface_reveal(bContext *C, Object *ob, const bool select)
   paintface_flush_flags(C, ob, SELECT | ME_HIDE);
 }
 
-/* Set tface seams based on edge data, uses hash table to find seam edges. */
+/* Set object-mode face selection seams based on edge data, uses hash table to find seam edges. */
 
 static void select_linked_tfaces_with_seams(Mesh *me, const uint index, const bool select)
 {
diff --git a/source/blender/editors/sculpt_paint/paint_image_proj.c b/source/blender/editors/sculpt_paint/paint_image_proj.c
index e6c90fd8d3f..d597705e82e 100644
--- a/source/blender/editors/sculpt_paint/paint_image_proj.c
+++ b/source/blender/editors/sculpt_paint/paint_image_proj.c
@@ -4492,7 +4492,8 @@ static void project_paint_begin(const bContext *C,
     }
   }
 
-  /* when using subsurf or multires, mface arrays are thrown away, we need to keep a copy */
+  /* when using sub-surface or multi-resolution,
+   * mesh-data arrays are thrown away, we need to keep a copy. */
   if (ps->is_shared_user == false) {
     proj_paint_state_cavity_init(ps);
   }
diff --git a/source/blender/editors/uvedit/uvedit_unwrap_ops.c b/source/blender/editors/uvedit/uvedit_unwrap_ops.c
index 84dca352c9f..f24057920d7 100644
--- a/source/blender/editors/uvedit/uvedit_unwrap_ops.c
+++ b/source/blender/editors/uvedit/uvedit_unwrap_ops.c
@@ -652,7 +652,7 @@ static ParamHandle *construct_param_handle_subsurfed(const Scene *scene,
 
     mloop = &subsurfedLoops[mpoly->loopstart];
 
-    /* We will not check for v4 here. Subsurfed mfaces always have 4 vertices. */
+    /* We will not check for v4 here. Sub-surface faces always have 4 vertices. */
     BLI_assert(mpoly->totloop == 4);
     key = (ParamKey)i;
     vkeys[0] = (ParamKey)mloop[0].v;
diff --git a/source/blender/makesrna/intern/rna_mesh.c b/source/blender/makesrna/intern/rna_mesh.c
index da4be3cd0da..fd548ea6a56 100644
--- a/source/blender/makesrna/intern/rna_mesh.c
+++ b/source/blender/makesrna/intern/rna_mesh.c
@@ -1094,7 +1094,7 @@ static int rna_MeshPoly_vertices_get_length(const PointerRNA *ptr,
 {
   const MPoly *mp = (MPoly *)ptr->data;
   /* NOTE: raw access uses dummy item, this _could_ crash,
-   * watch out for this, mface uses it but it can't work here. */
+   * watch out for this, #MFace uses it but it can't work here. */
   return (length[0] = mp->totloop);
 }
 
diff --git a/source/blender/modifiers/intern/MOD_array.c b/source/blender/modifiers/intern/MOD_array.c
index c44a4e0b438..02aa5254e55 100644
--- a/source/blender/modifiers/intern/MOD_array.c
+++ b/source/blender/modifiers/intern/MOD_array.c
@@ -328,7 +328,7 @@ static void mesh_merge_transform(Mesh *result,
     ml->e += cap_edges_index;
   }
 
-  /* set origindex */
+  /* Set #CD_ORIGINDEX. */
   index_orig = CustomData_get_layer(&result->vdata, CD_ORIGINDEX);
   if (index_orig) {
     copy_vn_i(index_orig + cap_verts_index, cap_nverts, ORIGINDEX_NONE);
diff --git a/source/blender/modifiers/intern/MOD_dynamicpaint.c b/source/blender/modifiers/intern/MOD_dynamicpaint.c
index 1891ac5df7c..6b0578c77f1 100644
--- a/source/blender/modifiers/intern/MOD_dynamicpaint.c
+++ b/source/blender/modifiers/intern/MOD_dynamicpaint.c
@@ -83,17 +83,17 @@ static void requiredDataMask(Object *UNUSED(ob),
   if (pmd->canvas) {
     DynamicPaintSurface *surface = pmd->canvas->surfaces.first;
     for (; surface; surface = surface->next) {
-      /* tface */
+      /* UV's: #CD_MLOOPUV. */
       if (surface->format == MOD_DPAINT_SURFACE_F_IMAGESEQ ||
           surface->init_color_type == MOD_DPAINT_INITIAL_TEXTURE) {
         r_cddata_masks->lmask |= CD_MASK_MLOOPUV;
       }
-      /* mcol */
+      /* Vertex Colors: #CD_PROP_BYTE_COLOR. */
       if (surface->type == MOD_DPAINT_SURFACE_T_PAINT ||
           surface->init_color_type == MOD_DPAINT_INITIAL_VERTEXCOLOR) {
         r_cddata_masks->lmask |= CD_MASK_PROP_BYTE_COLOR;
       }
-      /* CD_MDEFORMVERT */
+      /* Vertex Weights: #CD_MDEFORMVERT. */
       if (surface->type == MOD_DPAINT_SURFACE_T_WEIGHT) {
         r_cddata_masks->vmask |= CD_MASK_MDEFORMVERT;
       }