Cleanup: move public doc-strings into headers

Some recent changes re-introduced public-style doc-strings
in the source file.

20 files changed, 225 insertions, 224 deletions

diff --git a/source/blender/blenkernel/BKE_gpencil_modifier.h b/source/blender/blenkernel/BKE_gpencil_modifier.h
index 5fc0abf6a2c..6c8edf598f1 100644
--- a/source/blender/blenkernel/BKE_gpencil_modifier.h
+++ b/source/blender/blenkernel/BKE_gpencil_modifier.h
@@ -407,7 +407,15 @@ void BKE_gpencil_set_lineart_modifier_limits(struct GpencilModifierData *md,
 bool BKE_gpencil_is_first_lineart_in_stack(const struct Object *ob,
                                            const struct GpencilModifierData *md);
 
+/**
+ * Init grease pencil cache deform data.
+ * \param ob: Grease pencil object
+ */
 void BKE_gpencil_cache_data_init(struct Depsgraph *depsgraph, struct Object *ob);
+/**
+ * Clear grease pencil cache deform data.
+ * \param ob: Grease pencil object
+ */
 void BKE_gpencil_cache_data_clear(struct Object *ob);
 
 /**
diff --git a/source/blender/blenkernel/intern/gpencil_modifier.c b/source/blender/blenkernel/intern/gpencil_modifier.c
index 62604286b43..74db151261f 100644
--- a/source/blender/blenkernel/intern/gpencil_modifier.c
+++ b/source/blender/blenkernel/intern/gpencil_modifier.c
@@ -79,10 +79,6 @@ static GpencilVirtualModifierData virtualModifierCommonData;
  * each loop over all the geometry being evaluated.
  */
 
-/**
- * Init grease pencil cache deform data.
- * \param ob: Grease pencil object
- */
 void BKE_gpencil_cache_data_init(Depsgraph *depsgraph, Object *ob)
 {
   LISTBASE_FOREACH (GpencilModifierData *, md, &ob->greasepencil_modifiers) {
@@ -131,10 +127,6 @@ void BKE_gpencil_cache_data_init(Depsgraph *depsgraph, Object *ob)
   }
 }
 
-/**
- * Clear grease pencil cache deform data.
- * \param ob: Grease pencil object
- */
 void BKE_gpencil_cache_data_clear(Object *ob)
 {
   LISTBASE_FOREACH (GpencilModifierData *, md, &ob->greasepencil_modifiers) {
diff --git a/source/blender/blenlib/BLI_serialize.hh b/source/blender/blenlib/BLI_serialize.hh
index 5945960c450..05606794994 100644
--- a/source/blender/blenlib/BLI_serialize.hh
+++ b/source/blender/blenlib/BLI_serialize.hh
@@ -123,7 +123,7 @@ using ArrayValue = ContainerValue<Vector<std::shared_ptr<Value>>, eValueType::Ar
  * - `BooleanValue`: contains a boolean (true/false).
  * - `DoubleValue`: contains a double precision floating point number.
  * - `DictionaryValue`: represents an object (key value pairs where keys are strings and values can
- * be of different types.
+ *   be of different types.
  *
  */
 class Value {
diff --git a/source/blender/blenloader/intern/versioning_300.c b/source/blender/blenloader/intern/versioning_300.c
index 035aa293b62..5a93e81d2b1 100644
--- a/source/blender/blenloader/intern/versioning_300.c
+++ b/source/blender/blenloader/intern/versioning_300.c
@@ -2527,4 +2527,4 @@ void blo_do_versions_300(FileData *fd, Library *UNUSED(lib), Main *bmain)
       }
     }
   }
-}
\ No newline at end of file
+}
diff --git a/source/blender/blenloader/intern/versioning_common.cc b/source/blender/blenloader/intern/versioning_common.cc
index 752157bffde..575bfd565e6 100644
--- a/source/blender/blenloader/intern/versioning_common.cc
+++ b/source/blender/blenloader/intern/versioning_common.cc
@@ -224,10 +224,6 @@ void version_node_socket_index_animdata(Main *bmain,
   }
 }
 
