Cleanup: Use doxy for more structured comments

12 files changed, 89 insertions, 59 deletions

diff --git a/source/blender/blenkernel/intern/anim.c b/source/blender/blenkernel/intern/anim.c
index 4cce69dc824..b8e76858ffe 100644
--- a/source/blender/blenkernel/intern/anim.c
+++ b/source/blender/blenkernel/intern/anim.c
@@ -125,12 +125,13 @@ void animviz_free_motionpath(bMotionPath *mpath)
 
 /* ------------------- */
 
-/* Setup motion paths for the given data
- * - Only used when explicitly calculating paths on bones which may/may not be consider already
+/**
+ * Setup motion paths for the given data.
+ * \note Only used when explicitly calculating paths on bones which may/may not be consider already
  *
- * < scene: current scene (for frame ranges, etc.)
- * < ob: object to add paths for (must be provided)
- * < pchan: posechannel to add paths for (optional; if not provided, object-paths are assumed)
+ * \param scene Current scene (for frame ranges, etc.)
+ * \param ob Object to add paths for (must be provided)
+ * \param pchan Posechannel to add paths for (optional; if not provided, object-paths are assumed)
  */
 bMotionPath *animviz_verify_motionpaths(ReportList *reports, Scene *scene, Object *ob, bPoseChannel *pchan)
 {
diff --git a/source/blender/blenkernel/intern/anim_sys.c b/source/blender/blenkernel/intern/anim_sys.c
index 6a9c4c851b2..776f7c51313 100644
--- a/source/blender/blenkernel/intern/anim_sys.c
+++ b/source/blender/blenkernel/intern/anim_sys.c
@@ -381,10 +381,12 @@ void BKE_relink_animdata(AnimData *adt)
 
 /* Sub-ID Regrouping ------------------------------------------- */
 
-/* helper heuristic for determining if a path is compatible with the basepath 
- * < path: (str) full RNA-path from some data (usually an F-Curve) to compare
- * < basepath: (str) shorter path fragment to look for
- * > returns (bool) whether there is a match
+/**
+ * Helper heuristic for determining if a path is compatible with the basepath
+ *
+ * \param path Full RNA-path from some data (usually an F-Curve) to compare
+ * \param basepath Shorter path fragment to look for
+ * \return Whether there is a match
  */
 static bool animpath_matches_basepath(const char path[], const char basepath[])
 {
@@ -2232,9 +2234,12 @@ void nladata_flush_channels(ListBase *channels)
 
 /* ---------------------- */
 
-/* NLA Evaluation function - values are calculated and stored in temporary "NlaEvalChannels" 
- * ! This is exported so that keyframing code can use this for make use of it for anim layers support
- * > echannels: (list<NlaEvalChannels>) evaluation channels with calculated values
+/**
+ * NLA Evaluation function - values are calculated and stored in temporary "NlaEvalChannels"
+ *
+ * \note This is exported so that keyframing code can use this for make use of it for anim layers support
+ *
+ * \param echannels Evaluation channels with calculated values
  */
 static void animsys_evaluate_nla(ListBase *echannels, PointerRNA *ptr, AnimData *adt, float ctime)
 {
diff --git a/source/blender/blenkernel/intern/nla.c b/source/blender/blenkernel/intern/nla.c
index 0c244e8a40b..d0114d52a06 100644
--- a/source/blender/blenkernel/intern/nla.c
+++ b/source/blender/blenkernel/intern/nla.c
@@ -157,8 +157,10 @@ void free_nladata(ListBase *tracks)
 
 /* Copying ------------------------------------------- */
 
-/* Copy NLA strip 
- * < use_same_action: if true, the existing action is used (instead of being duplicated)
+/**
+ * Copy NLA strip
+ *
+ * \param use_same_action When true, the existing action is used (instead of being duplicated)
  */
 NlaStrip *copy_nlastrip(NlaStrip *strip, const bool use_same_action)
 {
diff --git a/source/blender/blenkernel/intern/rigidbody.c b/source/blender/blenkernel/intern/rigidbody.c
index 86128994092..09293503ad5 100644
--- a/source/blender/blenkernel/intern/rigidbody.c
+++ b/source/blender/blenkernel/intern/rigidbody.c
@@ -455,8 +455,10 @@ static void rigidbody_validate_sim_shape(Object *ob, bool rebuild)
 
 /* --------------------- */
 
-/* Create physics sim representation of object given RigidBody settings
- * < rebuild: even if an instance already exists, replace it
+/**
+ * Create physics sim representation of object given RigidBody settings
+ *
+ * \param rebuild Even if an instance already exists, replace it
  */
 static void rigidbody_validate_sim_object(RigidBodyWorld *rbw, Object *ob, bool rebuild)
 {
@@ -518,8 +520,10 @@ static void rigidbody_validate_sim_object(RigidBodyWorld *rbw, Object *ob, bool
 
 /* --------------------- */
 
-/* Create physics sim representation of constraint given rigid body constraint settings
- * < rebuild: even if an instance already exists, replace it
+/**
+ * Create physics sim representation of constraint given rigid body constraint settings
+ *
+ * \param rebuild Even if an instance already exists, replace it
  */
 static void rigidbody_validate_sim_constraint(RigidBodyWorld *rbw, Object *ob, bool rebuild)
 {
@@ -895,7 +899,8 @@ RigidBodyCon *BKE_rigidbody_create_constraint(Scene *scene, Object *ob, short ty
 /* Utilities API */
 
 /* Get RigidBody world for the given scene, creating one if needed
- * < scene: Scene to find active Rigid Body world for
+ *
+ * \param scene Scene to find active Rigid Body world for
  */
 RigidBodyWorld *BKE_rigidbody_get_world(Scene *scene)
 {
@@ -1093,8 +1098,10 @@ static void rigidbody_update_sim_ob(Scene *scene, RigidBodyWorld *rbw, Object *o
 	 */
 }
 
-/* Updates and validates world, bodies and shapes.
- * < rebuild: rebuild entire simulation
+/**
+ * Updates and validates world, bodies and shapes.
+ *
+ * \param rebuild Rebuild entire simulation
  */
 static void rigidbody_update_simulation(Scene *scene, RigidBodyWorld *rbw, bool rebuild)
 {
diff --git a/source/blender/editors/animation/anim_channels_edit.c b/source/blender/editors/animation/anim_channels_edit.c
index a7e7cb2df1a..7da8aee8d6c 100644
--- a/source/blender/editors/animation/anim_channels_edit.c
+++ b/source/blender/editors/animation/anim_channels_edit.c
@@ -769,10 +769,12 @@ static bool rearrange_island_bottom(ListBase *list, tReorderChannelIsland *islan
 
 /* ............................. */
 
-/* typedef for channel rearranging function 
- * < list: list that channels belong to
- * < island: island to be moved
- * > return[0]: whether operation was a success
+/**
+ * typedef for channel rearranging function
+ *
+ * \param list List that channels belong to
+ * \param island Island to be moved
+ * \return Whether operation was a success
  */
 typedef bool (*AnimChanRearrangeFp)(ListBase *list, tReorderChannelIsland *island);
 
diff --git a/source/blender/editors/animation/anim_filter.c b/source/blender/editors/animation/anim_filter.c
index b80e29ba424..9fec1d28a29 100644
--- a/source/blender/editors/animation/anim_filter.c
+++ b/source/blender/editors/animation/anim_filter.c
@@ -987,8 +987,10 @@ static bool skip_fcurve_with_name(bDopeSheet *ads, FCurve *fcu, ID *owner_id)
 	return true;
 }
 
-/* Check if F-Curve has errors and/or is disabled 
- * > returns: (bool) True if F-Curve has errors/is disabled
+/**
+ * Check if F-Curve has errors and/or is disabled
+ *
+ * \return true if F-Curve has errors/is disabled
  */
 static bool fcurve_has_errors(FCurve *fcu)
 {
diff --git a/source/blender/editors/animation/anim_markers.c b/source/blender/editors/animation/anim_markers.c
index 04363f61fd6..e0592e594be 100644
--- a/source/blender/editors/animation/anim_markers.c
+++ b/source/blender/editors/animation/anim_markers.c
@@ -115,12 +115,15 @@ ListBase *ED_animcontext_get_markers(const bAnimContext *ac)
 
 /* --------------------------------- */
 
-/* Apply some transformation to markers after the fact 
- * < markers: list of markers to affect - this may or may not be the scene markers list, so don't assume anything
- * < scene: current scene (for getting current frame)
- * < mode: (TfmMode) transform mode that this transform is for
- * < value: from the transform code, this is t->vec[0] (which is delta transform for grab/extend, and scale factor for scale)
- * < side: (B/L/R) for 'extend' functionality, which side of current frame to use
+/**
+ * Apply some transformation to markers after the fact
+ *
+ * \param markers List of markers to affect - this may or may not be the scene markers list, so don't assume anything
+ * \param scene Current scene (for getting current frame)
+ * \param mode (TfmMode) transform mode that this transform is for
+ * \param value From the transform code, this is ``t->vec[0]``
+ * (which is delta transform for grab/extend, and scale factor for scale)
+ * \param side (B/L/R) for 'extend' functionality, which side of current frame to use
  */
 int ED_markers_post_apply_transform(ListBase *markers, Scene *scene, int mode, float value, char side)
 {
@@ -472,13 +475,14 @@ static int ed_markers_poll_markers_exist(bContext *C)
  
 /* ------------------------ */ 
 
-/* Second-tier invoke() callback that performs context validation before running the  
+/**
+ * Second-tier invoke() callback that performs context validation before running the
  * "custom"/third-tier invoke() callback supplied as the last arg (which would normally
  * be the operator's invoke() callback elsewhere)
  *
- * < invoke_func: (fn(bContext *, wmOperator *, wmEvent *)=int) "standard" invoke function
- *			that operator would otherwise have used. If NULL, the operator's standard
- *			exec() callback will be called instead in the appropriate places.
+ * \param invoke_func "standard" invoke function that operator would otherwise have used.
+ * If NULL, the operator's standard exec()
+ * callback will be called instead in the appropriate places.
  */
 static int ed_markers_opwrap_invoke_custom(bContext *C, wmOperator *op, const wmEvent *event,
                                            int (*invoke_func)(bContext *, wmOperator *, const wmEvent *))
diff --git a/source/blender/editors/animation/drivers.c b/source/blender/editors/animation/drivers.c
index 839284905ff..ee33f3b766a 100644
--- a/source/blender/editors/animation/drivers.c
+++ b/source/blender/editors/animation/drivers.c
@@ -426,15 +426,15 @@ bool ANIM_paste_driver(ReportList *reports, ID *id, const char rna_path[], int a
 /* ************************************************** */
 /* UI-Button Interface */
 
-/* Temporary wrapper for driver operators for buttons to make it easier to create
+/**
+ * Temporary wrapper for driver operators for buttons to make it easier to create
  * such drivers by rerouting all paths through the active object instead so that
  * they will get picked up by the dependency system.
  *
- * < C: context pointer - for getting active data 
- * <> ptr: RNA pointer for property's datablock. May be modified as result of path remapping.
- * < prop: RNA definition of property to add for
- *
- * > returns: MEM_alloc'd string representing the path to the property from the given PointerRNA
+ * \param C Context pointer - for getting active data
+ * \param ptr RNA pointer for property's datablock. May be modified as result of path remapping.
+ * \param prop RNA definition of property to add for
+ * \return MEM_alloc'd string representing the path to the property from the given #PointerRNA
  */
 static char *get_driver_path_hack(bContext *C, PointerRNA *ptr, PropertyRNA *prop)
 {
diff --git a/source/blender/editors/animation/keyframes_general.c b/source/blender/editors/animation/keyframes_general.c
index 07a1a7e6b30..640568a99e4 100644
--- a/source/blender/editors/animation/keyframes_general.c
+++ b/source/blender/editors/animation/keyframes_general.c
@@ -763,8 +763,10 @@ EnumPropertyItem keyframe_paste_merge_items[] = {
 	{0, NULL, 0, NULL, NULL}};
 
 
-/* This function pastes data from the keyframes copy/paste buffer 
- * > return status code is whether the method FAILED to do anything
+/**
+ * This function pastes data from the keyframes copy/paste buffer
+ *
+ * \return Status code is whether the method FAILED to do anything
  */
 short paste_animedit_keys(bAnimContext *ac, ListBase *anim_data,
                           const eKeyPasteOffset offset_mode, const eKeyMergeMode merge_mode)
diff --git a/source/blender/editors/armature/pose_transform.c b/source/blender/editors/armature/pose_transform.c
index 094af99776b..0cde8f30ace 100644
--- a/source/blender/editors/armature/pose_transform.c
+++ b/source/blender/editors/armature/pose_transform.c
@@ -290,13 +290,14 @@ static void set_pose_keys(Object *ob)
 	}
 }
 
-/* perform paste pose, for a single bone 
- * < ob: object where bone to paste to lives
- * < chan: bone that pose to paste comes from
- * < selOnly: only paste on selected bones
- * < flip: flip on x-axis
+/**
+ * Perform paste pose, for a single bone.
  *
- * > returns: whether the bone that we pasted to if we succeeded
+ * \param ob Object where bone to paste to lives
+ * \param chan Bone that pose to paste comes from
+ * \param selOnly Only paste on selected bones
+ * \param flip Flip on x-axis
+ * \return Whether the bone that we pasted to if we succeeded
  */
 static bPoseChannel *pose_bone_do_paste(Object *ob, bPoseChannel *chan, const bool selOnly, const bool flip)
 {
diff --git a/source/blender/editors/space_action/action_edit.c b/source/blender/editors/space_action/action_edit.c
index 3bc3c7f7b73..43cecf1d48e 100644
--- a/source/blender/editors/space_action/action_edit.c
+++ b/source/blender/editors/space_action/action_edit.c
@@ -362,10 +362,12 @@ void ACTION_OT_previewrange_set(wmOperatorType *ot)
 
 /* ****************** View-All Operator ****************** */
 
-/* Find the extents of the active channel
- * > min: (float) bottom y-extent of channel
- * > max: (float) top y-extent of channel
- * > returns: success of finding a selected channel
+/**
+ * Find the extents of the active channel
+ *
+ * \param min Bottom y-extent of channel
+ * \param max Top y-extent of channel
+ * \return Success of finding a selected channel
  */
 static bool actkeys_channels_get_selected_extents(bAnimContext *ac, float *min, float *max)
 {
diff --git a/source/blender/editors/space_nla/nla_edit.c b/source/blender/editors/space_nla/nla_edit.c
index 11674805a3e..ef3bb1a548b 100644
--- a/source/blender/editors/space_nla/nla_edit.c
+++ b/source/blender/editors/space_nla/nla_edit.c
@@ -356,10 +356,12 @@ void NLA_OT_previewrange_set(wmOperatorType *ot)
 
 /* ****************** View-All Operator ****************** */
 
-/* Find the extents of the active channel
- * > min: (float) bottom y-extent of channel
- * > max: (float) top y-extent of channel
- * > returns: success of finding a selected channel
+/**
+ * Find the extents of the active channel
+ *
+ * \param min Bottom y-extent of channel
+ * \param max Top y-extent of channel
+ * \return Success of finding a selected channel
  */
 static bool nla_channels_get_selected_extents(bAnimContext *ac, float *min, float *max)
 {