Cleanup: use doxy comments in object.c

1 files changed, 81 insertions, 42 deletions

diff --git a/source/blender/blenkernel/intern/object.c b/source/blender/blenkernel/intern/object.c
index 5afad6a294b..69b4f68bc33 100644
--- a/source/blender/blenkernel/intern/object.c
+++ b/source/blender/blenkernel/intern/object.c
@@ -143,7 +143,8 @@
 
 static CLG_LogRef LOG = {"bke.object"};
 
-/* Vertex parent modifies original BMesh which is not safe for threading.
+/**
+ * Vertex parent modifies original BMesh which is not safe for threading.
  * Ideally such a modification should be handled as a separate DAG update
  * callback for mesh datablock, but for until it is actually supported use
  * simpler solution with a mutex lock.
@@ -753,8 +754,8 @@ void BKE_object_link_modifiers(struct Object *ob_dst, const struct Object *ob_sr
   /* TODO: smoke?, cloth? */
 }
 
-/* Copy CCG related data. Used to sync copy of mesh with reshaped original
- * mesh.
+/**
+ * Copy CCG related data. Used to sync copy of mesh with reshaped original mesh.
  */
 static void copy_ccg_data(Mesh *mesh_destination, Mesh *mesh_source, int layer_type)
 {
@@ -844,7 +845,9 @@ static void object_update_from_subsurf_ccg(Object *object)
   subdiv_ccg->dirty.hidden = false;
 }
 
-/* Assign data after modifier stack evaluation. */
+/**
+ * Assign #Object.data after modifier stack evaluation.
+ */
 void BKE_object_eval_assign_data(Object *object_eval, ID *data_eval, bool is_owned)
 {
   BLI_assert(object_eval->id.tag & LIB_TAG_COPIED_ON_WRITE);
@@ -871,7 +874,9 @@ void BKE_object_eval_assign_data(Object *object_eval, ID *data_eval, bool is_own
   }
 }
 
-/* free data derived from mesh, called when mesh changes or is freed */
+/**
+ * Free data derived from mesh, called when mesh changes or is freed.
+ */
 void BKE_object_free_derived_caches(Object *ob)
 {
   MEM_SAFE_FREE(ob->runtime.bb);
@@ -962,7 +967,9 @@ void BKE_object_free_caches(Object *object)
   }
 }
 
-/* actual check for internal data, not context or flags */
+/**
+ * Actual check for internal data, not context or flags.
+ */
 bool BKE_object_is_in_editmode(const Object *ob)
 {
   if (ob->data == NULL) {
@@ -1312,7 +1319,9 @@ int BKE_object_obdata_to_type(const ID *id)
   }
 }
 
