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

Ref T92709

source/blender/io/collada/AnimationExporter.cpp

@@ -126,7 +126,6 @@ bool AnimationExporter::exportAnimations()
   return animation_count;
 }
 
-/* called for each exported object */
 void AnimationExporter::exportAnimation(Object *ob, BCAnimationSampler &sampler)
 {
   bool container_is_open = false;
@@ -165,16 +164,6 @@ void AnimationExporter::exportAnimation(Object *ob, BCAnimationSampler &sampler)
   close_animation_container(container_is_open);
 }
 
-/*
- * Export all animation FCurves of an Object.
- *
- * NOTE: This uses the keyframes as sample points,
- * and exports "baked keyframes" while keeping the tangent information
- * of the FCurves intact. This works for simple cases, but breaks
- * especially when negative scales are involved in the animation.
- * And when parent inverse matrices are involved (when exporting
- * object hierarchies)
- */
 void AnimationExporter::export_curve_animation_set(Object *ob,
                                                    BCAnimationSampler &sampler,
                                                    bool export_as_matrix)
@@ -254,7 +243,6 @@ BC_global_rotation_type AnimationExporter::get_global_rotation_type(Object *ob)
   return (apply_global_rotation) ? BC_DATA_ROTATION : BC_OBJECT_ROTATION;
 }
 
-/* Write bone animations in transform matrix sources. */
 void AnimationExporter::export_bone_animations_recursive(Object *ob,
                                                          Bone *bone,
                                                          BCAnimationSampler &sampler)
@@ -277,14 +265,6 @@ void AnimationExporter::export_bone_animations_recursive(Object *ob,
   }
 }
 
-/**
- * In some special cases the exported Curve needs to be replaced
- * by a modified curve (for collada purposes)
- * This method checks if a conversion is necessary and if applicable
- * returns a pointer to the modified BCAnimationCurve.
- * IMPORTANT: the modified curve must be deleted by the caller when no longer needed
- * if no conversion is needed this method returns a NULL;
- */
 BCAnimationCurve *AnimationExporter::get_modified_export_curve(Object *ob,
                                                                BCAnimationCurve &curve,
                                                                BCAnimationCurveMap &curves)
@@ -657,9 +637,6 @@ std::string AnimationExporter::collada_source_from_values(
   return source_id;
 }
 
-/*
- * Create a collada matrix source for a set of samples
- */
 std::string AnimationExporter::collada_source_from_values(
     BCMatrixSampleMap &samples,
     const std::string &anim_id,
@@ -823,10 +800,6 @@ std::string AnimationExporter::get_collada_name(std::string channel_type) const
   return tm_name;
 }
 
