Cleanup: move public doc-strings into headers for 'io/alembic'

Ref T92709

12 files changed, 43 insertions, 31 deletions

diff --git a/source/blender/io/alembic/exporter/abc_subdiv_disabler.cc b/source/blender/io/alembic/exporter/abc_subdiv_disabler.cc
index 8073e157c13..bd12f3c10d3 100644
--- a/source/blender/io/alembic/exporter/abc_subdiv_disabler.cc
+++ b/source/blender/io/alembic/exporter/abc_subdiv_disabler.cc
@@ -72,8 +72,6 @@ void SubdivModifierDisabler::disable_modifiers()
   }
 }
 
-/* Check if the mesh is a subsurf, ignoring disabled modifiers and
- * displace if it's after subsurf. */
 ModifierData *SubdivModifierDisabler::get_subdiv_modifier(Scene *scene, Object *ob)
 {
   ModifierData *md = static_cast<ModifierData *>(ob->modifiers.last);
diff --git a/source/blender/io/alembic/exporter/abc_subdiv_disabler.h b/source/blender/io/alembic/exporter/abc_subdiv_disabler.h
index 3556df7ff31..c6541fd8afe 100644
--- a/source/blender/io/alembic/exporter/abc_subdiv_disabler.h
+++ b/source/blender/io/alembic/exporter/abc_subdiv_disabler.h
@@ -45,6 +45,10 @@ class SubdivModifierDisabler final {
 
   void disable_modifiers();
 
+  /**
+   * Check if the mesh is a subsurf, ignoring disabled modifiers and
+   * displace if it's after subsurf.
+   */
   static ModifierData *get_subdiv_modifier(Scene *scene, Object *ob);
 };
 
diff --git a/source/blender/io/alembic/intern/abc_axis_conversion.cc b/source/blender/io/alembic/intern/abc_axis_conversion.cc
index 23b24d2fd9a..78ea7166faf 100644
--- a/source/blender/io/alembic/intern/abc_axis_conversion.cc
+++ b/source/blender/io/alembic/intern/abc_axis_conversion.cc
@@ -75,8 +75,6 @@ void create_swapped_rotation_matrix(float rot_x_mat[3][3],
 }  // namespace
    // alembicvoidcreate_swapped_rotation_matrix(floatrot_x_mat[3][3],floatrot_y_mat[3][3],floatrot_z_mat[3][3],constfloateuler[3],AbcAxisSwapModemode)
 
-/* Convert matrix from Z=up to Y=up or vice versa.
- * Use yup_mat = zup_mat for in-place conversion. */
 void copy_m44_axis_swap(float dst_mat[4][4], float src_mat[4][4], AbcAxisSwapMode mode)
 {
   float dst_rot[3][3], src_rot[3][3], dst_scale_mat[4][4];
@@ -139,8 +137,6 @@ void copy_m44_axis_swap(float dst_mat[4][4], float src_mat[4][4], AbcAxisSwapMod
   mul_m4_m4m4(dst_mat, dst_mat, dst_scale_mat);
 }
 
-/* Recompute transform matrix of object in new coordinate system
- * (from Z-Up to Y-Up). */
 void create_transform_matrix(Object *obj,
                              float r_yup_mat[4][4],
                              AbcMatrixMode mode,
diff --git a/source/blender/io/alembic/intern/abc_axis_conversion.h b/source/blender/io/alembic/intern/abc_axis_conversion.h
index 30988222fb7..21b95ec717e 100644
--- a/source/blender/io/alembic/intern/abc_axis_conversion.h
+++ b/source/blender/io/alembic/intern/abc_axis_conversion.h
@@ -70,20 +70,27 @@ BLI_INLINE void copy_yup_from_zup(short yup[3], const short zup[3])
 }
 
 /* Names are given in (dst, src) order, just like
- * the parameters of copy_m44_axis_swap() */
+ * the parameters of copy_m44_axis_swap(). */
+
 typedef enum {
   ABC_ZUP_FROM_YUP = 1,
   ABC_YUP_FROM_ZUP = 2,
 } AbcAxisSwapMode;
 
-/* Create a rotation matrix for each axis from euler angles.
- * Euler angles are swapped to change coordinate system. */
+/**
+ * Create a rotation matrix for each axis from euler angles.
+ * Euler angles are swapped to change coordinate system.
+ */
 void create_swapped_rotation_matrix(float rot_x_mat[3][3],
                                     float rot_y_mat[3][3],
                                     float rot_z_mat[3][3],
                                     const float euler[3],
                                     AbcAxisSwapMode mode);
 
+/**
+ * Convert matrix from Z=up to Y=up or vice versa.
+ * Use yup_mat = zup_mat for in-place conversion.
+ */
 void copy_m44_axis_swap(float dst_mat[4][4], float src_mat[4][4], AbcAxisSwapMode mode);
 
 typedef enum {
@@ -91,6 +98,10 @@ typedef enum {
   ABC_MATRIX_LOCAL = 2,
 } AbcMatrixMode;
 
+/**
+ * Recompute transform matrix of object in new coordinate system
+ * (from Z-Up to Y-Up).
+ */
 void create_transform_matrix(Object *obj,
                              float r_yup_mat[4][4],
                              AbcMatrixMode mode,
diff --git a/source/blender/io/alembic/intern/abc_customdata.cc b/source/blender/io/alembic/intern/abc_customdata.cc
index 04add1c1360..830ec731e20 100644
--- a/source/blender/io/alembic/intern/abc_customdata.cc
+++ b/source/blender/io/alembic/intern/abc_customdata.cc
@@ -603,12 +603,6 @@ void read_custom_data(const std::string &iobject_full_name,
   }
 }
 
-/* UVs can be defined per-loop (one value per vertex per face), or per-vertex (one value per
- * vertex). The first case is the most common, as this is the standard way of storing this data
- * given that some vertices might be on UV seams and have multiple possible UV coordinates; the
- * second case can happen when the mesh is split according to the UV islands, in which case storing
- * a single UV value per vertex allows to deduplicate data and thus to reduce the file size since
- * vertices are guaranteed to only have a single UV coordinate. */
 AbcUvScope get_uv_scope(const Alembic::AbcGeom::GeometryScope scope,
                         const CDStreamConfig &config,
                         const Alembic::AbcGeom::UInt32ArraySamplePtr &indices)
diff --git a/source/blender/io/alembic/intern/abc_customdata.h b/source/blender/io/alembic/intern/abc_customdata.h
index 5eae6307474..97a9235753f 100644
--- a/source/blender/io/alembic/intern/abc_customdata.h
+++ b/source/blender/io/alembic/intern/abc_customdata.h
@@ -132,6 +132,14 @@ typedef enum {
   ABC_UV_SCOPE_VERTEX,
 } AbcUvScope;
 
+/**
+ * UVs can be defined per-loop (one value per vertex per face), or per-vertex (one value per
+ * vertex). The first case is the most common, as this is the standard way of storing this data
+ * given that some vertices might be on UV seams and have multiple possible UV coordinates; the
+ * second case can happen when the mesh is split according to the UV islands, in which case storing
+ * a single UV value per vertex allows to de-duplicate data and thus to reduce the file size since
+ * vertices are guaranteed to only have a single UV coordinate.
+ */
 AbcUvScope get_uv_scope(const Alembic::AbcGeom::GeometryScope scope,
                         const CDStreamConfig &config,
                         const Alembic::AbcGeom::UInt32ArraySamplePtr &indices);
diff --git a/source/blender/io/alembic/intern/abc_reader_curves.cc b/source/blender/io/alembic/intern/abc_reader_curves.cc
index d2ec7fb84db..bd1e57da648 100644
--- a/source/blender/io/alembic/intern/abc_reader_curves.cc
+++ b/source/blender/io/alembic/intern/abc_reader_curves.cc
@@ -274,12 +274,6 @@ void AbcCurveReader::read_curve_sample(Curve *cu,
   }
 }
 
-/* NOTE: Alembic only stores data about control points, but the Mesh
- * passed from the cache modifier contains the displist, which has more data
- * than the control points, so to avoid corrupting the displist we modify the
- * object directly and create a new Mesh from that. Also we might need to
- * create new or delete existing NURBS in the curve.
- */
 Mesh *AbcCurveReader::read_mesh(Mesh *existing_mesh,
                                 const ISampleSelector &sample_sel,
                                 int /*read_flag*/,
diff --git a/source/blender/io/alembic/intern/abc_reader_curves.h b/source/blender/io/alembic/intern/abc_reader_curves.h
index df5d68d7850..6bc0691a870 100644
--- a/source/blender/io/alembic/intern/abc_reader_curves.h
+++ b/source/blender/io/alembic/intern/abc_reader_curves.h
@@ -43,6 +43,13 @@ class AbcCurveReader final : public AbcObjectReader {
                            const char **err_str) const override;
 
   void readObjectData(Main *bmain, const Alembic::Abc::ISampleSelector &sample_sel) override;
+  /**
+   * \note Alembic only stores data about control points, but the Mesh
+   * passed from the cache modifier contains the displist, which has more data
+   * than the control points, so to avoid corrupting the displist we modify the
+   * object directly and create a new Mesh from that. Also we might need to
+   * create new or delete existing NURBS in the curve.
+   */
   struct Mesh *read_mesh(struct Mesh *existing_mesh,
                          const Alembic::Abc::ISampleSelector &sample_sel,
                          const int read_flag,
diff --git a/source/blender/io/alembic/intern/abc_reader_object.cc b/source/blender/io/alembic/intern/abc_reader_object.cc
index a6d46c4b42a..4a359c49d26 100644
--- a/source/blender/io/alembic/intern/abc_reader_object.cc
+++ b/source/blender/io/alembic/intern/abc_reader_object.cc
@@ -67,7 +67,6 @@ AbcObjectReader::AbcObjectReader(const IObject &object, ImportSettings &settings
   determine_inherits_xform();
 }
 
-/* Determine whether we can inherit our parent's XForm */
 void AbcObjectReader::determine_inherits_xform()
 {
   m_inherits_xform = false;
diff --git a/source/blender/io/alembic/intern/abc_reader_object.h b/source/blender/io/alembic/intern/abc_reader_object.h
index 6e97f841a88..f1c07da0764 100644
--- a/source/blender/io/alembic/intern/abc_reader_object.h
+++ b/source/blender/io/alembic/intern/abc_reader_object.h
@@ -171,6 +171,7 @@ class AbcObjectReader {
   void read_matrix(float r_mat[4][4], const float time, const float scale, bool &is_constant);
 
  protected:
+  /** Determine whether we can inherit our parent's XForm. */
   void determine_inherits_xform();
 };
 
diff --git a/source/blender/io/alembic/intern/abc_util.cc b/source/blender/io/alembic/intern/abc_util.cc
index 3d3ba0347c5..952fe1fa783 100644
--- a/source/blender/io/alembic/intern/abc_util.cc
+++ b/source/blender/io/alembic/intern/abc_util.cc
@@ -63,15 +63,6 @@ std::string get_valid_abc_name(const char *name)
   return name_string;
 }
 
-/**
- * \brief get_object_dag_path_name returns the name under which the object
- *  will be exported in the Alembic file. It is of the form
- *  "[../grandparent/]parent/object" if dupli_parent is NULL, or
- *  "dupli_parent/[../grandparent/]parent/object" otherwise.
- * \param ob:
- * \param dupli_parent:
- * \return
- */
 std::string get_object_dag_path_name(const Object *const ob, Object *dupli_parent)
 {
   std::string name = get_id_name(ob);
diff --git a/source/blender/io/alembic/intern/abc_util.h b/source/blender/io/alembic/intern/abc_util.h
index ced9fde0f85..3a0b2852eea 100644
--- a/source/blender/io/alembic/intern/abc_util.h
+++ b/source/blender/io/alembic/intern/abc_util.h
@@ -35,6 +35,15 @@ struct ImportSettings;
 std::string get_id_name(const ID *const id);
 std::string get_id_name(const Object *const ob);
 std::string get_valid_abc_name(const char *name);
+/**
+ * \brief get_object_dag_path_name returns the name under which the object
+ *  will be exported in the Alembic file. It is of the form
+ *  "[../grandparent/]parent/object" if dupli_parent is NULL, or
+ *  "dupli_parent/[../grandparent/]parent/object" otherwise.
+ * \param ob:
+ * \param dupli_parent:
+ * \return
+ */
 std::string get_object_dag_path_name(const Object *const ob, Object *dupli_parent);
 
 /* Convert from float to Alembic matrix representations. Does NOT convert from Z-up to Y-up. */