Cleanup: doxy comments

Use doxy references to function and enums,
also correct some names which became out of sync.

13 files changed, 72 insertions, 47 deletions

diff --git a/source/blender/blenkernel/BKE_blender_version.h b/source/blender/blenkernel/BKE_blender_version.h
index 9c47cc9f22b..1b56e203947 100644
--- a/source/blender/blenkernel/BKE_blender_version.h
+++ b/source/blender/blenkernel/BKE_blender_version.h
@@ -20,21 +20,25 @@
  * \ingroup bke
  */
 
-/* these lines are grep'd, watch out for our not-so-awesome regex
- * and keep comment above the defines.
- * Use STRINGIFY() rather than defining with quotes */
+/**
+ * The lines below use regex from scripts to extract their values,
+ * Keep this in mind when modifying this file and keep this comment above the defines.
+ *
+ * \note Use #STRINGIFY() rather than defining with quotes.
+ */
 #define BLENDER_VERSION         280
 #define BLENDER_SUBVERSION      55
-/* Several breakages with 280, e.g. collections vs layers */
+/** Several breakages with 280, e.g. collections vs layers. */
 #define BLENDER_MINVERSION      280
 #define BLENDER_MINSUBVERSION   0
 
-/* used by packaging tools */
-/* can be left blank, otherwise a,b,c... etc with no quotes */
+/** Used by packaging tools. */
+/** Can be left blank, otherwise a,b,c... etc with no quotes. */
 #define BLENDER_VERSION_CHAR
-/* alpha/beta/rc/release, docs use this */
+/** alpha/beta/rc/release, docs use this. */
 #define BLENDER_VERSION_CYCLE   beta
 
-extern char versionstr[]; /* from blender.c */
+/** Defined in from blender.c */
+extern char versionstr[];
 
 #endif  /* __BKE_BLENDER_VERSION_H__ */
diff --git a/source/blender/blenkernel/intern/armature.c b/source/blender/blenkernel/intern/armature.c
index 5123b159440..890a62351c1 100644
--- a/source/blender/blenkernel/intern/armature.c
+++ b/source/blender/blenkernel/intern/armature.c
@@ -1714,7 +1714,9 @@ void BKE_armature_mat_pose_to_bone_ex(struct Depsgraph *depsgraph, Object *ob, b
 	BKE_armature_mat_pose_to_bone(&work_pchan, inmat, outmat);
 }
 
-/* same as BKE_object_mat3_to_rot() */
+/**
+ * Same as #BKE_object_mat3_to_rot().
+ */
 void BKE_pchan_mat3_to_rot(bPoseChannel *pchan, float mat[3][3], bool use_compat)
 {
 	BLI_ASSERT_UNIT_M3(mat);
@@ -1735,8 +1737,10 @@ void BKE_pchan_mat3_to_rot(bPoseChannel *pchan, float mat[3][3], bool use_compat
 	}
 }
 
-/* Apply a 4x4 matrix to the pose bone,
- * similar to BKE_object_apply_mat4() */
+/**
+ * Apply a 4x4 matrix to the pose bone,
+ * similar to #BKE_object_apply_mat4().
+ */
 void BKE_pchan_apply_mat4(bPoseChannel *pchan, float mat[4][4], bool use_compat)
 {
 	float rot[3][3];
@@ -1744,9 +1748,11 @@ void BKE_pchan_apply_mat4(bPoseChannel *pchan, float mat[4][4], bool use_compat)
 	BKE_pchan_mat3_to_rot(pchan, rot, use_compat);
 }
 