-/* more general add: creates minimum required data, but without vertices etc. */
+/**
+ * More general add: creates minimum required data, but without vertices etc.
+ */
 Object *BKE_object_add_only_object(Main *bmain, int type, const char *name)
 {
   Object *ob;
@@ -1348,10 +1357,11 @@ static Object *object_add_common(Main *bmain, ViewLayer *view_layer, int type, c
 /**
  * General add: to scene, with layer from area and default name
  *
- * Object is added to the active Collection.
- * If there is no linked collection to the active ViewLayer we create a new one.
+ * Object is added to the active #Collection.
+ * If there is no linked collection to the active #ViewLayer we create a new one.
+ *
+ * \note Creates minimum required data, but without vertices etc.
  */
-/* creates minimum required data, but without vertices etc. */
 Object *BKE_object_add(Main *bmain, ViewLayer *view_layer, int type, const char *name)
 {
   Object *ob;
@@ -1759,7 +1769,9 @@ void BKE_object_transform_copy(Object *ob_tar, const Object *ob_src)
   copy_v3_v3(ob_tar->scale, ob_src->scale);
 }
 
-/* copy objects, will re-initialize cached simulation data */
+/**
+ * Copy objects, will re-initialize cached simulation data.
+ */
 Object *BKE_object_copy(Main *bmain, const Object *ob)
 {
   Object *ob_copy;
@@ -1954,13 +1966,17 @@ Object *BKE_object_duplicate(Main *bmain,
   return obn;
 }
 
-/* Returns true if the Object is from an external blend file (libdata) */
+/**
+ * Returns true if the Object is from an external blend file (libdata).
+ */
 bool BKE_object_is_libdata(const Object *ob)
 {
   return (ob && ID_IS_LINKED(ob));
 }
 
-/* Returns true if the Object data is from an external blend file (libdata) */
+/**
+ * Returns true if the Object data is from an external blend file (libdata).
+ */
 bool BKE_object_obdata_is_libdata(const Object *ob)
 {
   /* Linked objects with local obdata are forbidden! */
@@ -2726,7 +2742,9 @@ static void solve_parenting(
   }
 }
 
-/* note, scene is the active scene while actual_scene is the scene the object resides in */
+/**
+ * \note scene is the active scene while actual_scene is the scene the object resides in.
+ */
 static void object_where_is_calc_ex(Depsgraph *depsgraph,
                                     Scene *scene,
                                     Object *ob,
@@ -2777,10 +2795,12 @@ void BKE_object_where_is_calc_time(Depsgraph *depsgraph, Scene *scene, Object *o
   object_where_is_calc_ex(depsgraph, scene, ob, ctime, NULL, NULL);
 }
 
-/* get object transformation matrix without recalculating dependencies and
+/**
+ * Calculate object transformation matrix without recalculating dependencies and
  * constraints -- assume dependencies are already solved by depsgraph.
- * no changes to object and it's parent would be done.
- * used for bundles orientation in 3d space relative to parented blender camera */
+ * No changes to object and it's parent would be done.
+ * Used for bundles orientation in 3d space relative to parented blender camera.
+ */
 void BKE_object_where_is_calc_mat4(Object *ob, float r_obmat[4][4])
 {
   if (ob->parent) {
@@ -2892,7 +2912,9 @@ void BKE_object_apply_mat4_ex(Object *ob,
   /* BKE_object_mat3_to_rot handles delta rotations */
 }
 
-/* XXX: should be removed after COW operators port to use BKE_object_apply_mat4_ex directly */
+/**
+ * XXX: should be removed after COW operators port to use BKE_object_apply_mat4_ex directly.
+ */
 void BKE_object_apply_mat4(Object *ob,
                            const float mat[4][4],
                            const bool use_compat,
@@ -2997,7 +3019,9 @@ BoundBox *BKE_object_boundbox_get(Object *ob)
   return bb;
 }
 
-/* used to temporally disable/enable boundbox */
+/**
+ * Use this to temporally disable/enable bound-box.
+ */
 void BKE_object_boundbox_flag(Object *ob, int flag, const bool set)
 {
   BoundBox *bb = BKE_object_boundbox_get(ob);
@@ -3368,7 +3392,9 @@ void BKE_scene_foreach_display_point(Depsgraph *depsgraph,
   DEG_OBJECT_ITER_END;
 }
 
-/* copied from DNA_object_types.h */
+/**
+ * Struct members from DNA_object_types.h
+ */
 typedef struct ObTfmBack {
   float loc[3], dloc[3];
   /** scale and delta scale. */
@@ -3609,9 +3635,10 @@ Mesh *BKE_object_get_evaluated_mesh(Object *object)
   return (data_eval && GS(data_eval->name) == ID_ME) ? (Mesh *)data_eval : NULL;
 }
 
-/* Get mesh which is not affected by modifiers:
- * - For original objects it will be same as object->data, and it is a mesh
- *   which is in the corresponding bmain.
+/**
+ * Get mesh which is not affected by modifiers:
+ * - For original objects it will be same as `object->data`, and it is a mesh
+ *   which is in the corresponding #Main.
  * - For copied-on-write objects it will give pointer to a copied-on-write
  *   mesh which corresponds to original object's mesh.
  */
@@ -3630,7 +3657,8 @@ Mesh *BKE_object_get_pre_modified_mesh(Object *object)
   return object->data;
 }
 
-/* Get a mesh which corresponds to very very original mesh from bmain.
+/**
+ * Get a mesh which corresponds to very very original mesh from #Main.
  * - For original objects it will be object->data.
  * - For evaluated objects it will be same mesh as corresponding original
  *   object uses as data.
@@ -3717,7 +3745,7 @@ void BKE_object_delete_ptcache(Object *ob, int index)
 /** \name Object Data Shape Key Insert
  * \{ */
 
-/* Mesh */
+/** Mesh */
 static KeyBlock *insert_meshkey(Main *bmain, Object *ob, const char *name, const bool from_mix)
 {
   Mesh *me = ob->data;
@@ -3749,7 +3777,7 @@ static KeyBlock *insert_meshkey(Main *bmain, Object *ob, const char *name, const
 
   return kb;
 }
-/* Lattice */
+/** Lattice */
 static KeyBlock *insert_lattkey(Main *bmain, Object *ob, const char *name, const bool from_mix)
 {
   Lattice *lt = ob->data;
@@ -3787,7 +3815,7 @@ static KeyBlock *insert_lattkey(Main *bmain, Object *ob, const char *name, const
 
   return kb;
 }
-/* Curve */
+/** Curve */
 static KeyBlock *insert_curvekey(Main *bmain, Object *ob, const char *name, const bool from_mix)
 {
   Curve *cu = ob->data;
@@ -3955,8 +3983,10 @@ bool BKE_object_is_child_recursive(const Object *ob_parent, const Object *ob_chi
   return false;
 }
 
-/* most important if this is modified it should _always_ return True, in certain
- * cases false positives are hard to avoid (shape keys for example) */
+/**
+ * Most important if this is modified it should _always_ return true, in certain
+ * cases false positives are hard to avoid (shape keys for example).
+ */
 int BKE_object_is_modified(Scene *scene, Object *ob)
 {
   /* Always test on original object since evaluated object may no longer
@@ -4093,9 +4123,11 @@ static bool modifiers_has_animation_check(const Object *ob)
   return false;
 }
 
-/* test if object is affected by deforming modifiers (for motion blur). again
+/**
+ * Test if object is affected by deforming modifiers (for motion blur). again
  * most important is to avoid false positives, this is to skip computations
- * and we can still if there was actual deformation afterwards */
+ * and we can still if there was actual deformation afterwards.
+ */
 int BKE_object_is_deform_modified(Scene *scene, Object *ob)
 {
   /* Always test on original object since evaluated object may no longer
@@ -4190,7 +4222,9 @@ void BKE_object_runtime_reset(Object *object)
   memset(&object->runtime, 0, sizeof(object->runtime));
 }
 
-/* Reset all pointers which we don't want to be shared when copying the object. */
+/**
+ * Reset all pointers which we don't want to be shared when copying the object.
+ */
 void BKE_object_runtime_reset_on_copy(Object *object, const int UNUSED(flag))
 {
   Object_Runtime *runtime = &object->runtime;
@@ -4199,8 +4233,8 @@ void BKE_object_runtime_reset_on_copy(Object *object, const int UNUSED(flag))
   runtime->curve_cache = NULL;
 }
 
-/*
- * Find an associated Armature object
+/**
+ * Find an associated armature object.
  */
 static Object *obrel_armature_find(Object *ob)
 {
@@ -4232,12 +4266,12 @@ static void obrel_list_add(LinkNode **links, Object *ob)
   ob->id.tag |= LIB_TAG_DOIT;
 }
 
-/*
+/**
  * Iterates over all objects of the given scene layer.
- * Depending on the eObjectSet flag:
- * collect either OB_SET_ALL, OB_SET_VISIBLE or OB_SET_SELECTED objects.
- * If OB_SET_VISIBLE or OB_SET_SELECTED are collected,
- * then also add related objects according to the given includeFilters.
+ * Depending on the #eObjectSet flag:
+ * collect either #OB_SET_ALL, #OB_SET_VISIBLE or #OB_SET_SELECTED objects.
+ * If #OB_SET_VISIBLE or#OB_SET_SELECTED are collected,
+ * then also add related objects according to the given \a includeFilter.
  */
 LinkNode *BKE_object_relational_superset(struct ViewLayer *view_layer,
                                          eObjectSet objectSet,
@@ -4582,7 +4616,9 @@ bool BKE_object_shaderfx_use_time(Object *ob, ShaderFxData *fx)
   return false;
 }
 
-/* set "ignore cache" flag for all caches on this object */
+/**
+ * Set "ignore cache" flag for all caches on this object.
+ */
 static void object_cacheIgnoreClear(Object *ob, int state)
 {
   ListBase pidlist;
@@ -4603,7 +4639,8 @@ static void object_cacheIgnoreClear(Object *ob, int state)
   BLI_freelistN(&pidlist);
 }
 
-/* Note: this function should eventually be replaced by depsgraph functionality.
+/**
+ * \note this function should eventually be replaced by depsgraph functionality.
  * Avoid calling this in new code unless there is a very good reason for it!
  */
 bool BKE_object_modifier_update_subframe(Depsgraph *depsgraph,
@@ -4711,7 +4748,9 @@ bool BKE_object_modifier_update_subframe(Depsgraph *depsgraph,
   return false;
 }
 
-/* Updates select_id of all objects in the given bmain. */
+/**
+ * Updates select_id of all objects in the given \a bmain.
+ */
 void BKE_object_update_select_id(struct Main *bmain)
 {
   Object *ob = bmain->objects.first;