Cleanup: use doxy sections for multires & subdiv sources

9 files changed, 308 insertions, 185 deletions

diff --git a/source/blender/blenkernel/BKE_subdiv_ccg.h b/source/blender/blenkernel/BKE_subdiv_ccg.h
index 7c7638e65d2..8d2565c31f7 100644
--- a/source/blender/blenkernel/BKE_subdiv_ccg.h
+++ b/source/blender/blenkernel/BKE_subdiv_ccg.h
@@ -40,7 +40,7 @@ struct DMFlagMat;
 struct Mesh;
 struct Subdiv;
 
-/* =============================================================================
+/* --------------------------------------------------------------------
  * Masks.
  */
 
@@ -61,7 +61,7 @@ typedef struct SubdivCCGMaskEvaluator {
 bool BKE_subdiv_ccg_mask_init_from_paint(SubdivCCGMaskEvaluator *mask_evaluator,
                                          const struct Mesh *mesh);
 
-/* =============================================================================
+/* --------------------------------------------------------------------
  * Materials.
  */
 
@@ -80,7 +80,7 @@ typedef struct SubdivCCGMaterialFlagsEvaluator {
 void BKE_subdiv_ccg_material_flags_init_from_mesh(
     SubdivCCGMaterialFlagsEvaluator *material_flags_evaluator, const struct Mesh *mesh);
 
-/* =============================================================================
+/* --------------------------------------------------------------------
  * SubdivCCG.
  */
 
diff --git a/source/blender/blenkernel/intern/multires_reshape.c b/source/blender/blenkernel/intern/multires_reshape.c
index 02cd5f094a6..9b3242ba73a 100644
--- a/source/blender/blenkernel/intern/multires_reshape.c
+++ b/source/blender/blenkernel/intern/multires_reshape.c
@@ -42,9 +42,9 @@
 
 #include "multires_reshape.h"
 
-/* ================================================================================================
- * Reshape from object.
- */
+/* -------------------------------------------------------------------- */
+/** \name Reshape from object
+ * \{ */
 
 bool multiresModifier_reshapeFromVertcos(struct Depsgraph *depsgraph,
                                          struct Object *object,
@@ -93,9 +93,11 @@ bool multiresModifier_reshapeFromObject(struct Depsgraph *depsgraph,
   return result;
 }
 
-/* ================================================================================================
- * Reshape from modifier.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Reshape from modifier
+ * \{ */
 
 bool multiresModifier_reshapeFromDeformModifier(struct Depsgraph *depsgraph,
                                                 struct Object *object,
@@ -133,9 +135,11 @@ bool multiresModifier_reshapeFromDeformModifier(struct Depsgraph *depsgraph,
   return result;
 }
 
-/* ================================================================================================
- * Reshape from grids.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Reshape from grids
+ * \{ */
 
 bool multiresModifier_reshapeFromCCG(const int tot_level,
                                      Mesh *coarse_mesh,
@@ -161,9 +165,11 @@ bool multiresModifier_reshapeFromCCG(const int tot_level,
   return true;
 }
 
-/* ================================================================================================
- * Subdivision.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Subdivision
+ * \{ */
 
 void multiresModifier_subdivide(Object *object, MultiresModifierData *mmd)
 {
@@ -215,9 +221,11 @@ void multiresModifier_subdivide_to_level(struct Object *object,
   multires_set_tot_level(object, mmd, top_level);
 }
 
-/* ================================================================================================
- * Apply base.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Apply base
+ * \{ */
 
 void multiresModifier_base_apply(struct Depsgraph *depsgraph,
                                  Object *object,
@@ -263,3 +271,5 @@ void multiresModifier_base_apply(struct Depsgraph *depsgraph,
 
   multires_reshape_context_free(&reshape_context);
 }
+
+/** \} */
diff --git a/source/blender/blenkernel/intern/multires_reshape.h b/source/blender/blenkernel/intern/multires_reshape.h
index adfa2659661..bf5b03f51d9 100644
--- a/source/blender/blenkernel/intern/multires_reshape.h
+++ b/source/blender/blenkernel/intern/multires_reshape.h
@@ -138,7 +138,7 @@ typedef struct ReshapeConstGridElement {
   float mask;
 } ReshapeConstGridElement;
 
-/* ================================================================================================
+/* --------------------------------------------------------------------
  * Construct/destruct reshape context.
  */
 
@@ -169,7 +169,7 @@ bool multires_reshape_context_create_from_subdivide(MultiresReshapeContext *resh
 void multires_reshape_free_original_grids(MultiresReshapeContext *reshape_context);
 void multires_reshape_context_free(MultiresReshapeContext *reshape_context);
 
-/* ================================================================================================
+/* --------------------------------------------------------------------
  * Helper accessors.
  */
 
@@ -214,7 +214,7 @@ ReshapeGridElement multires_reshape_grid_element_for_ptex_coord(
 ReshapeConstGridElement multires_reshape_orig_grid_element_for_grid_coord(
     const MultiresReshapeContext *reshape_context, const GridCoord *grid_coord);
 
-/* ================================================================================================
+/* --------------------------------------------------------------------
  * Sample limit surface of the base mesh.
  */
 
@@ -225,14 +225,14 @@ void multires_reshape_evaluate_limit_at_grid(const MultiresReshapeContext *resha
                                              float r_P[3],
                                              float r_tangent_matrix[3][3]);
 
-/* ================================================================================================
+/* --------------------------------------------------------------------
  * Custom data preparation.
  */
 
 /* Make sure custom data is allocated for the given level. */
 void multires_reshape_ensure_grids(struct Mesh *mesh, const int level);
 
-/* ================================================================================================
+/* --------------------------------------------------------------------
  * Functions specific to reshaping from a set of vertices in a object position.
  */
 
@@ -245,7 +245,7 @@ bool multires_reshape_assign_final_coords_from_vertcos(
     const float (*vert_coords)[3],
     const int num_vert_coords);
 
-/* ================================================================================================
+/* --------------------------------------------------------------------
  * Functions specific to reshaping from CCG.
  */
 
@@ -255,7 +255,7 @@ bool multires_reshape_assign_final_coords_from_vertcos(
 bool multires_reshape_assign_final_coords_from_ccg(const MultiresReshapeContext *reshape_context,
                                                    struct SubdivCCG *subdiv_ccg);
 
-/* ================================================================================================
+/* --------------------------------------------------------------------
  * Functions specific to reshaping from MDISPS.
  */
 
@@ -267,7 +267,7 @@ void multires_reshape_assign_final_coords_from_mdisps(
 void multires_reshape_assign_final_coords_from_orig_mdisps(
     const MultiresReshapeContext *reshape_context);
 
-/* ================================================================================================
+/* --------------------------------------------------------------------
  * Displacement smooth.
  */
 
@@ -286,7 +286,7 @@ void multires_reshape_smooth_object_grids_with_details(
  */
 void multires_reshape_smooth_object_grids(const MultiresReshapeContext *reshape_context);
 
-/* ================================================================================================
+/* --------------------------------------------------------------------
  * Displacement, space conversion.
  */
 
@@ -297,7 +297,7 @@ void multires_reshape_store_original_grids(MultiresReshapeContext *reshape_conte
 void multires_reshape_object_grids_to_tangent_displacement(
     const MultiresReshapeContext *reshape_context);
 
-/* ================================================================================================
+/* --------------------------------------------------------------------
  * Apply base.
  */
 
diff --git a/source/blender/blenkernel/intern/multires_reshape_smooth.c b/source/blender/blenkernel/intern/multires_reshape_smooth.c
index 514608a0f1d..22864143f80 100644
--- a/source/blender/blenkernel/intern/multires_reshape_smooth.c
+++ b/source/blender/blenkernel/intern/multires_reshape_smooth.c
@@ -48,6 +48,10 @@
 #include "atomic_ops.h"
 #include "subdiv_converter.h"
 
+/* -------------------------------------------------------------------- */
+/** \name Local Structs
+ * \{ */
+
 typedef struct SurfacePoint {
   float P[3];
   float tangent_matrix[3][3];
@@ -117,9 +121,11 @@ typedef struct MultiresReshapeSmoothContext {
   SurfaceGrid *base_surface_grids;
 } MultiresReshapeSmoothContext;
 
-/* ================================================================================================
- * Masks.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Masks
+ * \{ */
 
 /* Interpolate mask grid at a reshape level.
  * Will return 0 if there is no masks custom data layer. */
@@ -165,9 +171,11 @@ static float interpolate_masks_grid(const MultiresReshapeSmoothContext *reshape_
          mask_elements[2] * weights[2] + mask_elements[3] * weights[3];
 }
 
-/* ================================================================================================
- * Surface.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Surface
+ * \{ */
 
 static void base_surface_grids_allocate(MultiresReshapeSmoothContext *reshape_smooth_context)
 {
@@ -227,9 +235,11 @@ static void base_surface_grids_write(const MultiresReshapeSmoothContext *reshape
   copy_m3_m3(point->tangent_matrix, tangent_matrix);
 }
 
-/* ================================================================================================
- * Evaluation of subdivision surface at a reshape level.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Evaluation of subdivision surface at a reshape level
+ * \{ */
 
 typedef void (*ForeachTopLevelGridCoordCallback)(
     const MultiresReshapeSmoothContext *reshape_smooth_context,
@@ -383,11 +393,14 @@ static void foreach_toplevel_grid_coord(const MultiresReshapeSmoothContext *resh
       0, num_faces, &data, foreach_toplevel_grid_coord_task, &parallel_range_settings);
 }
 
-/* ================================================================================================
- * Generation of a topology information for OpenSubdiv converter.
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Generation of a topology information for OpenSubdiv converter
  *
  * Calculates vertices, their coordinates in the original grids, and connections of them so then
- * it's easy to create OpenSubdiv's topology refiner. */
+ * it's easy to create OpenSubdiv's topology refiner.
+ * \{ */
 
 static int get_reshape_level_resolution(const MultiresReshapeContext *reshape_context)
 {
@@ -757,9 +770,11 @@ static void geometry_create(MultiresReshapeSmoothContext *reshape_smooth_context
       reshape_context->subdiv, &foreach_context, &mesh_settings, reshape_context->base_mesh);
 }
 
-/* ================================================================================================
- * Generation of OpenSubdiv evaluator for topology created form reshape level.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Generation of OpenSubdiv evaluator for topology created form reshape level
+ * \{ */
 
 static OpenSubdiv_SchemeType get_scheme_type(const OpenSubdiv_Converter *UNUSED(converter))
 {
@@ -1037,9 +1052,11 @@ static void reshape_subdiv_evaluate_limit_at_grid(
   BKE_multires_construct_tangent_matrix(r_tangent_matrix, dPdu, dPdv, corner);
 }
 
-/* ================================================================================================
- * Evaluation of base surface.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Evaluation of base surface
+ * \{ */
 
 static void evaluate_base_surface_grids_callback(
     const MultiresReshapeSmoothContext *reshape_smooth_context,
@@ -1060,9 +1077,11 @@ static void evaluate_base_surface_grids(const MultiresReshapeSmoothContext *resh
   foreach_toplevel_grid_coord(reshape_smooth_context, evaluate_base_surface_grids_callback, NULL);
 }
 
-/* ================================================================================================
- * Evaluation of new surface.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Evaluation of new surface
+ * \{ */
 
 /* Evaluate final position of the original (pre-sculpt-edit) point position at a given grid
  * coordinate. */
@@ -1176,9 +1195,12 @@ static void evaluate_higher_grid_positions(
   foreach_toplevel_grid_coord(
       reshape_smooth_context, evaluate_higher_grid_positions_callback, NULL);
 }
-/* ================================================================================================
- * Entry point.
- */
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Entry point
+ * \{ */
 
 void multires_reshape_smooth_object_grids_with_details(
     const MultiresReshapeContext *reshape_context)
@@ -1226,3 +1248,5 @@ void multires_reshape_smooth_object_grids(const MultiresReshapeContext *reshape_
 
   context_free(&reshape_smooth_context);
 }
+
+/** \} */
diff --git a/source/blender/blenkernel/intern/multires_reshape_util.c b/source/blender/blenkernel/intern/multires_reshape_util.c
index 57d790d2c34..2313aafab30 100644
--- a/source/blender/blenkernel/intern/multires_reshape_util.c
+++ b/source/blender/blenkernel/intern/multires_reshape_util.c
@@ -43,9 +43,9 @@
 
 #include "DEG_depsgraph_query.h"
 
-/* ================================================================================================
- * Construct/destruct reshape context.
- */
+/* -------------------------------------------------------------------- */
+/** \name Construct/destruct reshape context
+ * \{ */
 
 /* Create subdivision surface descriptor which is configured for surface evaluation at a given
  * multires modifier. */
@@ -277,9 +277,11 @@ void multires_reshape_context_free(MultiresReshapeContext *reshape_context)
   MEM_freeN(reshape_context->grid_to_face_index);
 }
 
-/* ================================================================================================
- * Helper accessors.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Helper accessors
+ * \{ */
 
 /* For the given grid index get index of face it was created for. */
 int multires_reshape_grid_to_face_index(const MultiresReshapeContext *reshape_context,
@@ -453,9 +455,11 @@ ReshapeConstGridElement multires_reshape_orig_grid_element_for_grid_coord(
   return grid_element;
 }
 
-/* ================================================================================================
- * Sample limit surface of the base mesh.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Sample limit surface of the base mesh
+ * \{ */
 
 void multires_reshape_evaluate_limit_at_grid(const MultiresReshapeContext *reshape_context,
                                              const GridCoord *grid_coord,
@@ -475,9 +479,11 @@ void multires_reshape_evaluate_limit_at_grid(const MultiresReshapeContext *resha
       reshape_context, face_index, corner, dPdu, dPdv, r_tangent_matrix);
 }
 
-/* ================================================================================================
- * Custom data preparation.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Custom data preparation
+ * \{ */
 
 static void allocate_displacement_grid(MDisps *displacement_grid, const int level)
 {
@@ -539,9 +545,11 @@ void multires_reshape_ensure_grids(Mesh *mesh, const int level)
   ensure_mask_grids(mesh, level);
 }
 
-/* ================================================================================================
- * Displacement, space conversion.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Displacement, space conversion
+ * \{ */
 
 void multires_reshape_store_original_grids(MultiresReshapeContext *reshape_context)
 {
@@ -678,10 +686,13 @@ void multires_reshape_object_grids_to_tangent_displacement(
                           NULL);
 }
 
-/* ================================================================================================
- * MDISPS
- *
- * TODO(sergey): Make foreach_grid_coordinate more accessible and move this functionality to
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name MDISPS
+ * \{ */
+
+/* TODO(sergey): Make foreach_grid_coordinate more accessible and move this functionality to
  * own file. */
 
 static void assign_final_coords_from_mdisps(const MultiresReshapeContext *reshape_context,
@@ -732,3 +743,5 @@ void multires_reshape_assign_final_coords_from_orig_mdisps(
   foreach_grid_coordinate(
       reshape_context, reshape_context->top.level, assign_final_coords_from_orig_mdisps, NULL);
 }
+
+/** \} */
diff --git a/source/blender/blenkernel/intern/subdiv_ccg.c b/source/blender/blenkernel/intern/subdiv_ccg.c
index 6637b3e9b69..d5d5530c1ce 100644
--- a/source/blender/blenkernel/intern/subdiv_ccg.c
+++ b/source/blender/blenkernel/intern/subdiv_ccg.c
@@ -40,9 +40,9 @@
 
 #include "opensubdiv_topology_refiner_capi.h"
 
-/* =============================================================================
- * Various forward declarations.
- */
+/* -------------------------------------------------------------------- */
+/** \name Various forward declarations
+ * \{ */
 
 static void subdiv_ccg_average_all_boundaries_and_corners(SubdivCCG *subdiv_ccg, CCGKey *key);
 
@@ -50,9 +50,11 @@ static void subdiv_ccg_average_inner_face_grids(SubdivCCG *subdiv_ccg,
                                                 CCGKey *key,
                                                 SubdivCCGFace *face);
 
-/* =============================================================================
- * Generally useful internal helpers.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Generally useful internal helpers
+ * \{ */
 
 /* Number of floats in per-vertex elements.  */
 static int num_element_float_get(const SubdivCCG *subdiv_ccg)
@@ -74,9 +76,11 @@ static int element_size_bytes_get(const SubdivCCG *subdiv_ccg)
   return sizeof(float) * num_element_float_get(subdiv_ccg);
 }
 
-/* =============================================================================
- * Internal helpers for CCG creation.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Internal helpers for CCG creation
+ * \{ */
 
 static void subdiv_ccg_init_layers(SubdivCCG *subdiv_ccg, const SubdivToCCGSettings *settings)
 {
@@ -158,9 +162,11 @@ static void subdiv_ccg_alloc_elements(SubdivCCG *subdiv_ccg, Subdiv *subdiv)
   }
 }
 
-/* =============================================================================
- * Grids evaluation.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Grids evaluation
+ * \{ */
 
 typedef struct CCGEvalGridsData {
   SubdivCCG *subdiv_ccg;
@@ -556,9 +562,11 @@ static void subdiv_ccg_init_faces_neighborhood(SubdivCCG *subdiv_ccg)
   subdiv_ccg_init_faces_vertex_neighborhood(subdiv_ccg);
 }
 
-/* =============================================================================
- * Creation / evaluation.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Creation / evaluation
+ * \{ */
 
 SubdivCCG *BKE_subdiv_to_ccg(Subdiv *subdiv,
                              const SubdivToCCGSettings *settings,
@@ -670,9 +678,11 @@ void BKE_subdiv_ccg_key_top_level(CCGKey *key, const SubdivCCG *subdiv_ccg)
   BKE_subdiv_ccg_key(key, subdiv_ccg, subdiv_ccg->level);
 }
 
-/* =============================================================================
- * Normals.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Normals
+ * \{ */
 
 typedef struct RecalcInnerNormalsData {
   SubdivCCG *subdiv_ccg;
@@ -885,9 +895,11 @@ void BKE_subdiv_ccg_update_normals(SubdivCCG *subdiv_ccg,
   subdiv_ccg_average_all_boundaries_and_corners(subdiv_ccg, &key);
 }
 
-/* =============================================================================
- * Boundary averaging/stitching.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Boundary averaging/stitching
+ * \{ */
 
 typedef struct AverageInnerGridsData {
   SubdivCCG *subdiv_ccg;
@@ -1244,9 +1256,11 @@ void BKE_subdiv_ccg_topology_counters(const SubdivCCG *subdiv_ccg,
   *r_num_loops = *r_num_faces * 4;
 }
 
-/* =============================================================================
- * Neighbors.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Neighbors
+ * \{ */
 
 void BKE_subdiv_ccg_print_coord(const char *message, const SubdivCCGCoord *coord)
 {
@@ -1791,3 +1805,5 @@ int BKE_subdiv_ccg_grid_to_face_index(const SubdivCCG *subdiv_ccg, const int gri
   const int face_index = face - subdiv_ccg->faces;
   return face_index;
 }
+
+/** \} */
diff --git a/source/blender/blenkernel/intern/subdiv_deform.c b/source/blender/blenkernel/intern/subdiv_deform.c
index db0a51c390b..f03cf4c4d21 100644
--- a/source/blender/blenkernel/intern/subdiv_deform.c
+++ b/source/blender/blenkernel/intern/subdiv_deform.c
@@ -39,9 +39,9 @@
 
 #include "MEM_guardedalloc.h"
 
-/* ================================================================================================
- * Subdivision context.
- */
+/* -------------------------------------------------------------------- */
+/** \name Subdivision context
+ * \{ */
 
 typedef struct SubdivDeformContext {
   const Mesh *coarse_mesh;
@@ -77,9 +77,11 @@ static void subdiv_mesh_context_free(SubdivDeformContext *ctx)
   MEM_SAFE_FREE(ctx->accumulated_counters);
 }
 
-/* ================================================================================================
- * Accumulation helpers.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Accumulation helpers
+ * \{ */
 
 static void subdiv_accumulate_vertex_displacement(SubdivDeformContext *ctx,
                                                   const int ptex_face_index,
@@ -105,9 +107,11 @@ static void subdiv_accumulate_vertex_displacement(SubdivDeformContext *ctx,
   ++ctx->accumulated_counters[vertex_index];
 }
 
-/* ================================================================================================
- * Subdivision callbacks.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Subdivision callbacks
+ * \{ */
 
 static bool subdiv_mesh_topology_info(const SubdivForeachContext *foreach_context,
                                       const int UNUSED(num_vertices),
@@ -165,9 +169,11 @@ static void subdiv_mesh_vertex_corner(const SubdivForeachContext *foreach_contex
   add_v3_v3(vertex_co, D);
 }
 
-/* ================================================================================================
- * Initialization.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Initialization
+ * \{ */
 
 static void setup_foreach_callbacks(const SubdivDeformContext *subdiv_context,
                                     SubdivForeachContext *foreach_context)
@@ -182,9 +188,11 @@ static void setup_foreach_callbacks(const SubdivDeformContext *subdiv_context,
   foreach_context->vertex_corner = subdiv_mesh_vertex_corner;
 }
 
-/* ================================================================================================
- * Public entry point.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Public entry point
+ * \{ */
 
 void BKE_subdiv_deform_coarse_vertices(struct Subdiv *subdiv,
                                        const struct Mesh *coarse_mesh,
@@ -234,3 +242,5 @@ void BKE_subdiv_deform_coarse_vertices(struct Subdiv *subdiv,
   /* Free used memory. */
   subdiv_mesh_context_free(&subdiv_context);
 }
+
+/** \} */
diff --git a/source/blender/blenkernel/intern/subdiv_foreach.c b/source/blender/blenkernel/intern/subdiv_foreach.c
index 0884f40952f..ff7f6fad5f0 100644
--- a/source/blender/blenkernel/intern/subdiv_foreach.c
+++ b/source/blender/blenkernel/intern/subdiv_foreach.c
@@ -40,9 +40,9 @@
 
 #include "MEM_guardedalloc.h"
 
-/* =============================================================================
- * General helpers.
- */
+/* -------------------------------------------------------------------- */
+/** \name General helpers
+ * \{ */
 
 /* Number of ptex faces for a given polygon. */
 BLI_INLINE int num_ptex_faces_per_poly_get(const MPoly *poly)
@@ -75,9 +75,11 @@ BLI_INLINE int ptex_face_resolution_get(const MPoly *poly, int resolution)
   return (poly->totloop == 4) ? (resolution) : ((resolution >> 1) + 1);
 }
 
-/* =============================================================================
- * Context which is passed to all threaded tasks.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Context which is passed to all threaded tasks
+ * \{ */
 
 typedef struct SubdivForeachTaskContext {
   const Mesh *coarse_mesh;
@@ -122,9 +124,11 @@ typedef struct SubdivForeachTaskContext {
   BLI_bitmap *coarse_edges_used_map;
 } SubdivForeachTaskContext;
 
-/* =============================================================================
- * Threading helpers.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Threading helpers
+ * \{ */
 
 static void *subdiv_foreach_tls_alloc(SubdivForeachTaskContext *ctx)
 {
@@ -148,9 +152,11 @@ static void subdiv_foreach_tls_free(SubdivForeachTaskContext *ctx, void *tls)
   MEM_freeN(tls);
 }
 
-/* =============================================================================
- * Initialization.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Initialization
+ * \{ */
 
 /* NOTE: Expects edge map to be zeroed. */
 static void subdiv_foreach_ctx_count(SubdivForeachTaskContext *ctx)
@@ -294,9 +300,11 @@ static void subdiv_foreach_ctx_free(SubdivForeachTaskContext *ctx)
   MEM_freeN(ctx->subdiv_polygon_offset);
 }
 
-/* =============================================================================
- * Vertex traversal process.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Vertex traversal process
+ * \{ */
 
 /* Traversal of corner vertices. They are coming from coarse vertices. */
 
@@ -706,9 +714,11 @@ static void subdiv_foreach_vertices(SubdivForeachTaskContext *ctx, void *tls, co
   }
 }
 
-/* =============================================================================
- * Edge traversal process.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Edge traversal process
+ * \{ */
 
 /* TODO(sergey): Coarse edge are always NONE, consider getting rid of it. */
 static int subdiv_foreach_edges_row(SubdivForeachTaskContext *ctx,
@@ -1022,9 +1032,11 @@ static void subdiv_foreach_boundary_edges(SubdivForeachTaskContext *ctx,
       ctx->foreach_context, tls, coarse_edge_index, subdiv_edge_index, v1, v2);
 }
 
-/* =============================================================================
- * Loops traversal.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Loops traversal
+ * \{ */
 
 static void rotate_indices(const int rot, int *a, int *b, int *c, int *d)
 {
@@ -1666,9 +1678,11 @@ static void subdiv_foreach_loops(SubdivForeachTaskContext *ctx, void *tls, int p
   }
 }
 
-/* =============================================================================
- * Polygons traverse process.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Polygons traverse process
+ * \{ */
 
 static void subdiv_foreach_polys(SubdivForeachTaskContext *ctx, void *tls, int poly_index)
 {
@@ -1697,9 +1711,11 @@ static void subdiv_foreach_polys(SubdivForeachTaskContext *ctx, void *tls, int p
   }
 }
 
-/* =============================================================================
- * Loose elements traverse process.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Loose elements traverse process
+ * \{ */
 
 static void subdiv_foreach_loose_vertices_task(void *__restrict userdata,
                                                const int coarse_vertex_index,
@@ -1754,9 +1770,11 @@ static void subdiv_foreach_vertices_of_loose_edges_task(void *__restrict userdat
   }
 }
 
-/* =============================================================================
- * Subdivision process entry points.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Subdivision process entry points
+ * \{ */
 
 static void subdiv_foreach_single_geometry_vertices(SubdivForeachTaskContext *ctx, void *tls)
 {
@@ -1908,3 +1926,5 @@ bool BKE_subdiv_foreach_subdiv_geometry(Subdiv *subdiv,
   subdiv_foreach_ctx_free(&ctx);
   return true;
 }
+
+/** \} */
diff --git a/source/blender/blenkernel/intern/subdiv_mesh.c b/source/blender/blenkernel/intern/subdiv_mesh.c
index bd091108b11..987cc0311c7 100644
--- a/source/blender/blenkernel/intern/subdiv_mesh.c
+++ b/source/blender/blenkernel/intern/subdiv_mesh.c
@@ -41,9 +41,9 @@
 
 #include "MEM_guardedalloc.h"
 
-/* =============================================================================
- * Subdivision context.
- */
+/* -------------------------------------------------------------------- */
+/** \name Subdivision Context
+ * \{ */
 
 typedef struct SubdivMeshContext {
   const SubdivToMeshSettings *settings;
@@ -119,9 +119,11 @@ static void subdiv_mesh_context_free(SubdivMeshContext *ctx)
   MEM_SAFE_FREE(ctx->accumulated_counters);
 }
 
-/* =============================================================================
- * Loop custom data copy helpers.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Loop custom data copy helpers
+ * \{ */
 
 typedef struct LoopsOfPtex {
   /* First loop of the ptex, starts at ptex (0, 0) and goes in u direction. */
@@ -159,9 +161,11 @@ static void loops_of_ptex_get(const SubdivMeshContext *ctx,
   }
 }
 
-/* =============================================================================
- * Vertex custom data interpolation helpers.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Vertex custom data interpolation helpers
+ * \{ */
 
 /* TODO(sergey): Somehow de-duplicate with loops storage, without too much
  * exception cases all over the code. */
@@ -295,9 +299,11 @@ static void vertex_interpolation_end(VerticesForInterpolation *vertex_interpolat
   }
 }
 
-/* =============================================================================
- * Loop custom data interpolation helpers.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Loop custom data interpolation helpers
+ * \{ */
 
 typedef struct LoopsForInterpolation {
   /* This field points to a loop data which is to be used for interpolation.
@@ -413,9 +419,11 @@ static void loop_interpolation_end(LoopsForInterpolation *loop_interpolation)
   }
 }
 
-/* =============================================================================
- * TLS.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name TLS
+ * \{ */
 
 typedef struct SubdivMeshTLS {
   bool vertex_interpolation_initialized;
@@ -440,9 +448,11 @@ static void subdiv_mesh_tls_free(void *tls_v)
   }
 }
 
-/* =============================================================================
- * Evaluation helper functions.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Evaluation helper functions
+ * \{ */
 
 static void eval_final_point_and_vertex_normal(Subdiv *subdiv,
                                                const int ptex_face_index,
@@ -459,9 +469,11 @@ static void eval_final_point_and_vertex_normal(Subdiv *subdiv,
   }
 }
 
-/* =============================================================================
- * Accumulation helpers.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Accumulation helpers
+ * \{ */
 
 static void subdiv_accumulate_vertex_normal_and_displacement(SubdivMeshContext *ctx,
                                                              const int ptex_face_index,
@@ -490,9 +502,11 @@ static void subdiv_accumulate_vertex_normal_and_displacement(SubdivMeshContext *
   ++ctx->accumulated_counters[subdiv_vertex_index];
 }
 
-/* =============================================================================
- * Callbacks.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Callbacks
+ * \{ */
 
 static bool subdiv_mesh_topology_info(const SubdivForeachContext *foreach_context,
                                       const int num_vertices,
@@ -513,9 +527,11 @@ static bool subdiv_mesh_topology_info(const SubdivForeachContext *foreach_contex
   return true;
 }
 
-/* =============================================================================
- * Vertex subdivision process.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Vertex subdivision process
+ * \{ */
 
 static void subdiv_vertex_data_copy(const SubdivMeshContext *ctx,
                                     const MVert *coarse_vertex,
@@ -778,9 +794,11 @@ static void subdiv_mesh_vertex_inner(const SubdivForeachContext *foreach_context
   subdiv_mesh_tag_center_vertex(coarse_poly, subdiv_vert, u, v);
 }
 
-/* =============================================================================
- * Edge subdivision process.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Edge subdivision process
+ * \{ */
 
 static void subdiv_copy_edge_data(SubdivMeshContext *ctx,
                                   MEdge *subdiv_edge,
@@ -827,9 +845,11 @@ static void subdiv_mesh_edge(const SubdivForeachContext *foreach_context,
   subdiv_edge->v2 = subdiv_v2;
 }
 
-/* =============================================================================
- * Loops creation/interpolation.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Loops creation/interpolation
+ * \{ */
 
 static void subdiv_interpolate_loop_data(const SubdivMeshContext *ctx,
                                          MLoop *subdiv_loop,
@@ -921,9 +941,11 @@ static void subdiv_mesh_loop(const SubdivForeachContext *foreach_context,
   subdiv_loop->e = subdiv_edge_index;
 }
 
-/* =============================================================================
- * Polygons subdivision process.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Polygons subdivision process
+ * \{ */
 
 static void subdiv_copy_poly_data(const SubdivMeshContext *ctx,
                                   MPoly *subdiv_poly,
@@ -955,9 +977,11 @@ static void subdiv_mesh_poly(const SubdivForeachContext *foreach_context,
   subdiv_poly->totloop = num_loops;
 }
 
-/* =============================================================================
- * Loose elements subdivision process.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Loose elements subdivision process
+ * \{ */
 
 static void subdiv_mesh_vertex_loose(const SubdivForeachContext *foreach_context,
                                      void *UNUSED(tls),
@@ -1127,9 +1151,11 @@ static void subdiv_mesh_vertex_of_loose_edge(const struct SubdivForeachContext *
   normal_float_to_short_v3(subdiv_vertex->no, no);
 }
 
-/* =============================================================================
- * Initialization.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Initialization
+ * \{ */
 
 static void setup_foreach_callbacks(const SubdivMeshContext *subdiv_context,
                                     SubdivForeachContext *foreach_context)
@@ -1157,9 +1183,11 @@ static void setup_foreach_callbacks(const SubdivMeshContext *subdiv_context,
   foreach_context->user_data_tls_free = subdiv_mesh_tls_free;
 }
 
-/* =============================================================================
- * Public entry point.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Public entry point
+ * \{ */
 
 Mesh *BKE_subdiv_to_mesh(Subdiv *subdiv,
                          const SubdivToMeshSettings *settings,
@@ -1206,3 +1234,5 @@ Mesh *BKE_subdiv_to_mesh(Subdiv *subdiv,
   subdiv_mesh_context_free(&subdiv_context);
   return result;
 }
+
+/** \} */