-/* Remove rest-position effects from pose-transform for obtaining
+/**
+ * Remove rest-position effects from pose-transform for obtaining
  * 'visual' transformation of pose-channel.
- * (used by the Visual-Keyframing stuff) */
+ * (used by the Visual-Keyframing stuff).
+ */
 void BKE_armature_mat_pose_to_delta(float delta_mat[4][4], float pose_mat[4][4], float arm_mat[4][4])
 {
 	float imat[4][4];
diff --git a/source/blender/blenkernel/intern/collection.c b/source/blender/blenkernel/intern/collection.c
index 336a4739760..eadf190c363 100644
--- a/source/blender/blenkernel/intern/collection.c
+++ b/source/blender/blenkernel/intern/collection.c
@@ -804,7 +804,7 @@ static void collection_missing_parents_remove(Collection *collection)
  * This is used for library remapping, where these pointers have been set to NULL.
  * Otherwise this should never happen.
  *
- * \note caller must ensure BKE_main_collection_sync_remap() is called afterwards!
+ * \note caller must ensure #BKE_main_collection_sync_remap() is called afterwards!
  *
  * \param collection: may be \a NULL, in which case whole \a bmain database of collections is checked.
  */
diff --git a/source/blender/blenkernel/intern/constraint.c b/source/blender/blenkernel/intern/constraint.c
index 7d9a6c234a0..e8a4983528e 100644
--- a/source/blender/blenkernel/intern/constraint.c
+++ b/source/blender/blenkernel/intern/constraint.c
@@ -4709,15 +4709,18 @@ const bConstraintTypeInfo *BKE_constraint_typeinfo_get(bConstraint *con)
 
 /* ---------- Data Management ------- */
 
-/* helper function for BKE_constraint_free_data() - unlinks references */
+/**
+ * Helper function for #BKE_constraint_free_data() - unlinks references.
+ */
 static void con_unlink_refs_cb(bConstraint *UNUSED(con), ID **idpoin, bool is_reference, void *UNUSED(userData))
 {
 	if (*idpoin && is_reference)
 		id_us_min(*idpoin);
 }
 
-/* Free data of a specific constraint if it has any info.
- * be sure to run BIK_clear_data() when freeing an IK constraint,
+/**
+ * Free data of a specific constraint if it has any info.
+ * be sure to run #BIK_clear_data() when freeing an IK constraint,
  * unless DAG_relations_tag_update is called.
  */
 void BKE_constraint_free_data_ex(bConstraint *con, bool do_id_user)
diff --git a/source/blender/blenkernel/intern/crazyspace.c b/source/blender/blenkernel/intern/crazyspace.c
index 5dd5e014cc8..4aa3b702693 100644
--- a/source/blender/blenkernel/intern/crazyspace.c
+++ b/source/blender/blenkernel/intern/crazyspace.c
@@ -305,12 +305,13 @@ int BKE_crazyspace_get_first_deform_matrices_editbmesh(
 	return numleft;
 }
 
-/* Crazyspace evaluation needs to have an object which has all the fields
+/**
+ * Crazyspace evaluation needs to have an object which has all the fields
  * evaluated, but the mesh data being at undeformed state. This way it can
  * re-apply modifiers and also have proper pointers to key data blocks.
  *
- * Similar to BKE_object_eval_reset(), but does not modify the actual evaluated
- * object. */
+ * Similar to #BKE_object_eval_reset(), but does not modify the actual evaluated object.
+ */
 static void crazyspace_init_object_for_eval(
         struct Depsgraph *depsgraph,
         Object *object,
diff --git a/source/blender/blenkernel/intern/image.c b/source/blender/blenkernel/intern/image.c
index b00e4cbcdd9..0205f275f59 100644
--- a/source/blender/blenkernel/intern/image.c
+++ b/source/blender/blenkernel/intern/image.c
@@ -4770,8 +4770,9 @@ bool BKE_image_has_loaded_ibuf(Image *image)
 	return has_loaded_ibuf;
 }
 
-/* References the result, BKE_image_release_ibuf is to be called to de-reference.
- * Use lock=NULL when calling BKE_image_release_ibuf().
+/**
+ * References the result, #BKE_image_release_ibuf is to be called to de-reference.
+ * Use lock=NULL when calling #BKE_image_release_ibuf().
  */
 ImBuf *BKE_image_get_ibuf_with_name(Image *image, const char *name)
 {
@@ -4797,8 +4798,9 @@ ImBuf *BKE_image_get_ibuf_with_name(Image *image, const char *name)
 	return ibuf;
 }
 
-/* References the result, BKE_image_release_ibuf is to be called to de-reference.
- * Use lock=NULL when calling BKE_image_release_ibuf().
+/**
+ * References the result, #BKE_image_release_ibuf is to be called to de-reference.
+ * Use lock=NULL when calling #BKE_image_release_ibuf().
  *
  * TODO(sergey): This is actually "get first entry from the cache", which is
  *               not so much predictable. But using first loaded image buffer
diff --git a/source/blender/blenkernel/intern/library_query.c b/source/blender/blenkernel/intern/library_query.c
index 4fc1ea6bb62..b7ae8eea18d 100644
--- a/source/blender/blenkernel/intern/library_query.c
+++ b/source/blender/blenkernel/intern/library_query.c
@@ -1294,7 +1294,7 @@ bool BKE_library_ID_is_indirectly_used(Main *bmain, void *idv)
 }
 
 /**
- * Combine \a BKE_library_ID_is_locally_used() and \a BKE_library_ID_is_indirectly_used() in a single call.
+ * Combine #BKE_library_ID_is_locally_used() and #BKE_library_ID_is_indirectly_used() in a single call.
  */
 void BKE_library_ID_test_usages(Main *bmain, void *idv, bool *is_used_local, bool *is_used_linked)
 {
diff --git a/source/blender/blenkernel/intern/mesh_validate.c b/source/blender/blenkernel/intern/mesh_validate.c
index a5aa198bc4e..295b65190a8 100644
--- a/source/blender/blenkernel/intern/mesh_validate.c
+++ b/source/blender/blenkernel/intern/mesh_validate.c
@@ -1063,10 +1063,13 @@ void BKE_mesh_strip_loose_faces(Mesh *me)
 	}
 }
 
