Cleanup: move doc-strings into headers

- The comment for create_normals was moved into an inline note
  as it's not related to the public API.
- Use a colon after parameters.

Ref T92709

source/blender/io/wavefront_obj/IO_wavefront_obj.cc

@@ -11,18 +11,12 @@
 #include "obj_exporter.hh"
 #include "obj_importer.hh"
 
-/**
- * C-interface for the exporter.
- */
 void OBJ_export(bContext *C, const OBJExportParams *export_params)
 {
   SCOPED_TIMER("OBJ export");
   blender::io::obj::exporter_main(C, *export_params);
 }
 
-/**
- * Time the full import process.
- */
 void OBJ_import(bContext *C, const OBJImportParams *import_params)
 {
   SCOPED_TIMER(__func__);

source/blender/io/wavefront_obj/IO_wavefront_obj.h

@@ -86,8 +86,14 @@ struct OBJImportParams {
   eTransformAxisUp up_axis;
 };
 
+/**
+ * Time the full import process.
+ */
 void OBJ_import(bContext *C, const struct OBJImportParams *import_params);
 
+/**
+ * C-interface for the exporter.
+ */
 void OBJ_export(bContext *C, const struct OBJExportParams *export_params);
 
 #ifdef __cplusplus

source/blender/io/wavefront_obj/importer/importer_mesh_utils.hh

@@ -19,10 +19,12 @@ namespace blender::io::obj {
  * Given an invalid polygon (with holes or duplicated vertex indices),
  * turn it into possibly multiple polygons that are valid.
  *
- * \param vertex_coords Polygon's vertex coordinate list.
- * \param face_vertex_indices A polygon's indices that index into the given vertex coordinate list.
- * \return List of polygons with each element containing indices of one polygon.
- *    The indices are into face_vertex_indices array.
+ * \param vertex_coords: Polygon's vertex coordinate list.
+ * \param face_vertex_indices: A polygon's indices that index into the given vertex coordinate
+ * list.
+ *
+ * \return List of polygons with each element containing indices of one polygon. The indices
+ * are into face_vertex_indices array.
  */
 Vector<Vector<int>> fixup_invalid_polygon(Span<float3> vertex_coords,
                                           Span<int> face_vertex_indices);

source/blender/io/wavefront_obj/importer/obj_import_file_reader.cc

@@ -318,9 +318,6 @@ static void geom_update_smooth_group(const StringRef rest_line, bool &r_state_sh
   }
 }
 
-/**
- * Open OBJ file at the path given in import parameters.
- */
 OBJParser::OBJParser(const OBJImportParams &import_params) : import_params_(import_params)
 {
   obj_file_.open(import_params_.filepath);
@@ -330,10 +327,6 @@ OBJParser::OBJParser(const OBJImportParams &import_params) : import_params_(impo
   }
 }
 
-/**
- * Read the OBJ file line by line and create OBJ Geometry instances. Also store all the vertex
- * and UV vertex coordinates in a struct accessible by all objects.
- */
 void OBJParser::parse(Vector<std::unique_ptr<Geometry>> &r_all_geometries,
                       GlobalVertices &r_global_vertices)
 {
@@ -499,17 +492,11 @@ static string fix_bad_map_keys(StringRef map_key)
   return new_map_key;
 }
 
-/**
- * Return a list of all material library filepaths referenced by the OBJ file.
- */
 Span<std::string> OBJParser::mtl_libraries() const
 {
   return mtl_libraries_;
 }
 
-/**
- * Open material library file.
- */
 MTLParser::MTLParser(StringRef mtl_library, StringRefNull obj_filepath)
 {
   char obj_file_dir[FILE_MAXDIR];
@@ -523,9 +510,6 @@ MTLParser::MTLParser(StringRef mtl_library, StringRefNull obj_filepath)
   }
 }
 