-/**
- * The versioning code generally expects `SOCK_IN_USE` to be set correctly. This function updates
- * the flag on all sockets after changes to the node tree.
- */
 void version_socket_update_is_used(bNodeTree *ntree)
 {
   LISTBASE_FOREACH (bNode *, node, &ntree->nodes) {
diff --git a/source/blender/blenloader/intern/versioning_common.h b/source/blender/blenloader/intern/versioning_common.h
index dd1dd1f22f2..9e13cc45103 100644
--- a/source/blender/blenloader/intern/versioning_common.h
+++ b/source/blender/blenloader/intern/versioning_common.h
@@ -100,6 +100,10 @@ struct bNodeSocket *version_node_add_socket_if_not_exist(struct bNodeTree *ntree
                                                          const char *identifier,
                                                          const char *name);
 
+/**
+ * The versioning code generally expects `SOCK_IN_USE` to be set correctly. This function updates
+ * the flag on all sockets after changes to the node tree.
+ */
 void version_socket_update_is_used(bNodeTree *ntree);
 
 #ifdef __cplusplus
diff --git a/source/blender/editors/animation/keyframes_general.c b/source/blender/editors/animation/keyframes_general.c
index 8aac1e9b779..5d82b3b9939 100644
--- a/source/blender/editors/animation/keyframes_general.c
+++ b/source/blender/editors/animation/keyframes_general.c
@@ -345,10 +345,6 @@ static bool find_fcurve_segment(FCurve *fcu,
   return in_segment;
 }
 
-/* Return a list of FCurveSegment with a start index and a length.
- * A segment is a continuous selection of keyframes.
- * Keys that have BEZT_FLAG_IGNORE_TAG set are treated as unselected.
- * The caller is responsible for freeing the memory. */
 ListBase find_fcurve_segments(FCurve *fcu)
 {
   ListBase segments = {NULL, NULL};
diff --git a/source/blender/editors/animation/keyframes_keylist.cc b/source/blender/editors/animation/keyframes_keylist.cc
index 8dae46766fa..e4641ead2d2 100644
--- a/source/blender/editors/animation/keyframes_keylist.cc
+++ b/source/blender/editors/animation/keyframes_keylist.cc
@@ -850,7 +850,6 @@ bool actkeyblock_is_valid(const ActKeyColumn *ac)
   return ac != nullptr && ac->next != nullptr && ac->totblock > 0;
 }
 
-/* Checks if ActKeyBlock should exist... */
 int actkeyblock_get_valid_hold(const ActKeyColumn *ac)
 {
   /* check that block is valid */
diff --git a/source/blender/editors/include/ED_keyframes_edit.h b/source/blender/editors/include/ED_keyframes_edit.h
index c54fb93e495..d08abf8aab8 100644
--- a/source/blender/editors/include/ED_keyframes_edit.h
+++ b/source/blender/editors/include/ED_keyframes_edit.h
@@ -327,13 +327,13 @@ KeyframeEditFunc ANIM_editkeyframes_easing(short mode);
 
 /**
  * Get a callback to populate the selection settings map
- * requires: ked->custom = char[] of length fcurve->totvert.
+ * requires: `ked->custom = char[]` of length `fcurve->totvert`.
  */
 KeyframeEditFunc ANIM_editkeyframes_buildselmap(short mode);
 
 /**
  * Change the selection status of the keyframe based on the map entry for this vert
- * requires: ked->custom = char[] of length fcurve->totvert.
+ * requires: `ked->custom = char[]` of length `fcurve->totvert`.
  */
 short bezt_selmap_flush(KeyframeEditData *ked, struct BezTriple *bezt);
 
@@ -384,6 +384,13 @@ typedef struct FCurveSegment {
   struct FCurveSegment *next, *prev;
   int start_index, length;
 } FCurveSegment;
+
+/**
+ * Return a list of #FCurveSegment with a start index and a length.
+ * A segment is a continuous selection of keyframes.
+ * Keys that have BEZT_FLAG_IGNORE_TAG set are treated as unselected.
+ * The caller is responsible for freeing the memory.
+ */
 ListBase find_fcurve_segments(struct FCurve *fcu);
 void clean_fcurve(struct bAnimContext *ac,
                   struct bAnimListElem *ale,
diff --git a/source/blender/editors/sculpt_paint/sculpt.c b/source/blender/editors/sculpt_paint/sculpt.c
index fd550790f2e..21bbc9fb543 100644
--- a/source/blender/editors/sculpt_paint/sculpt.c
+++ b/source/blender/editors/sculpt_paint/sculpt.c
@@ -2128,10 +2128,6 @@ bool SCULPT_pbvh_calc_area_normal(const Brush *brush,
   return data.any_vertex_sampled;
 }
 
-/**
- * This calculates flatten center and area normal together,
- * amortizing the memory bandwidth and loop overhead to calculate both at the same time.
- */
 void SCULPT_calc_area_normal_and_center(
     Sculpt *sd, Object *ob, PBVHNode **nodes, int totnode, float r_area_no[3], float r_area_co[3])
 {
@@ -3963,8 +3959,7 @@ static const char *sculpt_tool_name(Sculpt *sd)
   return "Sculpting";
 }
 
-/**
- * Operator for applying a stroke (various attributes including mouse path)
+/* Operator for applying a stroke (various attributes including mouse path)
  * using the current brush. */
 
 void SCULPT_cache_free(StrokeCache *cache)
diff --git a/source/blender/editors/sculpt_paint/sculpt_intern.h b/source/blender/editors/sculpt_paint/sculpt_intern.h
index 35ffb214185..f239d12b69e 100644
--- a/source/blender/editors/sculpt_paint/sculpt_intern.h
+++ b/source/blender/editors/sculpt_paint/sculpt_intern.h
@@ -300,6 +300,10 @@ void SCULPT_calc_brush_plane(struct Sculpt *sd,
 
 void SCULPT_calc_area_normal(
     Sculpt *sd, Object *ob, PBVHNode **nodes, int totnode, float r_area_no[3]);
+/**
+ * This calculates flatten center and area normal together,
+ * amortizing the memory bandwidth and loop overhead to calculate both at the same time.
+ */
 void SCULPT_calc_area_normal_and_center(
     Sculpt *sd, Object *ob, PBVHNode **nodes, int totnode, float r_area_no[3], float r_area_co[3]);
 void SCULPT_calc_area_center(
diff --git a/source/blender/gpu/intern/gpu_backend.hh b/source/blender/gpu/intern/gpu_backend.hh
index d472e48776e..00645f34173 100644
--- a/source/blender/gpu/intern/gpu_backend.hh
+++ b/source/blender/gpu/intern/gpu_backend.hh
@@ -42,7 +42,7 @@ class VertBuf;
 
 class GPUBackend {
  public:
-  virtual ~GPUBackend()= default;;
+  virtual ~GPUBackend() = default;
 
   static GPUBackend *get();
 
diff --git a/source/blender/io/wavefront_obj/exporter/obj_export_file_writer.cc b/source/blender/io/wavefront_obj/exporter/obj_export_file_writer.cc
index 8c4ae7e111e..45fa75c65b3 100644
--- a/source/blender/io/wavefront_obj/exporter/obj_export_file_writer.cc
+++ b/source/blender/io/wavefront_obj/exporter/obj_export_file_writer.cc
@@ -52,9 +52,6 @@ const char *DEFORM_GROUP_DISABLED = "off";
  * So an empty material name is written. */
 const char *MATERIAL_GROUP_DISABLED = "";
 
-/**
- * Write one line of polygon indices as "f v1/vt1/vn1 v2/vt2/vn2 ...".
- */
 void OBJWriter::write_vert_uv_normal_indices(Span<int> vert_indices,
                                              Span<int> uv_indices,
                                              Span<int> normal_indices) const
@@ -71,9 +68,6 @@ void OBJWriter::write_vert_uv_normal_indices(Span<int> vert_indices,
   file_handler_->write<eOBJSyntaxElement::poly_element_end>();
 }
 
-/**
- * Write one line of polygon indices as "f v1//vn1 v2//vn2 ...".
- */
 void OBJWriter::write_vert_normal_indices(Span<int> vert_indices,
                                           Span<int> /*uv_indices*/,
                                           Span<int> normal_indices) const
@@ -88,9 +82,6 @@ void OBJWriter::write_vert_normal_indices(Span<int> vert_indices,
   file_handler_->write<eOBJSyntaxElement::poly_element_end>();
 }
 
-/**
- * Write one line of polygon indices as "f v1/vt1 v2/vt2 ...".
- */
 void OBJWriter::write_vert_uv_indices(Span<int> vert_indices,
                                       Span<int> uv_indices,
                                       Span<int> /*normal_indices*/) const
@@ -105,9 +96,6 @@ void OBJWriter::write_vert_uv_indices(Span<int> vert_indices,
   file_handler_->write<eOBJSyntaxElement::poly_element_end>();
 }
 
-/**
- * Write one line of polygon indices as "f v1 v2 ...".
- */
 void OBJWriter::write_vert_indices(Span<int> vert_indices,
                                    Span<int> /*uv_indices*/,
                                    Span<int> /*normal_indices*/) const
@@ -128,9 +116,6 @@ void OBJWriter::write_header() const
   file_handler_->write<eOBJSyntaxElement::string>("# www.blender.org\n");
 }
 
-/**
- * Write file name of Material Library in .OBJ file.
- */
 void OBJWriter::write_mtllib_name(const StringRefNull mtl_filepath) const
 {
   /* Split .MTL file path into parent directory and filename. */
@@ -140,9 +125,6 @@ void OBJWriter::write_mtllib_name(const StringRefNull mtl_filepath) const
   file_handler_->write<eOBJSyntaxElement::mtllib>(mtl_file_name);
 }
 
-/**
- * Write an object's group with mesh and/or material name appended conditionally.
- */
 void OBJWriter::write_object_group(const OBJMesh &obj_mesh_data) const
 {
   /* "o object_name" is not mandatory. A valid .OBJ file may contain neither
@@ -163,9 +145,6 @@ void OBJWriter::write_object_group(const OBJMesh &obj_mesh_data) const
   file_handler_->write<eOBJSyntaxElement::object_group>(object_name + "_" + object_mesh_name);
 }
 
-/**
- * Write object's name or group.
- */
 void OBJWriter::write_object_name(const OBJMesh &obj_mesh_data) const
 {
   const char *object_name = obj_mesh_data.get_object_name();
@@ -176,9 +155,6 @@ void OBJWriter::write_object_name(const OBJMesh &obj_mesh_data) const
   file_handler_->write<eOBJSyntaxElement::object_name>(object_name);
 }
 
-/**
- * Write vertex coordinates for all vertices as "v x y z".
- */
 void OBJWriter::write_vertex_coords(const OBJMesh &obj_mesh_data) const
 {
   const int tot_vertices = obj_mesh_data.tot_vertices();
@@ -188,10 +164,6 @@ void OBJWriter::write_vertex_coords(const OBJMesh &obj_mesh_data) const
   }
 }
 
-/**
- * Write UV vertex coordinates for all vertices as `vt u v`.
- * \note UV indices are stored here, but written later.
- */
 void OBJWriter::write_uv_coords(OBJMesh &r_obj_mesh_data) const
 {
   Vector<std::array<float, 2>> uv_coords;
@@ -203,9 +175,6 @@ void OBJWriter::write_uv_coords(OBJMesh &r_obj_mesh_data) const
   }
 }
 
-/**
- * Write loop normals for smooth-shaded polygons, and polygon normals otherwise, as "vn x y z".
- */
 void OBJWriter::write_poly_normals(const OBJMesh &obj_mesh_data) const
 {
   obj_mesh_data.ensure_mesh_normals();
@@ -226,9 +195,6 @@ void OBJWriter::write_poly_normals(const OBJMesh &obj_mesh_data) const
   }
 }
 
-/**
- * Write smooth group if polygon at the given index is shaded smooth else "s 0"
- */
 int OBJWriter::write_smooth_group(const OBJMesh &obj_mesh_data,
                                   const int poly_index,
                                   const int last_poly_smooth_group) const
@@ -251,11 +217,6 @@ int OBJWriter::write_smooth_group(const OBJMesh &obj_mesh_data,
   return current_group;
 }
 
-/**
- * Write material name and material group of a polygon in the .OBJ file.
- * \return #mat_nr of the polygon at the given index.
- * \note It doesn't write to the material library.
- */
 int16_t OBJWriter::write_poly_material(const OBJMesh &obj_mesh_data,
                                        const int poly_index,
                                        const int16_t last_poly_mat_nr,
@@ -286,9 +247,6 @@ int16_t OBJWriter::write_poly_material(const OBJMesh &obj_mesh_data,
   return current_mat_nr;
 }
 
-/**
- * Write the name of the deform group of a polygon.
- */
 int16_t OBJWriter::write_vertex_group(const OBJMesh &obj_mesh_data,
                                       const int poly_index,
                                       const int16_t last_poly_vertex_group) const
@@ -311,9 +269,6 @@ int16_t OBJWriter::write_vertex_group(const OBJMesh &obj_mesh_data,
   return current_group;
 }
 
-/**
- * \return Writer function with appropriate polygon-element syntax.
- */
 OBJWriter::func_vert_uv_normal_indices OBJWriter::get_poly_element_writer(
     const int total_uv_vertices) const
 {
@@ -333,13 +288,6 @@ OBJWriter::func_vert_uv_normal_indices OBJWriter::get_poly_element_writer(
   return &OBJWriter::write_vert_indices;
 }
 
-/**
- * Write polygon elements with at least vertex indices, and conditionally with UV vertex
- * indices and polygon normal indices. Also write groups: smooth, vertex, material.
- * The matname_fn turns a 0-indexed material slot number in an Object into the
- * name used in the .obj file.
- * \note UV indices were stored while writing UV vertices.
- */
 void OBJWriter::write_poly_elements(const OBJMesh &obj_mesh_data,
                                     std::function<const char *(int)> matname_fn)
 {
@@ -374,9 +322,6 @@ void OBJWriter::write_poly_elements(const OBJMesh &obj_mesh_data,
   index_offsets_.normal_offset += per_object_tot_normals;
 }
 
-/**
- * Write loose edges of a mesh as "l v1 v2".
- */
 void OBJWriter::write_edges_indices(const OBJMesh &obj_mesh_data) const
 {
   obj_mesh_data.ensure_mesh_edges();
@@ -393,9 +338,6 @@ void OBJWriter::write_edges_indices(const OBJMesh &obj_mesh_data) const
   }
 }
 
-/**
- * Write a NURBS curve to the .OBJ file in parameter form.
- */
 void OBJWriter::write_nurbs_curve(const OBJCurve &obj_nurbs_data) const
 {
   const int total_splines = obj_nurbs_data.total_splines();
@@ -444,10 +386,6 @@ void OBJWriter::write_nurbs_curve(const OBJCurve &obj_nurbs_data) const
   }
 }
 
-/**
- * When there are multiple objects in a frame, the indices of previous objects' coordinates or
- * normals add up.
- */
 void OBJWriter::update_index_offsets(const OBJMesh &obj_mesh_data)
 {
   index_offsets_.vertex_offset += obj_mesh_data.tot_vertices();
@@ -470,9 +408,6 @@ static std::string float3_to_string(const float3 &numbers)
   return r_string.str();
 };
 
-/*
- * Create the .MTL file.
- */
 MTLWriter::MTLWriter(const char *obj_filepath) noexcept(false)
 {
   mtl_filepath_ = obj_filepath;
@@ -499,9 +434,6 @@ StringRefNull MTLWriter::mtl_file_path() const
   return mtl_filepath_;
 }
 
-/**
- * Write properties sourced from p-BSDF node or #Object.Material.
- */
 void MTLWriter::write_bsdf_properties(const MTLMaterial &mtl_material)
 {
   file_handler_->write<eMTLSyntaxElement::Ns>(mtl_material.Ns);
@@ -518,9 +450,6 @@ void MTLWriter::write_bsdf_properties(const MTLMaterial &mtl_material)
   file_handler_->write<eMTLSyntaxElement::illum>(mtl_material.illum);
 }
 
-/**
- * Write a texture map in the form "map_XX -s 1. 1. 1. -o 0. 0. 0. [-bm 1.] path/to/image".
- */
 void MTLWriter::write_texture_map(
     const MTLMaterial &mtl_material,
     const Map<const eMTLSyntaxElement, tex_map_XX>::Item &texture_map)
@@ -557,11 +486,6 @@ void MTLWriter::write_texture_map(
   BLI_assert(!"This map type was not written to the file.");
 }
 
-/**
- * Write all of the material specifications to the MTL file.
- * For consistency of output from run to run (useful for testing),
- * the materials are sorted by name before writing.
- */
 void MTLWriter::write_materials()
 {
   if (mtlmaterials_.size() == 0) {
@@ -583,14 +507,6 @@ void MTLWriter::write_materials()
   }
 }
 
-/**
- * Add the materials of the given object to #MTLWriter, de-duplicating
- * against ones that are already there.
- * Return a Vector of indices into mtlmaterials_ that hold the #MTLMaterial
- * that corresponds to each material slot, in order, of the given Object.
- * Indexes are returned rather than pointers to the MTLMaterials themselves
- * because the mtlmaterials_ Vector may move around when resized.
- */
 Vector<int> MTLWriter::add_materials(const OBJMesh &mesh_to_export)
 {
   Vector<int> r_mtl_indices;
diff --git a/source/blender/io/wavefront_obj/exporter/obj_export_file_writer.hh b/source/blender/io/wavefront_obj/exporter/obj_export_file_writer.hh
index 36d35ae370b..c7ec7ec648f 100644
--- a/source/blender/io/wavefront_obj/exporter/obj_export_file_writer.hh
+++ b/source/blender/io/wavefront_obj/exporter/obj_export_file_writer.hh
@@ -61,44 +61,106 @@ class OBJWriter : NonMovable, NonCopyable {
 
   void write_header() const;
 
+  /**
+   * Write object's name or group.
+   */
   void write_object_name(const OBJMesh &obj_mesh_data) const;
+  /**
+   * Write an object's group with mesh and/or material name appended conditionally.
+   */
   void write_object_group(const OBJMesh &obj_mesh_data) const;
+  /**
+   * Write file name of Material Library in .OBJ file.
+   */
   void write_mtllib_name(const StringRefNull mtl_filepath) const;
+  /**
+   * Write vertex coordinates for all vertices as "v x y z".
+   */
   void write_vertex_coords(const OBJMesh &obj_mesh_data) const;
+  /**
+   * Write UV vertex coordinates for all vertices as `vt u v`.
+   * \note UV indices are stored here, but written later.
+   */
   void write_uv_coords(OBJMesh &obj_mesh_data) const;
+  /**
+   * Write loop normals for smooth-shaded polygons, and polygon normals otherwise, as "vn x y z".
+   */
   void write_poly_normals(const OBJMesh &obj_mesh_data) const;
+  /**
+   * Write smooth group if polygon at the given index is shaded smooth else "s 0"
+   */
   int write_smooth_group(const OBJMesh &obj_mesh_data,
                          int poly_index,
                          const int last_poly_smooth_group) const;
+  /**
+   * Write material name and material group of a polygon in the .OBJ file.
+   * \return #mat_nr of the polygon at the given index.
+   * \note It doesn't write to the material library.
+   */
   int16_t write_poly_material(const OBJMesh &obj_mesh_data,
                               const int poly_index,
                               const int16_t last_poly_mat_nr,
                               std::function<const char *(int)> matname_fn) const;
+  /**
+   * Write the name of the deform group of a polygon.
+   */
   int16_t write_vertex_group(const OBJMesh &obj_mesh_data,
                              const int poly_index,
                              const int16_t last_poly_vertex_group) const;
+  /**
+   * Write polygon elements with at least vertex indices, and conditionally with UV vertex
+   * indices and polygon normal indices. Also write groups: smooth, vertex, material.
+   * The matname_fn turns a 0-indexed material slot number in an Object into the
+   * name used in the .obj file.
+   * \note UV indices were stored while writing UV vertices.
+   */
   void write_poly_elements(const OBJMesh &obj_mesh_data,
                            std::function<const char *(int)> matname_fn);
+  /**
+   * Write loose edges of a mesh as "l v1 v2".
+   */
   void write_edges_indices(const OBJMesh &obj_mesh_data) const;
+  /**
+   * Write a NURBS curve to the .OBJ file in parameter form.
+   */
   void write_nurbs_curve(const OBJCurve &obj_nurbs_data) const;
 
+  /**
+   * When there are multiple objects in a frame, the indices of previous objects' coordinates or
+   * normals add up.
+   */
   void update_index_offsets(const OBJMesh &obj_mesh_data);
 
  private:
   using func_vert_uv_normal_indices = void (OBJWriter::*)(Span<int> vert_indices,
                                                           Span<int> uv_indices,
                                                           Span<int> normal_indices) const;
+  /**
+   * \return Writer function with appropriate polygon-element syntax.
+   */
   func_vert_uv_normal_indices get_poly_element_writer(const int total_uv_vertices) const;
 
+  /**
+   * Write one line of polygon indices as "f v1/vt1/vn1 v2/vt2/vn2 ...".
+   */
   void write_vert_uv_normal_indices(Span<int> vert_indices,
                                     Span<int> uv_indices,
                                     Span<int> normal_indices) const;
+  /**
+   * Write one line of polygon indices as "f v1//vn1 v2//vn2 ...".
+   */
   void write_vert_normal_indices(Span<int> vert_indices,
                                  Span<int> /*uv_indices*/,
                                  Span<int> normal_indices) const;
+  /**
+   * Write one line of polygon indices as "f v1/vt1 v2/vt2 ...".
+   */
   void write_vert_uv_indices(Span<int> vert_indices,
                              Span<int> uv_indices,
                              Span<int> /*normal_indices*/) const;
+  /**
+   * Write one line of polygon indices as "f v1 v2 ...".
+   */
   void write_vert_indices(Span<int> vert_indices,
                           Span<int> /*uv_indices*/,
                           Span<int> /*normal_indices*/) const;
@@ -116,16 +178,38 @@ class MTLWriter : NonMovable, NonCopyable {
   Map<const Material *, int> material_map_;
 
  public:
+  /*
+   * Create the .MTL file.
+   */
   MTLWriter(const char *obj_filepath) noexcept(false);
 
   void write_header(const char *blen_filepath) const;
+  /**
+   * Write all of the material specifications to the MTL file.
+   * For consistency of output from run to run (useful for testing),
+   * the materials are sorted by name before writing.
+   */
   void write_materials();
   StringRefNull mtl_file_path() const;
+  /**
+   * Add the materials of the given object to #MTLWriter, de-duplicating
+   * against ones that are already there.
+   * Return a Vector of indices into mtlmaterials_ that hold the #MTLMaterial
+   * that corresponds to each material slot, in order, of the given Object.
+   * Indexes are returned rather than pointers to the MTLMaterials themselves
+   * because the mtlmaterials_ Vector may move around when resized.
+   */
   Vector<int> add_materials(const OBJMesh &mesh_to_export);
   const char *mtlmaterial_name(int index);
 
  private:
+  /**
+   * Write properties sourced from p-BSDF node or #Object.Material.
+   */
   void write_bsdf_properties(const MTLMaterial &mtl_material);
+  /**
+   * Write a texture map in the form "map_XX -s 1. 1. 1. -o 0. 0. 0. [-bm 1.] path/to/image".
+   */
   void write_texture_map(const MTLMaterial &mtl_material,
                          const Map<const eMTLSyntaxElement, tex_map_XX>::Item &texture_map);
 };
diff --git a/source/blender/io/wavefront_obj/exporter/obj_export_mesh.cc b/source/blender/io/wavefront_obj/exporter/obj_export_mesh.cc
index 0947d1132b0..efe17c7d1a2 100644
--- a/source/blender/io/wavefront_obj/exporter/obj_export_mesh.cc
+++ b/source/blender/io/wavefront_obj/exporter/obj_export_mesh.cc
@@ -39,10 +39,6 @@
 #include "obj_export_mesh.hh"
 
 namespace blender::io::obj {
-/**
- * Store evaluated Object and Mesh pointers. Conditionally triangulate a mesh, or
- * create a new Mesh from a Curve.
- */
 OBJMesh::OBJMesh(Depsgraph *depsgraph, const OBJExportParams &export_params, Object *mesh_object)
 {
   export_object_eval_ = DEG_get_evaluated_object(depsgraph, mesh_object);
@@ -75,9 +71,6 @@ OBJMesh::~OBJMesh()
   }
 }
 
-/**
- * Free the mesh if _the exporter_ created it.
- */
 void OBJMesh::free_mesh_if_needed()
 {
   if (mesh_eval_needs_free_ && export_mesh_eval_) {
@@ -85,12 +78,6 @@ void OBJMesh::free_mesh_if_needed()
   }
 }
 
-/**
- * Allocate a new Mesh with triangulated polygons.
- *
- * The returned mesh can be the same as the old one.
- * \return Owning pointer to the new Mesh, and whether a new Mesh was created.
- */
 std::pair<Mesh *, bool> OBJMesh::triangulate_mesh_eval()
 {
   if (export_mesh_eval_->totpoly <= 0) {
@@ -119,9 +106,6 @@ std::pair<Mesh *, bool> OBJMesh::triangulate_mesh_eval()
   return {triangulated, true};
 }
 
-/**
- * Set the final transform after applying axes settings and an Object's world transform.
- */
 void OBJMesh::set_world_axes_transform(const eTransformAxisForward forward,
                                        const eTransformAxisUp up)
 {
@@ -157,17 +141,11 @@ int OBJMesh::tot_edges() const
   return export_mesh_eval_->totedge;
 }
 
-/**
- * \return Total materials in the object.
- */
 int16_t OBJMesh::tot_materials() const
 {
   return export_mesh_eval_->totcol;
 }
 
-/**
- * \return Smooth group of the polygon at the given index.
- */
 int OBJMesh::ith_smooth_group(const int poly_index) const
 {
   /* Calculate smooth groups first: #OBJMesh::calc_smooth_groups. */
@@ -188,10 +166,6 @@ void OBJMesh::ensure_mesh_edges() const
   BKE_mesh_calc_edges_loose(export_mesh_eval_);
 }
 
-/**
- * Calculate smooth groups of a smooth-shaded object.
- * \return A polygon aligned array of smooth group numbers.
- */
 void OBJMesh::calc_smooth_groups(const bool use_bitflags)
 {
   poly_smooth_groups_ = BKE_mesh_calc_smoothgroups(export_mesh_eval_->medge,
@@ -204,9 +178,6 @@ void OBJMesh::calc_smooth_groups(const bool use_bitflags)
                                                    use_bitflags);
 }
 
-/**
- * Return mat_nr-th material of the object. The given index should be zero-based.
- */
 const Material *OBJMesh::get_object_material(const int16_t mat_nr) const
 {
   /* "+ 1" as material getter needs one-based indices.  */
@@ -224,10 +195,6 @@ bool OBJMesh::is_ith_poly_smooth(const int poly_index) const
   return export_mesh_eval_->mpoly[poly_index].flag & ME_SMOOTH;
 }
 
-/**
- * Returns a zero-based index of a polygon's material indexing into
- * the Object's material slots.
- */
 int16_t OBJMesh::ith_poly_matnr(const int poly_index) const
 {
   BLI_assert(poly_index < export_mesh_eval_->totpoly);
@@ -235,25 +202,16 @@ int16_t OBJMesh::ith_poly_matnr(const int poly_index) const
   return r_mat_nr >= 0 ? r_mat_nr : NOT_FOUND;
 }
 
-/**
- * Get object name as it appears in the outliner.
- */
 const char *OBJMesh::get_object_name() const
 {
   return export_object_eval_->id.name + 2;
 }
 
-/**
- * Get Object's Mesh's name.
- */
 const char *OBJMesh::get_object_mesh_name() const
 {
   return export_mesh_eval_->id.name + 2;
 }
 
-/**
- * Get object's material (at the given index) name. The given index should be zero-based.
- */
 const char *OBJMesh::get_object_material_name(const int16_t mat_nr) const
 {
   const Material *mat = get_object_material(mat_nr);
@@ -263,9 +221,6 @@ const char *OBJMesh::get_object_material_name(const int16_t mat_nr) const
   return mat->id.name + 2;
 }
 
-/**
- * Calculate coordinates of the vertex at the given index.
- */
 float3 OBJMesh::calc_vertex_coords(const int vert_index, const float scaling_factor) const
 {
   float3 r_coords;
@@ -275,9 +230,6 @@ float3 OBJMesh::calc_vertex_coords(const int vert_index, const float scaling_fac
   return r_coords;
 }
 
-/**
- * Calculate vertex indices of all vertices of the polygon at the given index.
- */
 Vector<int> OBJMesh::calc_poly_vertex_indices(const int poly_index) const
 {
   const MPoly &mpoly = export_mesh_eval_->mpoly[poly_index];
@@ -290,11 +242,6 @@ Vector<int> OBJMesh::calc_poly_vertex_indices(const int poly_index) const
   return r_poly_vertex_indices;
 }
 
-/**
- * Calculate UV vertex coordinates of an Object.
- *
- * \note Also store the UV vertex indices in the member variable.
- */
 void OBJMesh::store_uv_coords_and_indices(Vector<std::array<float, 2>> &r_uv_coords)
 {
   const MPoly *mpoly = export_mesh_eval_->mpoly;
@@ -351,11 +298,6 @@ Span<int> OBJMesh::calc_poly_uv_indices(const int poly_index) const
   BLI_assert(poly_index < uv_indices_.size());
   return uv_indices_[poly_index];
 }
-/**
- * Calculate polygon normal of a polygon at given index.
- *
- * Should be used for flat-shaded polygons.
- */
 float3 OBJMesh::calc_poly_normal(const int poly_index) const
 {
   float3 r_poly_normal;
@@ -367,11 +309,6 @@ float3 OBJMesh::calc_poly_normal(const int poly_index) const
   return r_poly_normal;
 }
 
-/**
- * Calculate loop normals of a polygon at the given index.
- *
- * Should be used for smooth-shaded polygons.
- */
 void OBJMesh::calc_loop_normals(const int poly_index, Vector<float3> &r_loop_normals) const
 {
   r_loop_normals.clear();
@@ -386,11 +323,6 @@ void OBJMesh::calc_loop_normals(const int poly_index, Vector<float3> &r_loop_nor
   }
 }
 
-/**
- * Calculate a polygon's polygon/loop normal indices.
- * \param object_tot_prev_normals Number of normals of this Object written so far.
- * \return Number of distinct normal indices.
- */
 std::pair<int, Vector<int>> OBJMesh::calc_poly_normal_indices(
     const int poly_index, const int object_tot_prev_normals) const
 {
@@ -414,13 +346,6 @@ std::pair<int, Vector<int>> OBJMesh::calc_poly_normal_indices(
   return {1, r_poly_normal_indices};
 }
 
-/**
- * Find the index of the vertex group with the maximum number of vertices in a polygon.
- * The index indices into the #Object.defbase.
- *
- * If two or more groups have the same number of vertices (maximum), group name depends on the
- * implementation of #std::max_element.
- */
 int16_t OBJMesh::get_poly_deform_group_index(const int poly_index) const
 {
   BLI_assert(poly_index < export_mesh_eval_->totpoly);
@@ -464,10 +389,6 @@ int16_t OBJMesh::get_poly_deform_group_index(const int poly_index) const
   return max_idx;
 }
 
-/**
- * Find the name of the vertex deform group at the given index.
- * The index indices into the #Object.defbase.
- */
 const char *OBJMesh::get_poly_deform_group_name(const int16_t def_group_index) const
 {
   const bDeformGroup &vertex_group = *(static_cast<bDeformGroup *>(
@@ -475,9 +396,6 @@ const char *OBJMesh::get_poly_deform_group_name(const int16_t def_group_index) c
   return vertex_group.name;
 }
 
-/**
- * Calculate vertex indices of an edge's corners if it is a loose edge.
- */
 std::optional<std::array<int, 2>> OBJMesh::calc_loose_edge_vert_indices(const int edge_index) const
 {
   const MEdge &edge = export_mesh_eval_->medge[edge_index];
diff --git a/source/blender/io/wavefront_obj/exporter/obj_export_mesh.hh b/source/blender/io/wavefront_obj/exporter/obj_export_mesh.hh
index 92fea78732a..5d9c08a288e 100644
--- a/source/blender/io/wavefront_obj/exporter/obj_export_mesh.hh
+++ b/source/blender/io/wavefront_obj/exporter/obj_export_mesh.hh
@@ -87,6 +87,10 @@ class OBJMesh : NonCopyable {
   int *poly_smooth_groups_ = nullptr;
 
  public:
+  /**
+   * Store evaluated Object and Mesh pointers. Conditionally triangulate a mesh, or
+   * create a new Mesh from a Curve.
+   */
   OBJMesh(Depsgraph *depsgraph, const OBJExportParams &export_params, Object *mesh_object);
   ~OBJMesh();
 
@@ -95,37 +99,115 @@ class OBJMesh : NonCopyable {
   int tot_uv_vertices() const;
   int tot_edges() const;
 
+  /**
+   * \return Total materials in the object.
+   */
   int16_t tot_materials() const;
+  /**
+   * Return mat_nr-th material of the object. The given index should be zero-based.
+   */
   const Material *get_object_material(const int16_t mat_nr) const;
+  /**
+   * Returns a zero-based index of a polygon's material indexing into
+   * the Object's material slots.
+   */
   int16_t ith_poly_matnr(const int poly_index) const;
 
   void ensure_mesh_normals() const;
   void ensure_mesh_edges() const;
 
+  /**
+   * Calculate smooth groups of a smooth-shaded object.
+   * \return A polygon aligned array of smooth group numbers.
+   */
   void calc_smooth_groups(const bool use_bitflags);
+  /**
+   * \return Smooth group of the polygon at the given index.
+   */
   int ith_smooth_group(const int poly_index) const;
   bool is_ith_poly_smooth(const int poly_index) const;
 
+  /**
+   * Get object name as it appears in the outliner.
+   */
   const char *get_object_name() const;
+  /**
+   * Get Object's Mesh's name.
+   */
   const char *get_object_mesh_name() const;
+  /**
+   * Get object's material (at the given index) name. The given index should be zero-based.
+   */
   const char *get_object_material_name(const int16_t mat_nr) const;
 
+  /**
+   * Calculate coordinates of the vertex at the given index.
+   */
   float3 calc_vertex_coords(const int vert_index, const float scaling_factor) const;
+  /**
+   * Calculate vertex indices of all vertices of the polygon at the given index.
+   */
   Vector<int> calc_poly_vertex_indices(const int poly_index) const;
+  /**
+   * Calculate UV vertex coordinates of an Object.
+   *
+   * \note Also store the UV vertex indices in the member variable.
+   */
   void store_uv_coords_and_indices(Vector<std::array<float, 2>> &r_uv_coords);
   Span<int> calc_poly_uv_indices(const int poly_index) const;
+  /**
+   * Calculate polygon normal of a polygon at given index.
+   *
+   * Should be used for flat-shaded polygons.
+   */
   float3 calc_poly_normal(const int poly_index) const;
+  /**
+   * Calculate a polygon's polygon/loop normal indices.
+   * \param object_tot_prev_normals Number of normals of this Object written so far.
+   * \return Number of distinct normal indices.
+   */
   std::pair<int, Vector<int>> calc_poly_normal_indices(const int poly_index,
                                                        const int object_tot_prev_normals) const;
+  /**
+   * Calculate loop normals of a polygon at the given index.
+   *
+   * Should be used for smooth-shaded polygons.
+   */
   void calc_loop_normals(const int poly_index, Vector<float3> &r_loop_normals) const;
+  /**
+   * Find the index of the vertex group with the maximum number of vertices in a polygon.
+   * The index indices into the #Object.defbase.
+   *
+   * If two or more groups have the same number of vertices (maximum), group name depends on the
+   * implementation of #std::max_element.
+   */
   int16_t get_poly_deform_group_index(const int poly_index) const;
+  /**
+   * Find the name of the vertex deform group at the given index.
+   * The index indices into the #Object.defbase.
+   */
   const char *get_poly_deform_group_name(const int16_t def_group_index) const;
 
+  /**
+   * Calculate vertex indices of an edge's corners if it is a loose edge.
+   */
   std::optional<std::array<int, 2>> calc_loose_edge_vert_indices(const int edge_index) const;
 
  private:
+  /**
+   * Free the mesh if _the exporter_ created it.
+   */
   void free_mesh_if_needed();
+  /**
+   * Allocate a new Mesh with triangulated polygons.
+   *
+   * The returned mesh can be the same as the old one.
+   * \return Owning pointer to the new Mesh, and whether a new Mesh was created.
+   */
   std::pair<Mesh *, bool> triangulate_mesh_eval();
+  /**
+   * Set the final transform after applying axes settings and an Object's world transform.
+   */
   void set_world_axes_transform(const eTransformAxisForward forward, const eTransformAxisUp up);
 };
 }  // namespace blender::io::obj
diff --git a/source/blender/io/wavefront_obj/exporter/obj_export_nurbs.cc b/source/blender/io/wavefront_obj/exporter/obj_export_nurbs.cc
index 4138ad2f697..91aabd8fa76 100644
--- a/source/blender/io/wavefront_obj/exporter/obj_export_nurbs.cc
+++ b/source/blender/io/wavefront_obj/exporter/obj_export_nurbs.cc
@@ -39,9 +39,6 @@ OBJCurve::OBJCurve(const Depsgraph *depsgraph,
   set_world_axes_transform(export_params.forward_axis, export_params.up_axis);
 }
 
-/**
- * Set the final transform after applying axes settings and an Object's world transform.
- */
 void OBJCurve::set_world_axes_transform(const eTransformAxisForward forward,
                                         const eTransformAxisUp up)
 {
@@ -67,19 +64,12 @@ int OBJCurve::total_splines() const
   return BLI_listbase_count(&export_curve_->nurb);
 }
 
-/**
- * \param spline_index: Zero-based index of spline of interest.
- * \return: Total vertices in a spline.
- */
 int OBJCurve::total_spline_vertices(const int spline_index) const
 {
   const Nurb *const nurb = static_cast<Nurb *>(BLI_findlink(&export_curve_->nurb, spline_index));
   return nurb->pntsu * nurb->pntsv;
 }
 
-/**
- * Get coordinates of the vertex at the given index on the given spline.
- */
 float3 OBJCurve::vertex_coordinates(const int spline_index,
                                     const int vertex_index,
                                     const float scaling_factor) const
@@ -93,10 +83,6 @@ float3 OBJCurve::vertex_coordinates(const int spline_index,
   return r_coord;
 }
 
-/**
- * Get total control points of the NURBS spline at the given index. This is different than total
- * vertices of a spline.
- */
 int OBJCurve::total_spline_control_points(const int spline_index) const
 {
   const Nurb *const nurb = static_cast<Nurb *>(BLI_findlink(&export_curve_->nurb, spline_index));
@@ -110,9 +96,6 @@ int OBJCurve::total_spline_control_points(const int spline_index) const
   return r_tot_control_points;
 }
 
-/**
- * Get the degree of the NURBS spline at the given index.
- */
 int OBJCurve::get_nurbs_degree(const int spline_index) const
 {
   const Nurb *const nurb = static_cast<Nurb *>(BLI_findlink(&export_curve_->nurb, spline_index));
diff --git a/source/blender/io/wavefront_obj/exporter/obj_export_nurbs.hh b/source/blender/io/wavefront_obj/exporter/obj_export_nurbs.hh
index 463e41befb5..fe457f3c1c7 100644
--- a/source/blender/io/wavefront_obj/exporter/obj_export_nurbs.hh
+++ b/source/blender/io/wavefront_obj/exporter/obj_export_nurbs.hh
@@ -43,14 +43,31 @@ class OBJCurve : NonCopyable {
 
   const char *get_curve_name() const;
   int total_splines() const;
+  /**
+   * \param spline_index: Zero-based index of spline of interest.
+   * \return: Total vertices in a spline.
+   */
   int total_spline_vertices(const int spline_index) const;
+  /**
+   * Get coordinates of the vertex at the given index on the given spline.
+   */
   float3 vertex_coordinates(const int spline_index,
                             const int vertex_index,
                             const float scaling_factor) const;
+  /**
+   * Get total control points of the NURBS spline at the given index. This is different than total
+   * vertices of a spline.
+   */
   int total_spline_control_points(const int spline_index) const;
+  /**
+   * Get the degree of the NURBS spline at the given index.
+   */
   int get_nurbs_degree(const int spline_index) const;
 
  private:
+  /**
+   * Set the final transform after applying axes settings and an Object's world transform.
+   */
   void set_world_axes_transform(const eTransformAxisForward forward, const eTransformAxisUp up);
 };
 
diff --git a/source/blender/io/wavefront_obj/exporter/obj_exporter.cc b/source/blender/io/wavefront_obj/exporter/obj_exporter.cc
index d15d053adc9..595e6aaf4f2 100644
--- a/source/blender/io/wavefront_obj/exporter/obj_exporter.cc
+++ b/source/blender/io/wavefront_obj/exporter/obj_exporter.cc
@@ -207,11 +207,6 @@ static void write_nurbs_curve_objects(const Vector<std::unique_ptr<OBJCurve>> &e
   }
 }
 
-/**
- * Export a single frame to a .OBJ file.
- *
- * Conditionally write a .MTL file also.
- */
 void export_frame(Depsgraph *depsgraph, const OBJExportParams &export_params, const char *filepath)
 {
   std::unique_ptr<OBJWriter> frame_writer = nullptr;
@@ -250,11 +245,6 @@ void export_frame(Depsgraph *depsgraph, const OBJExportParams &export_params, co
   write_nurbs_curve_objects(std::move(exportable_as_nurbs), *frame_writer);
 }
 
-/**
- * Append the current frame number in the .OBJ file name.
- *
- * \return Whether the filepath is in #FILE_MAX limits.
- */
 bool append_frame_to_filename(const char *filepath, const int frame, char *r_filepath_with_frames)
 {
   BLI_strncpy(r_filepath_with_frames, filepath, FILE_MAX);
@@ -264,9 +254,6 @@ bool append_frame_to_filename(const char *filepath, const int frame, char *r_fil
   return BLI_path_extension_replace(r_filepath_with_frames, FILE_MAX, ".obj");
 }
 
-/**
- * Central internal function to call Scene update & writer functions.
- */
 void exporter_main(bContext *C, const OBJExportParams &export_params)
 {
   ED_object_mode_set(C, OB_MODE_OBJECT);
diff --git a/source/blender/io/wavefront_obj/exporter/obj_exporter.hh b/source/blender/io/wavefront_obj/exporter/obj_exporter.hh
index e02a240b51a..1a193bf437f 100644
--- a/source/blender/io/wavefront_obj/exporter/obj_exporter.hh
+++ b/source/blender/io/wavefront_obj/exporter/obj_exporter.hh
@@ -51,6 +51,9 @@ class OBJDepsgraph : NonMovable, NonCopyable {
  * Depending on whether or not `export_params.export_animation` is set, it writes
  * either one file per animation frame, or just one file.
  */
+/**
+ * Central internal function to call Scene update & writer functions.
+ */
 void exporter_main(bContext *C, const OBJExportParams &export_params);
 
 class OBJMesh;
@@ -62,6 +65,11 @@ class OBJCurve;
  * The output file name is given by `filepath`.
  * This function is normally called from `exporter_main`, but is exposed here for testing purposes.
  */
+/**
+ * Export a single frame to a .OBJ file.
+ *
+ * Conditionally write a .MTL file also.
+ */
 void export_frame(Depsgraph *depsgraph,
                   const OBJExportParams &export_params,
                   const char *filepath);
@@ -84,5 +92,10 @@ filter_supported_objects(Depsgraph *depsgraph, const OBJExportParams &export_par
  * be `filepath` with its "#" characters replaced by the number representing `frame`, and with
  * a .obj extension.
  */
+/**
+ * Append the current frame number in the .OBJ file name.
+ *
+ * \return Whether the filepath is in #FILE_MAX limits.
+ */
 bool append_frame_to_filename(const char *filepath, const int frame, char *r_filepath_with_frames);
 }  // namespace blender::io::obj