-/* Works on both loops and polys! */
-/* Note: It won't try to guess which loops of an invalid poly to remove!
- *       this is the work of the caller, to mark those loops...
- *       See e.g. BKE_mesh_validate_arrays(). */
+/**
+ * Works on both loops and polys!
+ *
+ * \note It won't try to guess which loops of an invalid poly to remove!
+ * this is the work of the caller, to mark those loops...
+ * See e.g. #BKE_mesh_validate_arrays().
+ */
 void BKE_mesh_strip_loose_polysloops(Mesh *me)
 {
 	MPoly *p;
diff --git a/source/blender/blenkernel/intern/object.c b/source/blender/blenkernel/intern/object.c
index 9985c8026e7..6e9c8ecb480 100644
--- a/source/blender/blenkernel/intern/object.c
+++ b/source/blender/blenkernel/intern/object.c
@@ -1429,11 +1429,11 @@ Object *BKE_object_copy(Main *bmain, const Object *ob)
 
 /** Perform deep-copy of object and its 'children' data-blocks (obdata, materials, actions, etc.).
  *
- * \param dupflag Controls which sub-data are also duplicated (see \a eDupli_ID_Flags in \a DNA_userdef_types.h).
+ * \param dupflag Controls which sub-data are also duplicated (see #eDupli_ID_Flags in DNA_userdef_types.h).
  *
- * \note This function does not do any remapping to new IDs, caller must do it (\a BKE_libblock_relink_to_newid()).
- * \note Caller MUST free \a newid pointers itself (\a BKE_main_id_clear_newpoins()) and call updates of DEG too
- *       (\a DAG_relations_tag_update()).
+ * \note This function does not do any remapping to new IDs, caller must do it (\a #BKE_libblock_relink_to_newid()).
+ * \note Caller MUST free \a newid pointers itself (#BKE_main_id_clear_newpoins()) and call updates of DEG too
+ *       (#DAG_relations_tag_update()).
  */
 Object *BKE_object_duplicate(Main *bmain, const Object *ob, const int dupflag)
 {
@@ -3147,10 +3147,12 @@ void BKE_object_handle_update_ex(Depsgraph *depsgraph,
 	object_handle_update_proxy(depsgraph, scene, ob, do_proxy_update);
 }
 
-/* WARNING: "scene" here may not be the scene object actually resides in.
+/**
+ * \warning "scene" here may not be the scene object actually resides in.
  * When dealing with background-sets, "scene" is actually the active scene.
  * e.g. "scene" <-- set 1 <-- set 2 ("ob" lives here) <-- set 3 <-- ... <-- set n
- * rigid bodies depend on their world so use BKE_object_handle_update_ex() to also pass along the current rigid body world
+ * rigid bodies depend on their world so use #BKE_object_handle_update_ex()
+ * to also pass along the current rigid body world.
  */
 void BKE_object_handle_update(Depsgraph *depsgraph, Scene *scene, Object *ob)
 {
diff --git a/source/blender/blenkernel/intern/object_update.c b/source/blender/blenkernel/intern/object_update.c
index c03fffc4098..bcca39cff24 100644
--- a/source/blender/blenkernel/intern/object_update.c
+++ b/source/blender/blenkernel/intern/object_update.c
@@ -66,7 +66,7 @@
  *
  * Some changes done directly in evaluated object require them to be reset
  * before being re-evaluated.
- * For example, we need to call this before BKE_mesh_new_from_object(),
+ * For example, we need to call this before #BKE_mesh_new_from_object(),
  * in case we removed/added modifiers in the evaluated object.
  */
 void BKE_object_eval_reset(Object *ob_eval)
@@ -244,8 +244,10 @@ void BKE_object_handle_data_update(
 	BKE_object_eval_boundbox(depsgraph, ob);
 }
 
-/* TODO(sergey): Ensure that bounding box is already calculated, and move this
- * into BKE_object_synchronize_to_original(). */
+/**
+ * TODO(sergey): Ensure that bounding box is already calculated, and move this
+ * into #BKE_object_synchronize_to_original().
+ */
 void BKE_object_eval_boundbox(Depsgraph *depsgraph, Object *object)
 {
 	if (!DEG_is_active(depsgraph)) {
diff --git a/source/blender/blenkernel/intern/pbvh.c b/source/blender/blenkernel/intern/pbvh.c
index 7dc772576c5..09fc7c64d6a 100644
--- a/source/blender/blenkernel/intern/pbvh.c
+++ b/source/blender/blenkernel/intern/pbvh.c
@@ -516,7 +516,7 @@ static void pbvh_build(PBVH *bvh, BB *cb, BBC *prim_bbc, int totprim)
  * Do a full rebuild with on Mesh data structure.
  *
  * \note Unlike mpoly/mloop/verts, looptri is **totally owned** by PBVH (which means it may rewrite it if needed,
- *       see BKE_pbvh_apply_vertCos().
+ * see #BKE_pbvh_apply_vertCos().
  */
 void BKE_pbvh_build_mesh(
         PBVH *bvh, const MPoly *mpoly, const MLoop *mloop, MVert *verts,
diff --git a/source/blender/blenkernel/intern/softbody.c b/source/blender/blenkernel/intern/softbody.c
index 0d8b2381572..2e0d4719339 100644
--- a/source/blender/blenkernel/intern/softbody.c
+++ b/source/blender/blenkernel/intern/softbody.c
@@ -725,8 +725,9 @@ static void add_bp_springlist(BodyPoint *bp, int springID)
 	}
 }
 
-/* do this once when sb is build
- * it is O(N^2) so scanning for springs every iteration is too expensive
+/**
+ * Do this once when sb is build it is `O(N^2)`
+ * so scanning for springs every iteration is too expensive.
  */
 static void build_bps_springlist(Object *ob)
 {
diff --git a/source/blender/blenkernel/intern/tracking_stabilize.c b/source/blender/blenkernel/intern/tracking_stabilize.c
index 5e7f2421428..6a0dbefd340 100644
--- a/source/blender/blenkernel/intern/tracking_stabilize.c
+++ b/source/blender/blenkernel/intern/tracking_stabilize.c
@@ -266,12 +266,13 @@ static StabContext *initialize_stabilization_working_context(MovieClip *clip)
 	return ctx;
 }
 
-/* Discard all private working data attached to this call context.
- * NOTE: We allocate the record for the per track baseline contribution
- *       locally for each call context (i.e. call to
- *       BKE_tracking_stabilization_data_get()
- *       Thus it is correct to discard all allocations found within the
- *       corresponding _local_ GHash
+/**
+ * Discard all private working data attached to this call context.
+ *
+ * \note We allocate the record for the per track baseline contribution
+ * locally for each call context (i.e. call to #BKE_tracking_stabilization_data_get)
+ * Thus it is correct to discard all allocations found within the
+ * corresponding _local_ GHash.
  */
 static void discard_stabilization_working_context(StabContext *ctx)
 {