-/*
- * Assign sid of the animated parameter or transform for rotation,
- * axis name is always appended and the value of append_axis is ignored
- */
 std::string AnimationExporter::get_collada_sid(const BCAnimationCurve &curve,
                                                const std::string axis_name)
 {

source/blender/io/collada/AnimationExporter.h

@@ -100,7 +100,7 @@ class AnimationExporter : COLLADASW::LibraryAnimations {
 
   bool exportAnimations();
 
-  /* called for each exported object */
+  /** Called for each exported object. */
   void operator()(Object *ob);
 
  protected:
@@ -148,25 +148,34 @@ class AnimationExporter : COLLADASW::LibraryAnimations {
 
   std::vector<std::vector<std::string>> anim_meta;
 
-  /* Main entry point into Animation export (called for each exported object) */
+  /** Main entry point into Animation export (called for each exported object). */
   void exportAnimation(Object *ob, BCAnimationSampler &sampler);
 
-  /* export animation as separate trans/rot/scale curves */
+  /**
+   * Export all animation FCurves of an Object.
+   *
+   * \note This uses the keyframes as sample points,
+   * and exports "baked keyframes" while keeping the tangent information
+   * of the FCurves intact. This works for simple cases, but breaks
+   * especially when negative scales are involved in the animation.
+   * And when parent inverse matrices are involved (when exporting
+   * object hierarchies)
+   */
   void export_curve_animation_set(Object *ob, BCAnimationSampler &sampler, bool export_as_matrix);
 
-  /* export one single curve */
+  /** Export one single curve. */
   void export_curve_animation(Object *ob, BCAnimationCurve &curve);
 
-  /* export animation as matrix data */
+  /** Export animation as matrix data. */
   void export_matrix_animation(Object *ob, BCAnimationSampler &sampler);
 
-  /* step through the bone hierarchy */
+  /** Write bone animations in transform matrix sources (step through the bone hierarchy). */
   void export_bone_animations_recursive(Object *ob_arm, Bone *bone, BCAnimationSampler &sampler);
 
-  /* Export for one bone */
+  /** Export for one bone. */
   void export_bone_animation(Object *ob, Bone *bone, BCFrames &frames, BCMatrixSampleMap &samples);
 
-  /* call to the low level collada exporter */
+  /** Call to the low level collada exporter. */
   void export_collada_curve_animation(std::string id,
                                       std::string name,
                                       std::string target,
@@ -174,7 +183,7 @@ class AnimationExporter : COLLADASW::LibraryAnimations {
                                       BCAnimationCurve &curve,
                                       BC_global_rotation_type global_rotation_type);
 
-  /* call to the low level collada exporter */
+  /** Call to the low level collada exporter. */
   void export_collada_matrix_animation(std::string id,
                                        std::string name,
                                        std::string target,
@@ -183,29 +192,38 @@ class AnimationExporter : COLLADASW::LibraryAnimations {
                                        BC_global_rotation_type global_rotation_type,
                                        Matrix &parentinv);
 
+  /**
+   * In some special cases the exported Curve needs to be replaced
+   * by a modified curve (for collada purposes)
+   * This method checks if a conversion is necessary and if applicable
+   * returns a pointer to the modified BCAnimationCurve.
+   * IMPORTANT: the modified curve must be deleted by the caller when no longer needed
+   * if no conversion is needed this method returns a NULL;
+   */
   BCAnimationCurve *get_modified_export_curve(Object *ob,
                                               BCAnimationCurve &curve,
                                               BCAnimationCurveMap &curves);
 
-  /* Helper functions */
+  /* Helper functions. */
+
   void openAnimationWithClip(std::string id, std::string name);
   bool open_animation_container(bool has_container, Object *ob);
   void close_animation_container(bool has_container);
 
-  /* Input and Output sources (single valued) */
+  /** Input and Output sources (single valued). */
   std::string collada_source_from_values(BC_animation_source_type source_type,
                                          COLLADASW::InputSemantic::Semantics semantic,
                                          std::vector<float> &values,
                                          const std::string &anim_id,
                                          const std::string axis_name);
 
-  /* Output sources (matrix data) */
+  /** Output sources (matrix data). * Create a collada matrix source for a set of samples. */
   std::string collada_source_from_values(BCMatrixSampleMap &samples,
                                          const std::string &anim_id,
                                          BC_global_rotation_type global_rotation_type,
                                          Matrix &parentinv);
 
-  /* Interpolation sources */
+  /** Interpolation sources. */
   std::string collada_linear_interpolation_source(int tot, const std::string &anim_id);
 
   /* source ID = animation_name + semantic_suffix */
@@ -240,6 +258,10 @@ class AnimationExporter : COLLADASW::LibraryAnimations {
 
   std::string get_axis_name(std::string channel, int id);
   std::string get_collada_name(std::string channel_type) const;
+  /**
+   * Assign sid of the animated parameter or transform for rotation,
+   * axis name is always appended and the value of append_axis is ignored.
+   */
   std::string get_collada_sid(const BCAnimationCurve &curve, const std::string axis_name);
 
   /* ===================================== */

source/blender/io/collada/AnimationImporter.cpp

@@ -81,7 +81,6 @@ void AnimationImporter::add_bezt(FCurve *fcu,
   calchandles_fcurve(fcu);
 }
 
-/* create one or several fcurves depending on the number of parameters being animated */
 void AnimationImporter::animation_to_fcurves(COLLADAFW::AnimationCurve *curve)
 {
   COLLADAFW::FloatOrDoubleArray &input = curve->getInputValues();
@@ -323,7 +322,6 @@ bool AnimationImporter::write_animation(const COLLADAFW::Animation *anim)
   return true;
 }
 
-/* called on post-process stage after writeVisualScenes */
 bool AnimationImporter::write_animation_list(const COLLADAFW::AnimationList *animlist)
 {
   const COLLADAFW::UniqueId &animlist_id = animlist->getUniqueId();
@@ -343,11 +341,6 @@ bool AnimationImporter::write_animation_list(const COLLADAFW::AnimationList *ani
   return true;
 }
 
-/**
- * \todo refactor read_node_transform to not automatically apply anything,
- * but rather return the transform matrix, so caller can do with it what is
- * necessary. Same for \ref get_node_mat
- */
 void AnimationImporter::read_node_transform(COLLADAFW::Node *node, Object *ob)
 {
   float mat[4][4];
@@ -463,7 +456,6 @@ virtual void AnimationImporter::change_eul_to_quat(Object *ob, bAction *act)
 }
 #endif
 
-/* sets the rna_path and array index to curve */
 void AnimationImporter::modify_fcurve(std::vector<FCurve *> *curves,
                                       const char *rna_path,
                                       int array_index,
@@ -535,8 +527,6 @@ static int get_animation_axis_index(const COLLADABU::Math::Vector3 &axis)
   return index;
 }
 
-/* creates the rna_paths and array indices of fcurves from animations using transformation and
- * bound animation class of each animation. */
 void AnimationImporter::Assign_transform_animations(
     COLLADAFW::Transformation *transform,
     const COLLADAFW::AnimationList::AnimationBinding *binding,
@@ -654,8 +644,6 @@ void AnimationImporter::Assign_transform_animations(
   }
 }
 
-/* creates the rna_paths and array indices of fcurves from animations using color and bound
- * animation class of each animation. */
 void AnimationImporter::Assign_color_animations(const COLLADAFW::UniqueId &listid,
                                                 ListBase *AnimCurves,
                                                 const char *anim_type)
@@ -765,11 +753,6 @@ float AnimationImporter::convert_to_focal_length(float in_xfov,
   return fov_to_focallength(xfov, sensorx);
 }
 
-/*
- * Lens animations must be stored in COLLADA by using FOV,
- * while blender internally uses focal length.
- * The imported animation curves must be converted appropriately.
- */
 void AnimationImporter::Assign_lens_animations(const COLLADAFW::UniqueId &listid,
                                                ListBase *AnimCurves,
                                                const double aspect,
@@ -1403,8 +1386,6 @@ void AnimationImporter::add_bone_animation_sampled(Object *ob,
   chan->rotmode = ROT_MODE_QUAT;
 }
 
-/* Check if object is animated by checking if animlist_map
- * holds the animlist_id of node transforms */
 AnimationImporter::AnimMix *AnimationImporter::get_animation_type(
     const COLLADAFW::Node *node,
     std::map<COLLADAFW::UniqueId, const COLLADAFW::Object *> FW_object_map)
@@ -1514,7 +1495,6 @@ int AnimationImporter::setAnimType(const COLLADAFW::Animatable *prop, int types,
   return anim_type;
 }
 
-/* Is not used anymore. */
 void AnimationImporter::find_frames_old(std::vector<float> *frames,
                                         COLLADAFW::Node *node,
                                         COLLADAFW::Transformation::TransformationType tm_type)
@@ -1579,9 +1559,6 @@ void AnimationImporter::find_frames_old(std::vector<float> *frames,
   }
 }
 
-/* prerequisites:
- * animlist_map - map animlist id -> animlist
- * curve_map - map anim id -> curve(s) */
 Object *AnimationImporter::translate_animation_OLD(
     COLLADAFW::Node *node,
     std::map<COLLADAFW::UniqueId, Object *> &object_map,
@@ -1854,9 +1831,6 @@ Object *AnimationImporter::translate_animation_OLD(
   return job;
 }
 
-/* internal, better make it private
- * warning: evaluates only rotation and only assigns matrix transforms now
- * prerequisites: animlist_map, curve_map */
 void AnimationImporter::evaluate_transform_at_frame(float mat[4][4],
                                                     COLLADAFW::Node *node,
                                                     float fra)
@@ -1915,7 +1889,6 @@ static void report_class_type_unsupported(const char *path,
   }
 }
 
-/* return true to indicate that mat contains a sane value */
 bool AnimationImporter::evaluate_animation(COLLADAFW::Transformation *tm,
                                            float mat[4][4],
                                            float fra,
@@ -2063,7 +2036,6 @@ bool AnimationImporter::evaluate_animation(COLLADAFW::Transformation *tm,
   return false;
 }
 
-/* gives a world-space mat of joint at rest position */
 void AnimationImporter::get_joint_rest_mat(float mat[4][4],
                                            COLLADAFW::Node *root,
                                            COLLADAFW::Node *node)
@@ -2079,7 +2051,6 @@ void AnimationImporter::get_joint_rest_mat(float mat[4][4],
   }
 }
 
-/* gives a world-space mat, end's mat not included */
 bool AnimationImporter::calc_joint_parent_mat_rest(float mat[4][4],
                                                    float par[4][4],
                                                    COLLADAFW::Node *node,

source/blender/io/collada/AnimationImporter.h

@@ -75,7 +75,9 @@ class AnimationImporter : private TransformReader, public AnimationImporterBase
                 float value,
                 eBezTriple_Interpolation ipo = BEZT_IPO_LIN);
 
-  /* create one or several fcurves depending on the number of parameters being animated */
+  /**
+   * Create one or several fcurves depending on the number of parameters being animated.
+   */
   void animation_to_fcurves(COLLADAFW::AnimationCurve *curve);
 
   void fcurve_deg_to_rad(FCurve *cu);
@@ -143,9 +145,14 @@ class AnimationImporter : private TransformReader, public AnimationImporterBase
   void set_import_from_version(std::string import_from_version);
   bool write_animation(const COLLADAFW::Animation *anim);
 
-  /* called on post-process stage after writeVisualScenes */
+  /** Called on post-process stage after writeVisualScenes. */
   bool write_animation_list(const COLLADAFW::AnimationList *animlist);
 
+  /**
+   * \todo refactor read_node_transform to not automatically apply anything,
+   * but rather return the transform matrix, so caller can do with it what is
+   * necessary. Same for \ref get_node_mat
+   */
   void read_node_transform(COLLADAFW::Node *node, Object *ob);
 #if 0
   virtual void change_eul_to_quat(Object *ob, bAction *act);
@@ -157,6 +164,10 @@ class AnimationImporter : private TransformReader, public AnimationImporterBase
                             std::map<COLLADAFW::UniqueId, const COLLADAFW::Object *> FW_object_map,
                             std::map<COLLADAFW::UniqueId, Material *> uid_material_map);
 
+  /**
+   * Check if object is animated by checking if animlist_map
+   * holds the animlist_id of node transforms.
+   */
   AnimMix *get_animation_type(
       const COLLADAFW::Node *node,
       std::map<COLLADAFW::UniqueId, const COLLADAFW::Object *> FW_object_map);
@@ -173,18 +184,31 @@ class AnimationImporter : private TransformReader, public AnimationImporterBase
                                   COLLADAFW::Node *node,
                                   COLLADAFW::Transformation *tm);
 
+  /**
+   * Creates the rna_paths and array indices of fcurves from animations using transformation and
+   * bound animation class of each animation.
+   */
   void Assign_transform_animations(COLLADAFW::Transformation *transform,
                                    const COLLADAFW::AnimationList::AnimationBinding *binding,
                                    std::vector<FCurve *> *curves,
                                    bool is_joint,
                                    char *joint_path);
 
+  /**
+   * Creates the rna_paths and array indices of fcurves from animations using color and bound
+   * animation class of each animation.
+   */
   void Assign_color_animations(const COLLADAFW::UniqueId &listid,
                                ListBase *AnimCurves,
                                const char *anim_type);
   void Assign_float_animations(const COLLADAFW::UniqueId &listid,
                                ListBase *AnimCurves,
                                const char *anim_type);
+  /**
+   * Lens animations must be stored in COLLADA by using FOV,
+   * while blender internally uses focal length.
+   * The imported animation curves must be converted appropriately.
+   */
   void Assign_lens_animations(const COLLADAFW::UniqueId &listid,
                               ListBase *AnimCurves,
                               const double aspect,
@@ -194,14 +218,17 @@ class AnimationImporter : private TransformReader, public AnimationImporterBase
 
   int setAnimType(const COLLADAFW::Animatable *prop, int type, int addition);
 
+  /** Sets the rna_path and array index to curve. */
   void modify_fcurve(std::vector<FCurve *> *curves,
                      const char *rna_path,
                      int array_index,
                      int scale = 1);
   void unused_fcurve(std::vector<FCurve *> *curves);
-  /* prerequisites:
+  /**
+   * Prerequisites:
    * animlist_map - map animlist id -> animlist
-   * curve_map - map anim id -> curve(s) */
+   * curve_map - map anim id -> curve(s).
+   */
   Object *translate_animation_OLD(COLLADAFW::Node *node,
                                   std::map<COLLADAFW::UniqueId, Object *> &object_map,
                                   std::map<COLLADAFW::UniqueId, COLLADAFW::Node *> &root_map,
@@ -209,24 +236,27 @@ class AnimationImporter : private TransformReader, public AnimationImporterBase
                                   Object *par_job = NULL);
 
   void find_frames(std::vector<float> *frames, std::vector<FCurve *> *curves);
+  /** Is not used anymore. */
   void find_frames_old(std::vector<float> *frames,
                        COLLADAFW::Node *node,
                        COLLADAFW::Transformation::TransformationType tm_type);
-  /* internal, better make it private
+  /**
-   * warning: evaluates only rotation
+   * Internal, better make it private
-   * prerequisites: animlist_map, curve_map */
+   * warning: evaluates only rotation and only assigns matrix transforms now
+   * prerequisites: animlist_map, curve_map.
+   */
   void evaluate_transform_at_frame(float mat[4][4], COLLADAFW::Node *node, float fra);
 
-  /* return true to indicate that mat contains a sane value */
+  /** Return true to indicate that mat contains a sane value. */
   bool evaluate_animation(COLLADAFW::Transformation *tm,
                           float mat[4][4],
                           float fra,
                           const char *node_id);
 
-  /* gives a world-space mat of joint at rest position */
+  /** Gives a world-space mat of joint at rest position. */
   void get_joint_rest_mat(float mat[4][4], COLLADAFW::Node *root, COLLADAFW::Node *node);
 
-  /* gives a world-space mat, end's mat not included */
+  /** * Gives a world-space mat, end's mat not included. */
   bool calc_joint_parent_mat_rest(float mat[4][4],
                                   float par[4][4],
                                   COLLADAFW::Node *node,
@@ -239,8 +269,10 @@ class AnimationImporter : private TransformReader, public AnimationImporterBase
 #endif
 
 #if 0
-  /* recursively evaluates joint tree until end is found, mat then is world-space matrix of end
+  /**
-   * mat must be identity on enter, node must be root */
+   * Recursively evaluates joint tree until end is found, mat then is world-space matrix of end
+   * mat must be identity on enter, node must be root.
+   */
   bool evaluate_joint_world_transform_at_frame(
       float mat[4][4], float par[4][4], COLLADAFW::Node *node, COLLADAFW::Node *end, float fra);
 #endif

source/blender/io/collada/ArmatureExporter.cpp

@@ -40,7 +40,6 @@
 #include "GeometryExporter.h"
 #include "SceneExporter.h"
 
-/* write bone nodes */
 void ArmatureExporter::add_armature_bones(Object *ob_arm,
                                           ViewLayer *view_layer,
                                           SceneExporter *se,
@@ -144,7 +143,6 @@ void ArmatureExporter::find_objects_using_armature(Object *ob_arm,
 }
 #endif
 
-/* parent_mat is armature-space */
 void ArmatureExporter::add_bone_node(Bone *bone,
                                      Object *ob_arm,
                                      SceneExporter *se,

source/blender/io/collada/ArmatureExporter.h

@@ -62,6 +62,7 @@ class ArmatureExporter : public COLLADASW::LibraryControllers,
   {
   }
 
+  /* write bone nodes */
   void add_armature_bones(Object *ob_arm,
                           ViewLayer *view_layer,
                           SceneExporter *se,
@@ -83,8 +84,11 @@ class ArmatureExporter : public COLLADASW::LibraryControllers,
   void find_objects_using_armature(Object *ob_arm, std::vector<Object *> &objects, Scene *sce);
 #endif
 
-  /* Scene, SceneExporter and the list of child_objects
+  /**
-   * are required for writing bone parented objects */
+   * Scene, SceneExporter and the list of child_objects
+   * are required for writing bone parented objects.
+   * \param parent_mat: is armature-space.
+   */
   void add_bone_node(Bone *bone,
                      Object *ob_arm,
                      SceneExporter *se,

source/blender/io/collada/ArmatureImporter.cpp

@@ -220,12 +220,6 @@ int ArmatureImporter::create_bone(SkinInfo *skin,
   return chain_length + 1;
 }
 
-/**
- * Collada only knows Joints, hence bones at the end of a bone chain
- * don't have a defined length. This function guesses reasonable
- * tail locations for the affected bones (nodes which don't have any connected child)
- * Hint: The extended_bones set gets populated in ArmatureImporter::create_bone
- */
 void ArmatureImporter::fix_leaf_bone_hierarchy(bArmature *armature,
                                                Bone *bone,
                                                bool fix_orientation)
@@ -757,11 +751,6 @@ bool ArmatureImporter::node_is_decomposed(const COLLADAFW::Node *node)
   return true;
 }
 
-/**
- * root - if this joint is the top joint in hierarchy, if a joint
- * is a child of a node (not joint), root should be true since
- * this is where we build armature bones from
- */
 void ArmatureImporter::add_root_joint(COLLADAFW::Node *node, Object *parent)
 {
   root_joints.push_back(node);
@@ -786,7 +775,6 @@ void ArmatureImporter::add_root_joint(COLLADAFW::Node *node)
 }
 #endif
 
-/* here we add bones to armatures, having armatures previously created in write_controller */
 void ArmatureImporter::make_armatures(bContext *C, std::vector<Object *> &objects_to_scale)
 {
   Main *bmain = CTX_data_main(C);
@@ -1042,7 +1030,6 @@ void ArmatureImporter::get_rna_path_for_joint(COLLADAFW::Node *node,
   BLI_snprintf(joint_path, count, "pose.bones[\"%s\"]", bone_name_esc);
 }
 
-/* gives a world-space mat */
 bool ArmatureImporter::get_joint_bind_mat(float m[4][4], COLLADAFW::Node *joint)
 {
   std::map<COLLADAFW::UniqueId, SkinInfo>::iterator it;

source/blender/io/collada/ArmatureImporter.h

@@ -111,6 +111,12 @@ class ArmatureImporter : private TransformReader {
                                   std::vector<std::string> &layer_labels,
                                   BoneExtensionMap &extended_bones);
 
+  /**
+   * Collada only knows Joints, hence bones at the end of a bone chain
+   * don't have a defined length. This function guesses reasonable
+   * tail locations for the affected bones (nodes which don't have any connected child)
+   * Hint: The extended_bones set gets populated in ArmatureImporter::create_bone
+   */
   void fix_leaf_bone_hierarchy(bArmature *armature, Bone *bone, bool fix_orientation);
   void fix_leaf_bone(bArmature *armature, EditBone *ebone, BoneExtended *be, bool fix_orientation);
   void fix_parent_connect(bArmature *armature, Bone *bone);
@@ -152,15 +158,20 @@ class ArmatureImporter : private TransformReader {
                    const ImportSettings *import_settings);
   ~ArmatureImporter();
 
+  /**
+   * root - if this joint is the top joint in hierarchy, if a joint
+   * is a child of a node (not joint), root should be true since
+   * this is where we build armature bones from
+   */
   void add_root_joint(COLLADAFW::Node *node, Object *parent);
 
-  /* here we add bones to armatures, having armatures previously created in write_controller */
+  /** Here we add bones to armatures, having armatures previously created in write_controller. */
   void make_armatures(bContext *C, std::vector<Object *> &objects_to_scale);
 
   void make_shape_keys(bContext *C);
 
 #if 0
-  /* link with meshes, create vertex groups, assign weights */
+  /** Link with meshes, create vertex groups, assign weights. */
   void link_armature(Object *ob_arm,
                      const COLLADAFW::UniqueId &geom_id,
                      const COLLADAFW::UniqueId &controller_data_id);
@@ -176,7 +187,7 @@ class ArmatureImporter : private TransformReader {
 
   void get_rna_path_for_joint(COLLADAFW::Node *node, char *joint_path, size_t count);
 
-  /* gives a world-space mat */
+  /** Gives a world-space mat. */
   bool get_joint_bind_mat(float m[4][4], COLLADAFW::Node *joint);
 
   void set_tags_map(TagsMap &tags_map);

source/blender/io/collada/BCAnimationSampler.cpp

@@ -418,11 +418,6 @@ void BCAnimationSampler::generate_transforms(Object *ob, Bone *bone, BCAnimation
   }
 }
 
-/**
- * Collect all keyframes from all animation curves related to the object.
- * The bc_get... functions check for NULL and correct object type.
- * The #add_keyframes_from() function checks for NULL.
- */
 void BCAnimationSampler::initialize_keyframes(BCFrameSet &frameset, Object *ob)
 {
   frameset.clear();
@@ -517,7 +512,6 @@ BCSample &BCSampleFrame::add(Object *ob)
   return *sample;
 }
 
-/* Get the matrix for the given key, returns Unity when the key does not exist */
 const BCSample *BCSampleFrame::get_sample(Object *ob) const
 {
   BCSampleMap::const_iterator it = sampleMap.find(ob);
@@ -537,7 +531,6 @@ const BCMatrix *BCSampleFrame::get_sample_matrix(Object *ob) const
   return &sample->get_matrix();
 }
 
-/* Get the matrix for the given Bone, returns Unity when the Object is not sampled. */
 const BCMatrix *BCSampleFrame::get_sample_matrix(Object *ob, Bone *bone) const
 {
   BCSampleMap::const_iterator it = sampleMap.find(ob);
@@ -550,13 +543,11 @@ const BCMatrix *BCSampleFrame::get_sample_matrix(Object *ob, Bone *bone) const
   return bc_bone;
 }
 
-/* Check if the key is in this BCSampleFrame */
 bool BCSampleFrame::has_sample_for(Object *ob) const
 {
   return sampleMap.find(ob) != sampleMap.end();
 }
 
-/* Check if the Bone is in this BCSampleFrame */
 bool BCSampleFrame::has_sample_for(Object *ob, Bone *bone) const
 {
   const BCMatrix *bc_bone = get_sample_matrix(ob, bone);
@@ -575,7 +566,6 @@ BCSample &BCSampleFrameContainer::add(Object *ob, int frame_index)
 /* Below are the getters which we need to export the data */
 /* ====================================================== */
 
-/* Return either the BCSampleFrame or NULL if frame does not exist. */
 BCSampleFrame *BCSampleFrameContainer::get_frame(int frame_index)
 {
   BCSampleFrameMap::iterator it = sample_frames.find(frame_index);
@@ -583,7 +573,6 @@ BCSampleFrame *BCSampleFrameContainer::get_frame(int frame_index)
   return frame;
 }
 
-/* Return a list of all frames that need to be sampled */
 int BCSampleFrameContainer::get_frames(std::vector<int> &frames) const
 {
   frames.clear(); /* safety; */

source/blender/io/collada/BCAnimationSampler.h

@@ -89,11 +89,16 @@ class BCSampleFrame {
   BCSample &add(Object *ob);
 
   /* Following methods return NULL if object is not in the sampleMap. */
+
+  /** Get the matrix for the given key, returns Unity when the key does not exist. */
   const BCSample *get_sample(Object *ob) const;
   const BCMatrix *get_sample_matrix(Object *ob) const;
+  /** Get the matrix for the given Bone, returns Unity when the Object is not sampled. */
   const BCMatrix *get_sample_matrix(Object *ob, Bone *bone) const;
 
+  /** Check if the key is in this BCSampleFrame. */
   bool has_sample_for(Object *ob) const;
+  /** Check if the Bone is in this BCSampleFrame. */
   bool has_sample_for(Object *ob, Bone *bone) const;
 };
 
@@ -134,8 +139,10 @@ class BCSampleFrameContainer {
   }
 
   BCSample &add(Object *ob, int frame_index);
-  BCSampleFrame *get_frame(int frame_index); /* returns NULL if frame does not exist */
+  /** Return either the #BCSampleFrame or NULL if frame does not exist. */
+  BCSampleFrame *get_frame(int frame_index);
 
+  /** Return a list of all frames that need to be sampled. */
   int get_frames(std::vector<int> &frames) const;
   int get_frames(Object *ob, BCFrames &frames) const;
   int get_frames(Object *ob, Bone *bone, BCFrames &frames) const;
@@ -159,6 +166,11 @@ class BCAnimationSampler {
   void generate_transforms(Object *ob, Bone *bone, BCAnimationCurveMap &curves);
 
   void initialize_curves(BCAnimationCurveMap &curves, Object *ob);
+  /**
+   * Collect all keyframes from all animation curves related to the object.
+   * The bc_get... functions check for NULL and correct object type.
+   * The #add_keyframes_from() function checks for NULL.
+   */
   void initialize_keyframes(BCFrameSet &frameset, Object *ob);
   BCSample &sample_object(Object *ob, int frame_index, bool for_opensim);
   void update_animation_curves(BCAnimation &animation,

source/blender/io/collada/BCMath.cpp

@@ -183,8 +183,6 @@ void BCMatrix::unit()
   quat_to_eul(this->rot, this->q);
 }
 
-/* We need double here because the OpenCollada API needs it.
- * precision = -1 indicates to not limit the precision. */
 void BCMatrix::get_matrix(DMatrix &mat, const bool transposed, const int precision) const
 {
   for (int i = 0; i < 4; i++) {

source/blender/io/collada/BCMath.h

@@ -78,6 +78,10 @@ class BCMatrix {
   BCMatrix(Object *ob);
   BCMatrix();
 
+  /**
+   * We need double here because the OpenCollada API needs it.
+   * precision = -1 indicates to not limit the precision.
+   */
   void get_matrix(DMatrix &matrix, const bool transposed = false, const int precision = -1) const;
   void get_matrix(Matrix &matrix,
                   const bool transposed = false,

source/blender/io/collada/BCSampleData.cpp

@@ -39,7 +39,6 @@ void BCSample::add_bone_matrix(Bone *bone, Matrix &mat)
   bonemats[bone] = matrix;
 }
 
-/* Get channel value */
 bool BCSample::get_value(std::string channel_target, const int array_index, float *val) const
 {
   std::string bname = bc_string_before(channel_target, ".");

source/blender/io/collada/BCSampleData.h

@@ -53,6 +53,7 @@ class BCSample {
 
   void add_bone_matrix(Bone *bone, Matrix &mat);
 
+  /** Get channel value. */
   bool get_value(std::string channel_target, const int array_index, float *val) const;
   const BCMatrix &get_matrix() const;
   const BCMatrix *get_matrix(Bone *bone) const; /* returns NULL if bone is not animated */

source/blender/io/collada/BlenderContext.cpp

@@ -31,12 +31,6 @@ bool bc_is_base_node(LinkNode *export_set, Object *ob, ViewLayer *view_layer)
   return (root == ob);
 }
 
-/**
- * Returns the highest selected ancestor
- * returns NULL if no ancestor is selected
- * IMPORTANT: This function expects that all exported objects have set:
- * ob->id.tag & LIB_TAG_DOIT
- */
 Object *bc_get_highest_exported_ancestor_or_self(LinkNode *export_set,
                                                  Object *ob,
                                                  ViewLayer *view_layer)

source/blender/io/collada/BlenderContext.h

@@ -38,6 +38,12 @@ static const BC_global_up_axis BC_DEFAULT_UP = BC_GLOBAL_UP_Z;
 
 bool bc_is_in_Export_set(LinkNode *export_set, Object *ob, ViewLayer *view_layer);
 bool bc_is_base_node(LinkNode *export_set, Object *ob, ViewLayer *view_layer);
+/**
+ * Returns the highest selected ancestor
+ * returns NULL if no ancestor is selected
+ * IMPORTANT: This function expects that all exported objects have set:
+ * `ob->id.tag & LIB_TAG_DOIT`
+ */
 Object *bc_get_highest_exported_ancestor_or_self(LinkNode *export_set,
                                                  Object *ob,
                                                  ViewLayer *view_layer);

source/blender/io/collada/ControllerExporter.cpp

@@ -161,8 +161,6 @@ std::string ControllerExporter::get_controller_id(Key *key, Object *ob)
   return translate_id(id_name(ob)) + MORPH_CONTROLLER_ID_SUFFIX;
 }
 
-/* ob should be of type OB_MESH
- * both args are required */
 void ControllerExporter::export_skin_controller(Object *ob, Object *ob_arm)
 {
   /* joint names
@@ -377,7 +375,6 @@ std::string ControllerExporter::add_morph_weights(Key *key, Object *ob)
   return source_id;
 }
 
-/* Added to implement support for animations. */
 void ControllerExporter::add_weight_extras(Key *key)
 {
   /* can also try the base element and param alternative */

source/blender/io/collada/ControllerExporter.h

@@ -91,8 +91,7 @@ class ControllerExporter : public COLLADASW::LibraryControllers,
 
   std::string get_controller_id(Key *key, Object *ob);
 
-  /* ob should be of type OB_MESH
+  /** `ob` should be of type OB_MESH, both arguments are required. */
-   * both args are required */
   void export_skin_controller(Object *ob, Object *ob_arm);
 
   void export_morph_controller(Object *ob, Key *key);
@@ -107,6 +106,9 @@ class ControllerExporter : public COLLADASW::LibraryControllers,
 
   std::string add_morph_weights(Key *key, Object *ob);
 
+  /**
+   * Added to implement support for animations.
+   */
   void add_weight_extras(Key *key);
 
   std::string add_joints_source(Object *ob_arm,

source/blender/io/collada/DocumentImporter.cpp

@@ -320,10 +320,6 @@ void DocumentImporter::translate_anim_recursive(COLLADAFW::Node *node,
   }
 }
 
-/**
- * If the imported file was made with Blender, return the Blender version used,
- * otherwise return an empty std::string
- */
 std::string DocumentImporter::get_import_version(const COLLADAFW::FileInfo *asset)
 {
   const char AUTORING_TOOL[] = "authoring_tool";
@@ -347,10 +343,6 @@ std::string DocumentImporter::get_import_version(const COLLADAFW::FileInfo *asse
   return "";
 }
 
-/**
- * When this method is called, the writer must write the global document asset.
- * \return The writer should return true, if writing succeeded, false otherwise.
- */
 bool DocumentImporter::writeGlobalAsset(const COLLADAFW::FileInfo *asset)
 {
   unit_converter.read_asset(asset);
@@ -359,10 +351,6 @@ bool DocumentImporter::writeGlobalAsset(const COLLADAFW::FileInfo *asset)
   return true;
 }
 
-/**
- * When this method is called, the writer must write the scene.
- * \return The writer should return true, if writing succeeded, false otherwise.
- */
 bool DocumentImporter::writeScene(const COLLADAFW::Scene *scene)
 {
   /* XXX could store the scene id, but do nothing for now */
@@ -476,8 +464,6 @@ Object *DocumentImporter::create_instance_node(Object *source_ob,
   return obn;
 }
 
-/* to create constraints off node <extra> tags. Assumes only constraint data in
- * current <extra> with blender profile. */
 void DocumentImporter::create_constraints(ExtraTags *et, Object *ob)
 {
   if (et && et->isProfile("blender")) {
@@ -712,10 +698,6 @@ finally:
   return root_objects;
 }
 
-/**
- * When this method is called, the writer must write the entire visual scene.
- * Return The writer should return true, if writing succeeded, false otherwise.
- */
 bool DocumentImporter::writeVisualScene(const COLLADAFW::VisualScene *visualScene)
 {
   if (mImportStage == Fetching_Controller_data) {
@@ -738,11 +720,6 @@ bool DocumentImporter::writeVisualScene(const COLLADAFW::VisualScene *visualScen
   return true;
 }
 
-/**
- * When this method is called, the writer must handle all nodes contained in the
- * library nodes.
- * \return The writer should return true, if writing succeeded, false otherwise.
- */
 bool DocumentImporter::writeLibraryNodes(const COLLADAFW::LibraryNodes *libraryNodes)
 {
   if (mImportStage == Fetching_Controller_data) {
@@ -762,10 +739,6 @@ bool DocumentImporter::writeLibraryNodes(const COLLADAFW::LibraryNodes *libraryN
   return true;
 }
 
-/**
- * When this method is called, the writer must write the geometry.
- * \return The writer should return true, if writing succeeded, false otherwise.
- */
 bool DocumentImporter::writeGeometry(const COLLADAFW::Geometry *geom)
 {
   if (mImportStage == Fetching_Controller_data) {
@@ -775,10 +748,6 @@ bool DocumentImporter::writeGeometry(const COLLADAFW::Geometry *geom)
   return mesh_importer.write_geometry(geom);
 }
 
-/**
- * When this method is called, the writer must write the material.
- * \return The writer should return true, if writing succeeded, false otherwise.
- */
 bool DocumentImporter::writeMaterial(const COLLADAFW::Material *cmat)
 {
   if (mImportStage == Fetching_Controller_data) {
@@ -821,10 +790,6 @@ void DocumentImporter::write_profile_COMMON(COLLADAFW::EffectCommon *ef, Materia
   matNode.update_material_nodetree();
 }
 
-/**
- * When this method is called, the writer must write the effect.
- * \return The writer should return true, if writing succeeded, false otherwise.
- */
 bool DocumentImporter::writeEffect(const COLLADAFW::Effect *effect)
 {
   if (mImportStage == Fetching_Controller_data) {
@@ -860,10 +825,6 @@ bool DocumentImporter::writeEffect(const COLLADAFW::Effect *effect)
   return true;
 }
 
-/**
- * When this method is called, the writer must write the camera.
- * \return The writer should return true, if writing succeeded, false otherwise.
- */
 bool DocumentImporter::writeCamera(const COLLADAFW::Camera *camera)
 {
   if (mImportStage == Fetching_Controller_data) {
@@ -973,10 +934,6 @@ bool DocumentImporter::writeCamera(const COLLADAFW::Camera *camera)
   return true;
 }
 
-/**
- * When this method is called, the writer must write the image.
- * \return The writer should return true, if writing succeeded, false otherwise.
- */
 bool DocumentImporter::writeImage(const COLLADAFW::Image *image)
 {
   if (mImportStage == Fetching_Controller_data) {
@@ -1013,10 +970,6 @@ bool DocumentImporter::writeImage(const COLLADAFW::Image *image)
   return true;
 }
 
-/**
- * When this method is called, the writer must write the light.
- * \return The writer should return true, if writing succeeded, false otherwise.
- */
 bool DocumentImporter::writeLight(const COLLADAFW::Light *light)
 {
   if (mImportStage == Fetching_Controller_data) {
@@ -1164,7 +1117,6 @@ bool DocumentImporter::writeLight(const COLLADAFW::Light *light)
   return true;
 }
 
-/* this function is called only for animations that pass COLLADAFW::validate */
 bool DocumentImporter::writeAnimation(const COLLADAFW::Animation *anim)
 {
   if (mImportStage == Fetching_Controller_data) {
@@ -1174,7 +1126,6 @@ bool DocumentImporter::writeAnimation(const COLLADAFW::Animation *anim)
   return anim_importer.write_animation(anim);
 }
 
-/* called on post-process stage after writeVisualScenes */
 bool DocumentImporter::writeAnimationList(const COLLADAFW::AnimationList *animationList)
 {
   if (mImportStage == Fetching_Controller_data) {
@@ -1186,10 +1137,10 @@ bool DocumentImporter::writeAnimationList(const COLLADAFW::AnimationList *animat
 }
 
 #if WITH_OPENCOLLADA_ANIMATION_CLIP
-/* Since opencollada 1.6.68
- * called on post-process stage after writeVisualScenes */
 bool DocumentImporter::writeAnimationClip(const COLLADAFW::AnimationClip *animationClip)
 {
+  /* Since opencollada 1.6.68: called on post-process stage after writeVisualScenes. */
+
   if (mImportStage == Fetching_Controller_data) {
     return true;
   }
@@ -1200,16 +1151,11 @@ bool DocumentImporter::writeAnimationClip(const COLLADAFW::AnimationClip *animat
 }
 #endif
 
-/**
- * When this method is called, the writer must write the skin controller data.
- * \return The writer should return true, if writing succeeded, false otherwise.
- */
 bool DocumentImporter::writeSkinControllerData(const COLLADAFW::SkinControllerData *skin)
 {
   return armature_importer.write_skin_controller_data(skin);
 }
 
-/* this is called on postprocess, before writeVisualScenes */
 bool DocumentImporter::writeController(const COLLADAFW::Controller *controller)
 {
   if (mImportStage == Fetching_Controller_data) {

source/blender/io/collada/DocumentImporter.h

@@ -64,6 +64,10 @@ class DocumentImporter : COLLADAFW::IWriter {
   Object *create_camera_object(COLLADAFW::InstanceCamera *, Scene *);
   Object *create_light_object(COLLADAFW::InstanceLight *, Scene *);
   Object *create_instance_node(Object *, COLLADAFW::Node *, COLLADAFW::Node *, Scene *, bool);
+  /**
+   * To create constraints off node <extra> tags. Assumes only constraint data in
+   * current <extra> with blender profile.
+   */
   void create_constraints(ExtraTags *et, Object *ob);
   std::vector<Object *> *write_node(COLLADAFW::Node *, COLLADAFW::Node *, Scene *, Object *, bool);
   void write_profile_COMMON(COLLADAFW::EffectCommon *, Material *);
@@ -86,17 +90,44 @@ class DocumentImporter : COLLADAFW::IWriter {
    */
   void finish();
 
+  /**
+   * When this method is called, the writer must write the global document asset.
+   * \return The writer should return true, if writing succeeded, false otherwise.
+   */
   bool writeGlobalAsset(const COLLADAFW::FileInfo *);
+  /**
+   * If the imported file was made with Blender, return the Blender version used,
+   * otherwise return an empty std::string
+   */
   std::string get_import_version(const COLLADAFW::FileInfo *asset);
 
+  /**
+   * When this method is called, the writer must write the scene.
+   * \return The writer should return true, if writing succeeded, false otherwise.
+   */
   bool writeScene(const COLLADAFW::Scene *);
 
+  /**
+   * When this method is called, the writer must write the entire visual scene.
+   * Return The writer should return true, if writing succeeded, false otherwise.
+   */
   bool writeVisualScene(const COLLADAFW::VisualScene *);
 
+  /**
+   * When this method is called, the writer must handle all nodes contained in the
+   * library nodes.
+   * \return The writer should return true, if writing succeeded, false otherwise.
+   */
   bool writeLibraryNodes(const COLLADAFW::LibraryNodes *);
 
+  /**
+   * This function is called only for animations that pass COLLADAFW::validate.
+   */
   bool writeAnimation(const COLLADAFW::Animation *);
 
+  /**
+   * Called on post-process stage after writeVisualScenes.
+   */
   bool writeAnimationList(const COLLADAFW::AnimationList *);
 
 #if WITH_OPENCOLLADA_ANIMATION_CLIP
@@ -105,20 +136,49 @@ class DocumentImporter : COLLADAFW::IWriter {
   bool writeAnimationClip(const COLLADAFW::AnimationClip *animationClip);
 #endif
 
+  /**
+   * When this method is called, the writer must write the geometry.
+   * \return The writer should return true, if writing succeeded, false otherwise.
+   */
   bool writeGeometry(const COLLADAFW::Geometry *);
 
+  /**
+   * When this method is called, the writer must write the material.
+   * \return The writer should return true, if writing succeeded, false otherwise.
+   */
   bool writeMaterial(const COLLADAFW::Material *);
 
+  /**
+   * When this method is called, the writer must write the effect.
+   * \return The writer should return true, if writing succeeded, false otherwise.
+   */
   bool writeEffect(const COLLADAFW::Effect *);
 
+  /**
+   * When this method is called, the writer must write the camera.
+   * \return The writer should return true, if writing succeeded, false otherwise.
+   */
   bool writeCamera(const COLLADAFW::Camera *);
 
+  /**
+   * When this method is called, the writer must write the image.
+   * \return The writer should return true, if writing succeeded, false otherwise.
+   */
   bool writeImage(const COLLADAFW::Image *);
 
+  /**
+   * When this method is called, the writer must write the light.
+   * \return The writer should return true, if writing succeeded, false otherwise.
+   */
   bool writeLight(const COLLADAFW::Light *);
 
+  /**
+   * When this method is called, the writer must write the skin controller data.
+   * \return The writer should return true, if writing succeeded, false otherwise.
+   */
   bool writeSkinControllerData(const COLLADAFW::SkinControllerData *);
 
+  /** This is called on post-process, before writeVisualScenes. */
   bool writeController(const COLLADAFW::Controller *);
 
   bool writeFormulas(const COLLADAFW::Formulas *);

source/blender/io/collada/GeometryExporter.cpp

@@ -324,7 +324,6 @@ std::string GeometryExporter::makeVertexColorSourceId(std::string &geom_id, char
   return result;
 }
 
-/* powerful because it handles both cases when there is material and when there's not */
 void GeometryExporter::create_mesh_primitive_list(short material_index,
                                                   bool has_uvs,
                                                   bool has_color,
@@ -441,7 +440,6 @@ void GeometryExporter::create_mesh_primitive_list(short material_index,
   finish_and_delete_primitive_List(is_triangulated, primitive_list);
 }
 
-/* creates <source> for positions */
 void GeometryExporter::createVertsSource(std::string geom_id, Mesh *me)
 {
 #if 0
@@ -542,7 +540,6 @@ std::string GeometryExporter::makeTexcoordSourceId(std::string &geom_id,
   return getIdBySemantics(geom_id, COLLADASW::InputSemantic::TEXCOORD) + suffix;
 }
 
-/* creates <source> for texcoords */
 void GeometryExporter::createTexcoordsSource(std::string geom_id, Mesh *me)
 {
 
@@ -593,7 +590,6 @@ bool operator<(const Normal &a, const Normal &b)
   return a.x < b.x || (a.x == b.x && (a.y < b.y || (a.y == b.y && a.z < b.z)));
 }
 
-/* creates <source> for normals */
 void GeometryExporter::createNormalsSource(std::string geom_id, Mesh *me, std::vector<Normal> &nor)
 {
 #if 0

source/blender/io/collada/GeometryExporter.h

@@ -72,7 +72,7 @@ class GeometryExporter : COLLADASW::LibraryGeometries {
 
   void createLooseEdgeList(Object *ob, Mesh *me, std::string &geom_id);
 
-  /* powerful because it handles both cases when there is material and when there's not */
+  /** Powerful because it handles both cases when there is material and when there's not. */
   void create_mesh_primitive_list(short material_index,
                                   bool has_uvs,
                                   bool has_color,
@@ -81,17 +81,17 @@ class GeometryExporter : COLLADASW::LibraryGeometries {
                                   std::string &geom_id,
                                   std::vector<BCPolygonNormalsIndices> &norind);
 
-  /* creates <source> for positions */
+  /** Creates <source> for positions. */
   void createVertsSource(std::string geom_id, Mesh *me);
 
   void createVertexColorSource(std::string geom_id, Mesh *me);
 
   std::string makeTexcoordSourceId(std::string &geom_id, int layer_index, bool is_single_layer);
 
-  /* creates <source> for texcoords */
+  /** Creates <source> for texcoords. */
   void createTexcoordsSource(std::string geom_id, Mesh *me);
 
-  /* creates <source> for normals */
+  /** Creates <source> for normals. */
   void createNormalsSource(std::string geom_id, Mesh *me, std::vector<Normal> &nor);
 
   void create_normals(std::vector<Normal> &nor,

source/blender/io/collada/Materials.cpp

@@ -91,7 +91,6 @@ void MaterialNode::setShaderType()
 #endif
 }
 
-/* returns null if material already has a node tree */
 bNodeTree *MaterialNode::prepare_material_nodetree()
 {
   if (material->nodetree) {

source/blender/io/collada/Materials.h

@@ -45,6 +45,7 @@ class MaterialNode {
   bNode *shader_node;
   bNode *output_node;
 
+  /** Returns null if material already has a node tree. */
   bNodeTree *prepare_material_nodetree();
   bNode *add_node(int node_type, int locx, int locy, std::string label);
   void add_link(bNode *from_node, int from_index, bNode *to_node, int to_index);

source/blender/io/collada/MeshImporter.cpp

@@ -267,7 +267,6 @@ void MeshImporter::print_index_list(COLLADAFW::IndexList &index_list)
 }
 #endif
 
-/* checks if mesh has supported primitive types: lines, polylist, triangles, triangle_fans */
 bool MeshImporter::is_nice_mesh(COLLADAFW::Mesh *mesh)
 {
   COLLADAFW::MeshPrimitiveArray &prim_arr = mesh->getMeshPrimitives();
@@ -356,12 +355,6 @@ void MeshImporter::read_vertices(COLLADAFW::Mesh *mesh, Mesh *me)
   }
 }
 
-/* =====================================================================
- * condition 1: The Primitive has normals
- * condition 2: The number of normals equals the number of faces.
- * return true if both conditions apply.
- * return false otherwise.
- * ===================================================================== */
 bool MeshImporter::primitive_has_useable_normals(COLLADAFW::MeshPrimitive *mp)
 {
 
@@ -385,10 +378,6 @@ bool MeshImporter::primitive_has_useable_normals(COLLADAFW::MeshPrimitive *mp)
   return has_useable_normals;
 }
 
-/* =====================================================================
- * Assume that only TRIANGLES, TRIANGLE_FANS, POLYLIST and POLYGONS
- * have faces. (to be verified)
- * ===================================================================== */
 bool MeshImporter::primitive_has_faces(COLLADAFW::MeshPrimitive *mp)
 {
 
@@ -420,12 +409,6 @@ static std::string extract_vcolname(const COLLADAFW::String &collada_id)
   return colname;
 }
 
-/* =================================================================
- * Return the number of faces by summing up
- * the face-counts of the parts.
- * hint: This is done because `mesh->getFacesCount()` does
- * count loose edges as extra faces, which is not what we want here.
- * ================================================================= */
 void MeshImporter::allocate_poly_data(COLLADAFW::Mesh *collada_mesh, Mesh *me)
 {
   COLLADAFW::MeshPrimitiveArray &prim_arr = collada_mesh->getMeshPrimitives();
@@ -554,13 +537,6 @@ unsigned int MeshImporter::get_loose_edge_count(COLLADAFW::Mesh *mesh)
   return loose_edge_count;
 }
 
-/* =================================================================
- * This function is copied from source/blender/editors/mesh/mesh_data.c
- *
- * TODO: (As discussed with sergey-) :
- * Maybe move this function to blenderkernel/intern/mesh.c
- * and add definition to BKE_mesh.c
- * ================================================================= */
 void MeshImporter::mesh_add_edges(Mesh *mesh, int len)
 {
   CustomData edata;
@@ -594,12 +570,6 @@ void MeshImporter::mesh_add_edges(Mesh *mesh, int len)
   mesh->totedge = totedge;
 }
 
-/* =================================================================
- * Read all loose edges.
- * Important: This function assumes that all edges from existing
- * faces have already been generated and added to me->medge
- * So this function MUST be called after read_faces() (see below)
- * ================================================================= */
 void MeshImporter::read_lines(COLLADAFW::Mesh *mesh, Mesh *me)
 {
   unsigned int loose_edge_count = get_loose_edge_count(mesh);
@@ -633,13 +603,6 @@ void MeshImporter::read_lines(COLLADAFW::Mesh *mesh, Mesh *me)
   }
 }
 
-/* =======================================================================
- * Read all faces from TRIANGLES, TRIANGLE_FANS, POLYLIST, POLYGON
- * Important: This function MUST be called before read_lines()
- * Otherwise we will lose all edges from faces (see read_lines() above)
- *
- * TODO: import uv set names
- * ======================================================================== */
 void MeshImporter::read_polys(COLLADAFW::Mesh *collada_mesh, Mesh *me)
 {
   unsigned int i;
@@ -965,11 +928,6 @@ static void bc_remove_materials_from_object(Object *ob, Mesh *me)
   }
 }
 
-/**
- * Returns the list of Users of the given Mesh object.
- * NOTE: This function uses the object user flag to control
- * which objects have already been processed.
- */
 std::vector<Object *> MeshImporter::get_all_users_of(Mesh *reference_mesh)
 {
   std::vector<Object *> mesh_users;
@@ -985,24 +943,6 @@ std::vector<Object *> MeshImporter::get_all_users_of(Mesh *reference_mesh)
   return mesh_users;
 }
 
-/**
- *
- * During import all materials have been assigned to Object.
- * Now we iterate over the imported objects and optimize
- * the assignments as follows:
- *
- * for each imported geometry:
- *     if number of users is 1:
- *         get the user (object)
- *         move the materials from Object to Data
- *     else:
- *         determine which materials are assigned to the first user
- *         check if all other users have the same materials in the same order
- *         if the check is positive:
- *             Add the materials of the first user to the geometry
- *             adjust all other users accordingly.
- *
- */
 void MeshImporter::optimize_material_assignements()
 {
   for (Object *ob : imported_objects) {
@@ -1035,14 +975,6 @@ void MeshImporter::optimize_material_assignements()
   }
 }
 
-/**
- * We do not know in advance which objects will share geometries.
- * And we do not know either if the objects which share geometries
- * come along with different materials. So we first create the objects
- * and assign the materials to Object, then in a later cleanup we decide
- * which materials shall be moved to the created geometries. Also see
- * optimize_material_assignements() above.
- */
 void MeshImporter::assign_material_to_geom(
     COLLADAFW::MaterialBinding cmaterial,
     std::map<COLLADAFW::UniqueId, Material *> &uid_material_map,
@@ -1165,7 +1097,6 @@ Object *MeshImporter::create_mesh_object(
   return ob;
 }
 
-/* create a mesh storing a pointer in a map so it can be retrieved later by geometry UID */
 bool MeshImporter::write_geometry(const COLLADAFW::Geometry *geom)
 {
 

source/blender/io/collada/MeshImporter.h

@@ -122,23 +122,60 @@ class MeshImporter : public MeshImporterBase {
   void print_index_list(COLLADAFW::IndexList &index_list);
 #endif
 
+  /** Checks if mesh has supported primitive types: lines, polylist, triangles, triangle_fans. */
   bool is_nice_mesh(COLLADAFW::Mesh *mesh);
 
   void read_vertices(COLLADAFW::Mesh *mesh, Mesh *me);
 
+  /**
+   * Condition 1: The Primitive has normals
+   * condition 2: The number of normals equals the number of faces.
+   * return true if both conditions apply.
+   * return false otherwise.
+   */
   bool primitive_has_useable_normals(COLLADAFW::MeshPrimitive *mp);
+  /**
+   * Assume that only TRIANGLES, TRIANGLE_FANS, POLYLIST and POLYGONS
+   * have faces. (to be verified).
+   */
   bool primitive_has_faces(COLLADAFW::MeshPrimitive *mp);
 
+  /**
+   * This function is copied from source/blender/editors/mesh/mesh_data.c
+   *
+   * TODO: (As discussed with sergey-) :
+   * Maybe move this function to blenderkernel/intern/mesh.c
+   * and add definition to BKE_mesh.c.
+   */
   static void mesh_add_edges(Mesh *mesh, int len);
 
   unsigned int get_loose_edge_count(COLLADAFW::Mesh *mesh);
 
   CustomData create_edge_custom_data(EdgeHash *eh);
 
+  /**
+   * Return the number of faces by summing up
+   * the face-counts of the parts.
+   * hint: This is done because `mesh->getFacesCount()` does
+   * count loose edges as extra faces, which is not what we want here.
+   */
   void allocate_poly_data(COLLADAFW::Mesh *collada_mesh, Mesh *me);
 
   /* TODO: import uv set names */
+  /**
+   * Read all faces from TRIANGLES, TRIANGLE_FANS, POLYLIST, POLYGON
+   * Important: This function MUST be called before read_lines()
+   * Otherwise we will lose all edges from faces (see read_lines() above)
+   *
+   * TODO: import uv set names.
+   */
   void read_polys(COLLADAFW::Mesh *mesh, Mesh *me);
+  /**
+   * Read all loose edges.
+   * Important: This function assumes that all edges from existing
+   * faces have already been generated and added to me->medge
+   * So this function MUST be called after read_faces() (see below)
+   */
   void read_lines(COLLADAFW::Mesh *mesh, Mesh *me);
   unsigned int get_vertex_count(COLLADAFW::Polygons *mp, int index);
 
@@ -146,6 +183,11 @@ class MeshImporter : public MeshImporterBase {
 
   bool is_flat_face(unsigned int *nind, COLLADAFW::MeshVertexData &nor, int count);
 
+  /**
+   * Returns the list of Users of the given Mesh object.
+   * NOTE: This function uses the object user flag to control
+   * which objects have already been processed.
+   */
   std::vector<Object *> get_all_users_of(Mesh *reference_mesh);
 
  public:
@@ -159,8 +201,34 @@ class MeshImporter : public MeshImporterBase {
 
   virtual Mesh *get_mesh_by_geom_uid(const COLLADAFW::UniqueId &geom_uid);
 
+  /**
+   *
+   * During import all materials have been assigned to Object.
+   * Now we iterate over the imported objects and optimize
+   * the assignments as follows:
+   *
+   * for each imported geometry:
+   *     if number of users is 1:
+   *         get the user (object)
+   *         move the materials from Object to Data
+   *     else:
+   *         determine which materials are assigned to the first user
+   *         check if all other users have the same materials in the same order
+   *         if the check is positive:
+   *             Add the materials of the first user to the geometry
+   *             adjust all other users accordingly.
+   *
+   */
   void optimize_material_assignements();
 
+  /**
+   * We do not know in advance which objects will share geometries.
+   * And we do not know either if the objects which share geometries
+   * come along with different materials. So we first create the objects
+   * and assign the materials to Object, then in a later cleanup we decide
+   * which materials shall be moved to the created geometries. Also see
+   * optimize_material_assignements() above.
+   */
   void assign_material_to_geom(COLLADAFW::MaterialBinding cmaterial,
                                std::map<COLLADAFW::UniqueId, Material *> &uid_material_map,
                                Object *ob,
@@ -172,7 +240,7 @@ class MeshImporter : public MeshImporterBase {
                              bool isController,
                              std::map<COLLADAFW::UniqueId, Material *> &uid_material_map);
 
-  /* create a mesh storing a pointer in a map so it can be retrieved later by geometry UID */
+  /** Create a mesh storing a pointer in a map so it can be retrieved later by geometry UID. */
   bool write_geometry(const COLLADAFW::Geometry *geom);
   std::string *get_geometry_name(const std::string &mesh_name);
 };

source/blender/io/collada/SkinInfo.cpp

@@ -53,9 +53,6 @@ template<class T> static const char *bc_get_joint_name(T *node)
   return id.empty() ? node->getOriginalId().c_str() : id.c_str();
 }
 
-/* This is used to store data passed in write_controller_data.
- * Arrays from COLLADAFW::SkinControllerData lose ownership, so do this class members
- * so that arrays don't get freed until we free them explicitly. */
 SkinInfo::SkinInfo() = default;
 
 SkinInfo::SkinInfo(const SkinInfo &skin)
@@ -77,7 +74,6 @@ SkinInfo::SkinInfo(UnitConverter *conv) : unit_converter(conv), ob_arm(nullptr),
 {
 }
 
-/* nobody owns the data after this, so it should be freed manually with releaseMemory */
 template<class T> void SkinInfo::transfer_array_data(T &src, T &dest)
 {
   dest.setData(src.getData(), src.getCount());
@@ -85,7 +81,6 @@ template<class T> void SkinInfo::transfer_array_data(T &src, T &dest)
   dest.yieldOwnerShip();
 }
 
-/* when src is const we cannot src.yieldOwnerShip, this is used by copy constructor */
 void SkinInfo::transfer_int_array_data_const(const COLLADAFW::IntValuesArray &src,
                                              COLLADAFW::IntValuesArray &dest)
 {
@@ -124,9 +119,6 @@ void SkinInfo::free()
   // weights.releaseMemory();
 }
 
-/* using inverse bind matrices to construct armature
- * it is safe to invert them to get the original matrices
- * because if they are inverse matrices, they can be inverted */
 void SkinInfo::add_joint(const COLLADABU::Math::Matrix4 &matrix)
 {
   JointData jd;
@@ -152,7 +144,6 @@ void SkinInfo::set_controller(const COLLADAFW::SkinController *co)
   }
 }
 
-/* called from write_controller */
 Object *SkinInfo::create_armature(Main *bmain, Scene *scene, ViewLayer *view_layer)
 {
   ob_arm = bc_add_object(bmain, scene, view_layer, OB_ARMATURE, nullptr);
@@ -193,11 +184,6 @@ const COLLADAFW::UniqueId &SkinInfo::get_controller_uid()
   return controller_uid;
 }
 
-/* check if this skin controller references a joint or any descendant of it
- *
- * some nodes may not be referenced by SkinController,
- * in this case to determine if the node belongs to this armature,
- * we need to search down the tree */
 bool SkinInfo::uses_joint_or_descendant(COLLADAFW::Node *node)
 {
   const COLLADAFW::UniqueId &uid = node->getUniqueId();

source/blender/io/collada/SkinInfo.h

@@ -35,9 +35,11 @@
 #include "TransformReader.h"
 #include "collada_internal.h"
 
-/* This is used to store data passed in write_controller_data.
+/**
- * Arrays from COLLADAFW::SkinControllerData lose ownership, so do this class members
+ * This is used to store data passed in write_controller_data.
- * so that arrays don't get freed until we free them explicitly. */
+ * Arrays from #COLLADAFW::SkinControllerData lose ownership, so do this class members
+ * so that arrays don't get freed until we free them explicitly.
+ */
 class SkinInfo {
  private:
   /* to build armature bones from inverse bind matrices */
@@ -69,10 +71,10 @@ class SkinInfo {
   SkinInfo(const SkinInfo &skin);
   SkinInfo(UnitConverter *conv);
 
-  /* nobody owns the data after this, so it should be freed manually with releaseMemory */
+  /** Nobody owns the data after this, so it should be freed manually with releaseMemory. */
   template<typename T> void transfer_array_data(T &src, T &dest);
 
-  /* when src is const we cannot src.yieldOwnerShip, this is used by copy constructor */
+  /** When src is const we cannot `src.yieldOwnerShip`, this is used by copy constructor. */
   void transfer_int_array_data_const(const COLLADAFW::IntValuesArray &src,
                                      COLLADAFW::IntValuesArray &dest);
 
@@ -83,14 +85,16 @@ class SkinInfo {
 
   void free();
 
-  /* using inverse bind matrices to construct armature
+  /**
+   * Using inverse bind matrices to construct armature
    * it is safe to invert them to get the original matrices
-   * because if they are inverse matrices, they can be inverted */
+   * because if they are inverse matrices, they can be inverted.
+   */
   void add_joint(const COLLADABU::Math::Matrix4 &matrix);
 
   void set_controller(const COLLADAFW::SkinController *co);
 
-  /* called from write_controller */
+  /** Called from write_controller. */
   Object *create_armature(Main *bmain, Scene *scene, ViewLayer *view_layer);
 
   Object *set_armature(Object *ob_arm);
@@ -101,11 +105,13 @@ class SkinInfo {
 
   const COLLADAFW::UniqueId &get_controller_uid();
 
-  /* check if this skin controller references a joint or any descendant of it
+  /**
+   * Check if this skin controller references a joint or any descendant of it
    *
    * some nodes may not be referenced by SkinController,
    * in this case to determine if the node belongs to this armature,
-   * we need to search down the tree */
+   * we need to search down the tree.
+   */
   bool uses_joint_or_descendant(COLLADAFW::Node *node);
 
   void link_armature(bContext *C,

source/blender/io/collada/collada_internal.cpp

@@ -213,7 +213,6 @@ void clear_global_id_map()
   global_id_map.clear();
 }
 
-/** Look at documentation of translate_map */
 std::string translate_id(const char *idString)
 {
   std::string id = std::string(idString);

source/blender/io/collada/collada_internal.h

@@ -76,6 +76,7 @@ class UnitConverter {
 extern void clear_global_id_map();
 /** Look at documentation of translate_map */
 extern std::string translate_id(const std::string &id);
+/** Look at documentation of translate_map */
 extern std::string translate_id(const char *idString);
 
 extern std::string id_name(void *id);

source/blender/io/collada/collada_utils.cpp

@@ -92,9 +92,10 @@ float bc_get_float_value(const COLLADAFW::FloatOrDoubleArray &array, unsigned in
   return array.getDoubleValues()->getData()[index];
 }
 
-/* copied from /editors/object/object_relations.c */
 int bc_test_parent_loop(Object *par, Object *ob)
 {
+  /* Copied from /editors/object/object_relations.c */
+
   /* test if 'ob' is a parent somewhere in par's parents */
 
   if (par == nullptr) {
@@ -289,9 +290,10 @@ bool bc_has_object_type(LinkNode *export_set, short obtype)
   return false;
 }
 
-/* Use bubble sort algorithm for sorting the export set */
 void bc_bubble_sort_by_Object_name(LinkNode *export_set)
 {
+  /* Use bubble sort algorithm for sorting the export set. */
+
   bool sorted = false;
   LinkNode *node;
   for (node = export_set; node->next && !sorted; node = node->next) {
@@ -312,11 +314,6 @@ void bc_bubble_sort_by_Object_name(LinkNode *export_set)
   }
 }
 
-/* Check if a bone is the top most exportable bone in the bone hierarchy.
- * When deform_bones_only == false, then only bones with NO parent
- * can be root bones. Otherwise the top most deform bones in the hierarchy
- * are root bones.
- */
 bool bc_is_root_bone(Bone *aBone, bool deform_bones_only)
 {
   if (deform_bones_only) {
@@ -386,9 +383,6 @@ void bc_match_scale(std::vector<Object *> *objects_done,
   }
 }
 
-/*
- * Convenience function to get only the needed components of a matrix
- */
 void bc_decompose(float mat[4][4], float *loc, float eul[3], float quat[4], float *size)
 {
   if (size) {
@@ -408,17 +402,6 @@ void bc_decompose(float mat[4][4], float *loc, float eul[3], float quat[4], floa
   }
 }
 
-/*
- * Create rotation_quaternion from a delta rotation and a reference quat
- *
- * Input:
- * mat_from: The rotation matrix before rotation
- * mat_to  : The rotation matrix after rotation
- * qref    : the quat corresponding to mat_from
- *
- * Output:
- * rot     : the calculated result (quaternion)
- */
 void bc_rotate_from_reference_quat(float quat_to[4], float quat_from[4], float mat_to[4][4])
 {
   float qd[4];
@@ -457,9 +440,6 @@ void bc_triangulate_mesh(Mesh *me)
   BM_mesh_free(bm);
 }
 
-/*
- * A bone is a leaf when it has no children or all children are not connected.
- */
 bool bc_is_leaf_bone(Bone *bone)
 {
   for (Bone *child = (Bone *)bone->childbase.first; child; child = child->next) {
@@ -501,11 +481,6 @@ int bc_set_layer(int bitfield, int layer, bool enable)
   return bitfield;
 }
 
-/**
- * This method creates a new extension map when needed.
- * \note The ~BoneExtensionManager destructor takes care
- * to delete the created maps when the manager is removed.
- */
 BoneExtensionMap &BoneExtensionManager::getExtensionMap(bArmature *armature)
 {
   std::string key = armature->id.name;
@@ -697,9 +672,6 @@ int BoneExtended::get_use_connect()
   return this->use_connect;
 }
 
-/**
- * Stores a 4*4 matrix as a custom bone property array of size 16
- */
 void bc_set_IDPropertyMatrix(EditBone *ebone, const char *key, float mat[4][4])
 {
   IDProperty *idgroup = (IDProperty *)ebone->prop;
@@ -745,19 +717,11 @@ static void bc_set_IDProperty(EditBone *ebone, const char *key, float value)
 }
 #endif
 
-/**
- * Get a custom property when it exists.
- * This function is also used to check if a property exists.
- */
 IDProperty *bc_get_IDProperty(Bone *bone, std::string key)
 {
   return (bone->prop == nullptr) ? nullptr : IDP_GetPropertyFromGroup(bone->prop, key.c_str());
 }
 
-/**
- * Read a custom bone property and convert to float
- * Return def if the property does not exist.
- */
 float bc_get_property(Bone *bone, std::string key, float def)
 {
   float result = def;
@@ -780,14 +744,6 @@ float bc_get_property(Bone *bone, std::string key, float def)
   return result;
 }
 
-/**
- * Read a custom bone property and convert to matrix
- * Return true if conversion was successful
- *
- * Return false if:
- * - the property does not exist
- * - is not an array of size 16
- */
 bool bc_get_property_matrix(Bone *bone, std::string key, float mat[4][4])
 {
   IDProperty *property = bc_get_IDProperty(bone, key);
@@ -803,9 +759,6 @@ bool bc_get_property_matrix(Bone *bone, std::string key, float mat[4][4])
   return false;
 }
 
-/**
- * get a vector that is stored in 3 custom properties (used in Blender <= 2.78)
- */
 void bc_get_property_vector(Bone *bone, std::string key, float val[3], const float def[3])
 {
   val[0] = bc_get_property(bone, key + "_x", def[0]);
@@ -1014,12 +967,6 @@ void bc_apply_global_transform(Vector &to_vec, const BCMatrix &global_transform,
   mul_v3_m4v3(to_vec, transform, to_vec);
 }
 
-/**
- * Check if custom information about bind matrix exists and modify the from_mat
- * accordingly.
- *
- * NOTE: This is old style for Blender <= 2.78 only kept for compatibility
- */
 void bc_create_restpose_mat(BCExportSettings &export_settings,
                             Bone *bone,
                             float to_mat[4][4],

source/blender/io/collada/collada_utils.h

@@ -143,6 +143,12 @@ extern char *bc_CustomData_get_layer_name(const CustomData *data, int type, int
 extern char *bc_CustomData_get_active_layer_name(const CustomData *data, int type);
 
 extern void bc_bubble_sort_by_Object_name(LinkNode *export_set);
+/**
+ * Check if a bone is the top most exportable bone in the bone hierarchy.
+ * When deform_bones_only == false, then only bones with NO parent
+ * can be root bones. Otherwise the top most deform bones in the hierarchy
+ * are root bones.
+ */
 extern bool bc_is_root_bone(Bone *aBone, bool deform_bones_only);
 extern int bc_get_active_UVLayer(Object *ob);
 
@@ -200,12 +206,29 @@ extern void bc_match_scale(std::vector<Object *> *objects_done,
                            UnitConverter &bc_unit,
                            bool scale_to_scene);
 
+/**
+ * Convenience function to get only the needed components of a matrix.
+ */
 extern void bc_decompose(float mat[4][4], float *loc, float eul[3], float quat[4], float *size);
+/**
+ * Create rotation_quaternion from a delta rotation and a reference quat
+ *
+ * Input:
+ * mat_from: The rotation matrix before rotation
+ * mat_to  : The rotation matrix after rotation
+ * qref    : the quat corresponding to mat_from
+ *
+ * Output:
+ * rot     : the calculated result (quaternion).
+ */
 extern void bc_rotate_from_reference_quat(float quat_to[4],
                                           float quat_from[4],
                                           float mat_to[4][4]);
 
 extern void bc_triangulate_mesh(Mesh *me);
+/**
+ * A bone is a leaf when it has no children or all children are not connected.
+ */
 extern bool bc_is_leaf_bone(Bone *bone);
 extern EditBone *bc_get_edit_bone(bArmature *armature, char *name);
 extern int bc_set_layer(int bitfield, int layer, bool enable);
@@ -224,12 +247,34 @@ void bc_copy_v44_m4d(std::vector<std::vector<double>> &r, double (&a)[4][4]);
 void bc_sanitize_v3(double v[3], int precision);
 void bc_sanitize_v3(float v[3], int precision);
 
+/**
+ * Get a custom property when it exists.
+ * This function is also used to check if a property exists.
+ */
 extern IDProperty *bc_get_IDProperty(Bone *bone, std::string key);
 extern void bc_set_IDProperty(EditBone *ebone, const char *key, float value);
+/**
+ * Stores a 4*4 matrix as a custom bone property array of size 16.
+ */
 extern void bc_set_IDPropertyMatrix(EditBone *ebone, const char *key, float mat[4][4]);
 
+/**
+ * Read a custom bone property and convert to float
+ * Return def if the property does not exist.
+ */
 extern float bc_get_property(Bone *bone, std::string key, float def);
+/**
+ * Get a vector that is stored in 3 custom properties (used in Blender <= 2.78).
+ */
 extern void bc_get_property_vector(Bone *bone, std::string key, float val[3], const float def[3]);
+/**
+ * Read a custom bone property and convert to matrix
+ * Return true if conversion was successful
+ *
+ * Return false if:
+ * - the property does not exist
+ * - is not an array of size 16
+ */
 extern bool bc_get_property_matrix(Bone *bone, std::string key, float mat[4][4]);
 
 extern void bc_enable_fcurves(bAction *act, char *bone_name);
@@ -258,6 +303,12 @@ extern void bc_apply_global_transform(Matrix &to_mat,
 extern void bc_apply_global_transform(Vector &to_vec,
                                       const BCMatrix &global_transform,
                                       const bool invert = false);
+/**
+ * Check if custom information about bind matrix exists and modify the from_mat
+ * accordingly.
+ *
+ * \note This is old style for Blender <= 2.78 only kept for compatibility.
+ */
 extern void bc_create_restpose_mat(BCExportSettings &export_settings,
                                    Bone *bone,
                                    float to_mat[4][4],
@@ -364,6 +415,11 @@ class BoneExtensionManager {
   std::map<std::string, BoneExtensionMap *> extended_bone_maps;
 
  public:
+  /**
+   * This method creates a new extension map when needed.
+   * \note The ~BoneExtensionManager destructor takes care
+   * to delete the created maps when the manager is removed.
+   */
   BoneExtensionMap &getExtensionMap(bArmature *armature);
   ~BoneExtensionManager();
 };