-/**
- * Read MTL file(s) and add MTLMaterial instances to the given Map reference.
- */
 void MTLParser::parse_and_store(Map<string, std::unique_ptr<MTLMaterial>> &r_mtl_materials)
 {
   if (!mtl_file_.good()) {

source/blender/io/wavefront_obj/importer/obj_import_file_reader.hh

@@ -22,10 +22,20 @@ class OBJParser {
   Vector<std::string> mtl_libraries_;
 
  public:
+  /**
+   * Open OBJ file at the path given in import parameters.
+   */
   OBJParser(const OBJImportParams &import_params);
 
+  /**
+   * Read the OBJ file line by line and create OBJ Geometry instances. Also store all the vertex
+   * and UV vertex coordinates in a struct accessible by all objects.
+   */
   void parse(Vector<std::unique_ptr<Geometry>> &r_all_geometries,
              GlobalVertices &r_global_vertices);
+  /**
+   * Return a list of all material library filepaths referenced by the OBJ file.
+   */
   Span<std::string> mtl_libraries() const;
 };
 
@@ -144,8 +154,14 @@ class MTLParser {
   blender::fstream mtl_file_;
 
  public:
+  /**
+   * Open material library file.
+   */
   MTLParser(StringRef mtl_library_, StringRefNull obj_filepath);
 
+  /**
+   * Read MTL file(s) and add MTLMaterial instances to the given Map reference.
+   */
   void parse_and_store(Map<std::string, std::unique_ptr<MTLMaterial>> &r_mtl_materials);
 };
 }  // namespace blender::io::obj

source/blender/io/wavefront_obj/importer/obj_import_mesh.cc

@@ -68,11 +68,6 @@ Object *MeshFromGeometry::create_mesh(
   return obj;
 }
 
-/**
- * OBJ files coming from the wild might have faces that are invalid in Blender
- * (mostly with duplicate vertex indices, used by some software to indicate
- * polygons with holes). This method tries to fix them up.
- */
 void MeshFromGeometry::fixup_invalid_faces()
 {
   for (int64_t face_idx = 0; face_idx < mesh_geometry_.face_elements_.size(); ++face_idx) {
@@ -158,13 +153,6 @@ void MeshFromGeometry::create_vertices(Mesh *mesh)
   }
 }
 
-/**
- * Create polygons for the Mesh, set smooth shading flag, deform group name, assigned material
- * also.
- *
- * It must receive all polygons to be added to the mesh. Remove holes from polygons before
- * calling this.
- */
 void MeshFromGeometry::create_polys_loops(Object *obj, Mesh *mesh)
 {
   /* Will not be used if vertex groups are not imported. */
@@ -245,9 +233,6 @@ void MeshFromGeometry::create_polys_loops(Object *obj, Mesh *mesh)
   }
 }
 
-/**
- * Add explicitly imported OBJ edges to the mesh.
- */
 void MeshFromGeometry::create_edges(Mesh *mesh)
 {
   const int64_t tot_edges{mesh_geometry_.edges_.size()};
@@ -268,9 +253,6 @@ void MeshFromGeometry::create_edges(Mesh *mesh)
   BKE_mesh_calc_edges_loose(mesh);
 }
 
