From b461cc9cd4f9e1827feec81b88ffc8c3b981755f Mon Sep 17 00:00:00 2001
From: Campbell Barton <ideasman42@gmail.com>
Date: Sat, 26 Oct 2013 03:56:32 +0000
Subject: code cleanup: merge doxygen comments into C source.

---
 source/blender/blenkernel/intern/action.c | 63 +++++++++++++++++++++++++------
 1 file changed, 51 insertions(+), 12 deletions(-)

(limited to 'source/blender/blenkernel/intern/action.c')

diff --git a/source/blender/blenkernel/intern/action.c b/source/blender/blenkernel/intern/action.c
index b0644da4598..94da2a330c1 100644
--- a/source/blender/blenkernel/intern/action.c
+++ b/source/blender/blenkernel/intern/action.c
@@ -440,6 +440,10 @@ void action_groups_clear_tempflags(bAction *act)
 
 /* *************** Pose channels *************** */
 
+/**
+ * Return a pointer to the pose channel of the given name
+ * from this pose.
+ */
 bPoseChannel *BKE_pose_channel_find_name(const bPose *pose, const char *name)
 {
 	if (ELEM(NULL, pose, name) || (name[0] == '\0'))
@@ -451,8 +455,14 @@ bPoseChannel *BKE_pose_channel_find_name(const bPose *pose, const char *name)
 	return BLI_findstring(&((bPose *)pose)->chanbase, name, offsetof(bPoseChannel, name));
 }
 
-/* Use with care, not on Armature poses but for temporal ones */
-/* (currently used for action constraints and in rebuild_pose) */
+/**
+ * Looks to see if the channel with the given name
+ * already exists in this pose - if not a new one is
+ * allocated and initialized.
+ *
+ * \note Use with care, not on Armature poses but for temporal ones.
+ * \note (currently used for action constraints and in rebuild_pose).
+ */
 bPoseChannel *BKE_pose_channel_verify(bPose *pose, const char *name)
 {
 	bPoseChannel *chan;
@@ -505,7 +515,12 @@ bool BKE_pose_channels_is_valid(const bPose *pose)
 }
 
 #endif
-/* Find the active posechannel for an object (we can't just use pose, as layer info is in armature) */
+
+/**
+ * Find the active posechannel for an object (we can't just use pose, as layer info is in armature)
+ *
+ * \note: Object, not bPose is used here, as we need layer info from Armature)
+ */
 bPoseChannel *BKE_pose_channel_active(Object *ob)
 {
 	bArmature *arm = (ob) ? ob->data : NULL;
@@ -536,8 +551,14 @@ const char *BKE_pose_ikparam_get_name(bPose *pose)
 	}
 	return NULL;
 }
-/* dst should be freed already, makes entire duplicate */
-void BKE_pose_copy_data(bPose **dst, bPose *src, int copycon)
+
+/**
+ * Allocate a new pose on the heap, and copy the src pose and it's channels
+ * into the new pose. *dst is set to the newly allocated structure, and assumed to be NULL.
+ *
+ * \param dst  Should be freed already, makes entire duplicate.
+ */
+void BKE_pose_copy_data(bPose **dst, bPose *src, const bool copy_constraints)
 {
 	bPose *outPose;
 	bPoseChannel *pchan;
@@ -558,8 +579,7 @@ void BKE_pose_copy_data(bPose **dst, bPose *src, int copycon)
 	outPose->avs = src->avs;
 	
 	for (pchan = outPose->chanbase.first; pchan; pchan = pchan->next) {
-		/* TODO: rename this argument... */
-		if (copycon) {
+		if (copy_constraints) {
 			BKE_copy_constraints(&listb, &pchan->constraints, TRUE);  // BKE_copy_constraints NULLs listb
 			pchan->constraints = listb;
 			pchan->mpath = NULL; /* motion paths should not get copied yet... */
@@ -571,8 +591,9 @@ void BKE_pose_copy_data(bPose **dst, bPose *src, int copycon)
 	}
 
 	/* for now, duplicate Bone Groups too when doing this */
-	if (copycon)
+	if (copy_constraints) {
 		BLI_duplicatelist(&outPose->agroups, &src->agroups);
+	}
 	
 	*dst = outPose;
 }
@@ -641,7 +662,10 @@ bool BKE_pose_channel_in_IK_chain(Object *ob, bPoseChannel *pchan)
 	return pose_channel_in_IK_chain(ob, pchan, 0);
 }
 
-
+/**
+ * Removes the hash for quick lookup of channels, must
+ * be done when adding/removing channels.
+ */
 void BKE_pose_channels_hash_make(bPose *pose) 
 {
 	if (!pose->chanhash) {
@@ -661,6 +685,10 @@ void BKE_pose_channels_hash_free(bPose *pose)
 	}
 }
 
+/**
+ * Deallocates a pose channel.
+ * Does not free the pose channel itself.
+ */
 void BKE_pose_channel_free(bPoseChannel *pchan)
 {
 	if (pchan->custom) {
@@ -681,6 +709,10 @@ void BKE_pose_channel_free(bPoseChannel *pchan)
 	}
 }
 
+/**
+ * Removes and deallocates all channels from a pose.
+ * Does not free the pose itself.
+ */
 void BKE_pose_channels_free(bPose *pose) 
 {
 	bPoseChannel *pchan;
@@ -695,6 +727,9 @@ void BKE_pose_channels_free(bPose *pose)
 	BKE_pose_channels_hash_free(pose);
 }
 
+/**
+ * Removes and deallocates all data from a pose, and also frees the pose.
+ */
 void BKE_pose_free(bPose *pose)
 {
 	if (pose) {
@@ -739,9 +774,13 @@ static void copy_pose_channel_data(bPoseChannel *pchan, const bPoseChannel *chan
 	}
 }
 
-/* makes copies of internal data, unlike copy_pose_channel_data which only
- * copies the pose state.
- * hint: use when copying bones in editmode (on returned value from BKE_pose_channel_verify) */
+/**
+ * Copy the internal members of each pose channel including constraints
+ * and ID-Props, used when duplicating bones in editmode.
+ * (unlike copy_pose_channel_data which only).
+ *
+ * \note use when copying bones in editmode (on returned value from #BKE_pose_channel_verify)
+ */
 void BKE_pose_channel_copy_data(bPoseChannel *pchan, const bPoseChannel *pchan_from)
 {
 	/* copy transform locks */
-- 
cgit v1.2.3