-/**
- * Add UV layer and vertices to the Mesh.
- */
 void MeshFromGeometry::create_uv_verts(Mesh *mesh)
 {
   if (global_vertices_.uv_vertices.size() <= 0) {
@@ -329,9 +311,6 @@ static Material *get_or_create_material(
   return mat;
 }
 
-/**
- * Add materials and the nodetree to the Mesh Object.
- */
 void MeshFromGeometry::create_materials(
     Main *bmain,
     const Map<std::string, std::unique_ptr<MTLMaterial>> &materials,
@@ -348,11 +327,10 @@ void MeshFromGeometry::create_materials(
   }
 }
 
-/**
- * Needs more clarity about what is expected in the viewport if the function works.
- */
 void MeshFromGeometry::create_normals(Mesh *mesh)
 {
+  /* NOTE: Needs more clarity about what is expected in the viewport if the function works. */
+
   /* No normal data: nothing to do. */
   if (global_vertices_.vertex_normals.is_empty() || !mesh_geometry_.has_vertex_normals_) {
     return;

source/blender/io/wavefront_obj/importer/obj_import_mesh.hh

@@ -37,11 +37,32 @@ class MeshFromGeometry : NonMovable, NonCopyable {
                       const OBJImportParams &import_params);
 
  private:
+  /**
+   * OBJ files coming from the wild might have faces that are invalid in Blender
+   * (mostly with duplicate vertex indices, used by some software to indicate
+   * polygons with holes). This method tries to fix them up.
+   */
   void fixup_invalid_faces();
   void create_vertices(Mesh *mesh);
+  /**
+   * Create polygons for the Mesh, set smooth shading flag, deform group name,
+   * assigned material also.
+   *
+   * It must receive all polygons to be added to the mesh.
+   * Remove holes from polygons before * calling this.
+   */
   void create_polys_loops(Object *obj, Mesh *mesh);
+  /**
+   * Add explicitly imported OBJ edges to the mesh.
+   */
   void create_edges(Mesh *mesh);
+  /**
+   * Add UV layer and vertices to the Mesh.
+   */
   void create_uv_verts(Mesh *mesh);
+  /**
+   * Add materials and the nodetree to the Mesh Object.
+   */
   void create_materials(Main *bmain,
                         const Map<std::string, std::unique_ptr<MTLMaterial>> &materials,
                         Map<std::string, Material *> &created_materials,

source/blender/io/wavefront_obj/importer/obj_import_mtl.cc

@@ -111,10 +111,6 @@ static bool load_texture_image(Main *bmain, const tex_map_XX &tex_map, bNode *r_
   return false;
 }
 
-/**
- * Initializes a nodetree with a p-BSDF node's BSDF socket connected to shader output node's
- * surface socket.
- */
 ShaderNodetreeWrap::ShaderNodetreeWrap(Main *bmain, const MTLMaterial &mtl_mat, Material *mat)
     : mtl_mat_(mtl_mat)
 {
@@ -141,10 +137,6 @@ ShaderNodetreeWrap::~ShaderNodetreeWrap()
   }
 }
 
-/**
- * Release nodetree for materials to own it. nodetree has its unique deleter
- * if destructor is not reached for some reason.
- */
 bNodeTree *ShaderNodetreeWrap::get_nodetree()
 {
   /* If this function has been reached, we know that nodes and the nodetree
@@ -152,19 +144,11 @@ bNodeTree *ShaderNodetreeWrap::get_nodetree()
   return nodetree_.release();
 }
 
-/**
- * Add a new static node to the tree.
- * No two nodes are linked here.
- */
 bNode *ShaderNodetreeWrap::add_node_to_tree(const int node_type)
 {
   return nodeAddStaticNode(nullptr, nodetree_.get(), node_type);
 }
 
-/**
- * Return x-y coordinates for a node where y is determined by other nodes present in
- * the same vertical column.
- */
 std::pair<float, float> ShaderNodetreeWrap::set_node_locations(const int pos_x)
 {
   int pos_y = 0;
@@ -186,11 +170,6 @@ std::pair<float, float> ShaderNodetreeWrap::set_node_locations(const int pos_x)
   }
 }
 
-/**
- * Link two nodes by the sockets of given IDs.
- * Also releases the ownership of the "from" node for nodetree to free it.
- * \param from_node_pos_x 0 to 4 value as per nodetree arrangement.
- */
 void ShaderNodetreeWrap::link_sockets(bNode *from_node,
                                       StringRef from_node_id,
                                       bNode *to_node,
@@ -205,9 +184,6 @@ void ShaderNodetreeWrap::link_sockets(bNode *from_node,
   nodeAddLink(nodetree_.get(), from_node, from_sock, to_node, to_sock);
 }
 
-/**
- * Set values of sockets in p-BSDF node of the nodetree.
- */
 void ShaderNodetreeWrap::set_bsdf_socket_values()
 {
   const int illum = mtl_mat_.illum;
@@ -331,10 +307,6 @@ void ShaderNodetreeWrap::set_bsdf_socket_values()
   set_property_of_socket(SOCK_FLOAT, "Alpha", {alpha}, bsdf_);
 }
 
-/**
- * Create image texture, vector and normal mapping nodes from MTL materials and link the
- * nodes to p-BSDF node.
- */
 void ShaderNodetreeWrap::add_image_textures(Main *bmain, Material *mat)
 {
   for (const Map<const eMTLSyntaxElement, tex_map_XX>::Item texture_map :

source/blender/io/wavefront_obj/importer/obj_import_mtl.hh

@@ -45,20 +45,48 @@ class ShaderNodetreeWrap {
   const float node_size_{300.f};
 
  public:
+  /**
+   * Initializes a nodetree with a p-BSDF node's BSDF socket connected to shader output node's
+   * surface socket.
+   */
   ShaderNodetreeWrap(Main *bmain, const MTLMaterial &mtl_mat, Material *mat);
   ~ShaderNodetreeWrap();
 
+  /**
+   * Release nodetree for materials to own it. nodetree has its unique deleter
+   * if destructor is not reached for some reason.
+   */
   bNodeTree *get_nodetree();
 
  private:
+  /**
+   * Add a new static node to the tree.
+   * No two nodes are linked here.
+   */
   bNode *add_node_to_tree(const int node_type);
+  /**
+   * Return x-y coordinates for a node where y is determined by other nodes present in
+   * the same vertical column.
+   */
   std::pair<float, float> set_node_locations(const int pos_x);
+  /**
+   * Link two nodes by the sockets of given IDs.
+   * Also releases the ownership of the "from" node for nodetree to free it.
+   * \param from_node_pos_x: 0 to 4 value as per nodetree arrangement.
+   */
   void link_sockets(bNode *from_node,
                     StringRef from_node_id,
                     bNode *to_node,
                     StringRef to_node_id,
                     const int from_node_pos_x);
+  /**
+   * Set values of sockets in p-BSDF node of the nodetree.
+   */
   void set_bsdf_socket_values();
+  /**
+   * Create image texture, vector and normal mapping nodes from MTL materials and link the
+   * nodes to p-BSDF node.
+   */
   void add_image_textures(Main *bmain, Material *mat);
 };
 

source/blender/io/wavefront_obj/importer/obj_import_nurbs.cc

@@ -45,9 +45,6 @@ Object *CurveFromGeometry::create_curve(Main *bmain, const OBJImportParams &impo
   return obj;
 }
 
-/**
- * Create a NURBS spline for the Curve converted from Geometry.
- */
 void CurveFromGeometry::create_nurbs(Curve *curve)
 {
   const NurbsElement &nurbs_geometry = curve_geometry_.nurbs_element_;

source/blender/io/wavefront_obj/importer/obj_import_nurbs.hh

@@ -33,6 +33,9 @@ class CurveFromGeometry : NonMovable, NonCopyable {
   Object *create_curve(Main *bmain, const OBJImportParams &import_params);
 
  private:
+  /**
+   * Create a NURBS spline for the Curve converted from Geometry.
+   */
   void create_nurbs(Curve *curve);
 };
 }  // namespace blender::io::obj

source/blender/io/wavefront_obj/importer/parser_string_utils.cc

@@ -17,10 +17,6 @@
 namespace blender::io::obj {
 using std::string;
 
-/**
- * Store multiple lines separated by an escaped newline character: `\\n`.
- * Use this before doing any parse operations on the read string.
- */
 void read_next_line(std::fstream &file, string &r_line)
 {
   std::string new_line;
@@ -36,11 +32,6 @@ void read_next_line(std::fstream &file, string &r_line)
   }
 }
 
-/**
- * Split a line string into the first word (key) and the rest of the line.
- * Also remove leading & trailing spaces as well as `\r` carriage return
- * character if present.
- */
 void split_line_key_rest(const StringRef line, StringRef &r_line_key, StringRef &r_rest_line)
 {
   if (line.is_empty()) {
@@ -83,11 +74,6 @@ void split_line_key_rest(const StringRef line, StringRef &r_line_key, StringRef
   }
 }
 
-/**
- * Split the given string by the delimiter and fill the given vector.
- * If an intermediate string is empty, or space or null character, it is not appended to the
- * vector.
- */
 void split_by_char(StringRef in_string, const char delimiter, Vector<StringRef> &r_out_list)
 {
   r_out_list.clear();
@@ -114,11 +100,6 @@ void split_by_char(StringRef in_string, const char delimiter, Vector<StringRef>
   }
 }
 
-/**
- * Convert the given string to float and assign it to the destination value.
- *
- * If the string cannot be converted to a float, the fallback value is used.
- */
 void copy_string_to_float(StringRef src, const float fallback_value, float &r_dst)
 {
   try {
@@ -135,12 +116,6 @@ void copy_string_to_float(StringRef src, const float fallback_value, float &r_ds
   }
 }
 
-/**
- * Convert all members of the Span of strings to floats and assign them to the float
- * array members. Usually used for values like coordinates.
- *
- * If a string cannot be converted to a float, the fallback value is used.
- */
 void copy_string_to_float(Span<StringRef> src,
                           const float fallback_value,
                           MutableSpan<float> r_dst)
@@ -155,11 +130,6 @@ void copy_string_to_float(Span<StringRef> src,
   }
 }
 
-/**
- * Convert the given string to int and assign it to the destination value.
- *
- * If the string cannot be converted to an integer, the fallback value is used.
- */
 void copy_string_to_int(StringRef src, const int fallback_value, int &r_dst)
 {
   try {
@@ -176,11 +146,6 @@ void copy_string_to_int(StringRef src, const int fallback_value, int &r_dst)
   }
 }
 
-/**
- * Convert the given strings to ints and fill the destination int buffer.
- *
- * If a string cannot be converted to an integer, the fallback value is used.
- */
 void copy_string_to_int(Span<StringRef> src, const int fallback_value, MutableSpan<int> r_dst)
 {
   for (int i = 0; i < r_dst.size(); ++i) {

source/blender/io/wavefront_obj/importer/parser_string_utils.hh

@@ -5,14 +5,49 @@ namespace blender::io::obj {
 /* Note: these OBJ parser helper functions are planned to get fairly large
  * changes "soon", so don't read too much into current implementation... */
 
+/**
+ * Store multiple lines separated by an escaped newline character: `\\n`.
+ * Use this before doing any parse operations on the read string.
+ */
 void read_next_line(std::fstream &file, std::string &r_line);
+/**
+ * Split a line string into the first word (key) and the rest of the line.
+ * Also remove leading & trailing spaces as well as `\r` carriage return
+ * character if present.
+ */
 void split_line_key_rest(StringRef line, StringRef &r_line_key, StringRef &r_rest_line);
+/**
+ * Split the given string by the delimiter and fill the given vector.
+ * If an intermediate string is empty, or space or null character, it is not appended to the
+ * vector.
+ */
 void split_by_char(StringRef in_string, const char delimiter, Vector<StringRef> &r_out_list);
+/**
+ * Convert the given string to float and assign it to the destination value.
+ *
+ * If the string cannot be converted to a float, the fallback value is used.
+ */
 void copy_string_to_float(StringRef src, const float fallback_value, float &r_dst);
+/**
+ * Convert all members of the Span of strings to floats and assign them to the float
+ * array members. Usually used for values like coordinates.
+ *
+ * If a string cannot be converted to a float, the fallback value is used.
+ */
 void copy_string_to_float(Span<StringRef> src,
                           const float fallback_value,
                           MutableSpan<float> r_dst);
+/**
+ * Convert the given string to int and assign it to the destination value.
+ *
+ * If the string cannot be converted to an integer, the fallback value is used.
+ */
 void copy_string_to_int(StringRef src, const int fallback_value, int &r_dst);
+/**
+ * Convert the given strings to ints and fill the destination int buffer.
+ *
+ * If a string cannot be converted to an integer, the fallback value is used.
+ */
 void copy_string_to_int(Span<StringRef> src, const int fallback_value, MutableSpan<int> r_dst);
 std::string replace_all_occurences(StringRef original, StringRef to_remove, StringRef to_add);