code cleanup: move doxy docs from headers into source. also replace strncpy();str[len]=0 with BLI_strncpy() in BLI_stringdec().

1 files changed, 92 insertions, 15 deletions

diff --git a/source/blender/blenkernel/intern/idprop.c b/source/blender/blenkernel/intern/idprop.c
index 8dc284e0a3e..ca1ae23c364 100644
--- a/source/blender/blenkernel/intern/idprop.c
+++ b/source/blender/blenkernel/intern/idprop.c
@@ -61,8 +61,10 @@ static char idp_size_table[] = {
 
 /* --------- property array type -------------*/
 
-/* note: as a start to move away from the stupid IDP_New function, this type
- * has it's own allocation function.*/
+/**
+ * \note as a start to move away from the stupid IDP_New function, this type
+ * has it's own allocation function.
+ */
 IDProperty *IDP_NewIDPArray(const char *name)
 {
 	IDProperty *prop = MEM_callocN(sizeof(IDProperty), "IDProperty prop array");
@@ -443,8 +445,8 @@ void IDP_SyncGroupValues(IDProperty *dest, IDProperty *src)
 	}
 }
 
-/*
- * replaces all properties with the same name in a destination group from a source group.
+/**
+ * Replaces all properties with the same name in a destination group from a source group.
  */
 void IDP_ReplaceGroupInGroup(IDProperty *dest, IDProperty *src)
 {
@@ -471,9 +473,10 @@ void IDP_ReplaceGroupInGroup(IDProperty *dest, IDProperty *src)
 		}
 	}
 }
-/*
- * replaces a property with the same name in a group, or adds 
- * it if the properly doesn't exist.
+
+/**
+ * Checks if a property with the same name as prop exists, and if so replaces it.
+ * Use this to preserve order!
  */
 void IDP_ReplaceInGroup(IDProperty *group, IDProperty *prop)
 {
@@ -515,8 +518,21 @@ void IDP_MergeGroup(IDProperty *dest, IDProperty *src, const int do_overwrite)
 	}
 }
 
-/* returns 0 if an id property with the same name exists and it failed,
- * or 1 if it succeeded in adding to the group.*/
+/**
+ * This function has a sanity check to make sure ID properties with the same name don't
+ * get added to the group.
+ *
+ * The sanity check just means the property is not added to the group if another property
+ * exists with the same name; the client code using ID properties then needs to detect this
+ * (the function that adds new properties to groups, IDP_AddToGroup,returns 0 if a property can't
+ * be added to the group, and 1 if it can) and free the property.
+ *
+ * Currently the code to free ID properties is designed to leave the actual struct
+ * you pass it un-freed, this is needed for how the system works.  This means
+ * to free an ID property, you first call IDP_FreeProperty then MEM_freeN the
+ * struct.  In the future this will just be IDP_FreeProperty and the code will
+ * be reorganized to work properly.
+ */
 int IDP_AddToGroup(IDProperty *group, IDProperty *prop)
 {
 	if (IDP_GetPropertyFromGroup(group, prop->name) == NULL) {
@@ -528,6 +544,10 @@ int IDP_AddToGroup(IDProperty *group, IDProperty *prop)
 	return 0;
 }
 
+/**
+ * This is the same as IDP_AddToGroup, only you pass an item
+ * in the group list to be inserted after.
+ */
 int IDP_InsertToGroup(IDProperty *group, IDProperty *previous, IDProperty *pnew)
 {
 	if (IDP_GetPropertyFromGroup(group, pnew->name) == NULL) {
@@ -539,6 +559,13 @@ int IDP_InsertToGroup(IDProperty *group, IDProperty *previous, IDProperty *pnew)
 	return 0;
 }
 
+/**
+ * \note this does not free the property!!
+ *
+ * To free the property, you have to do:
+ * IDP_FreeProperty(prop); //free all subdata
+ * MEM_freeN(prop); //free property struct itself
+ */
 void IDP_RemFromGroup(IDProperty *group, IDProperty *prop)
 {
 	group->len--;
@@ -549,7 +576,7 @@ IDProperty *IDP_GetPropertyFromGroup(IDProperty *prop, const char *name)
 {
 	return (IDProperty *)BLI_findstring(&prop->data.group, name, offsetof(IDProperty, name));
 }
-
+/** same as above but ensure type match */
 IDProperty *IDP_GetPropertyTypeFromGroup(IDProperty *prop, const char *name, const char type)
 {
 	IDProperty *idprop = IDP_GetPropertyFromGroup(prop, name);
@@ -561,6 +588,12 @@ typedef struct IDPIter {
 	IDProperty *parent;
 } IDPIter;
 
+/**
+ * Get an iterator to iterate over the members of an id property group.
+ * Note that this will automatically free the iterator once iteration is complete;
+ * if you stop the iteration before hitting the end, make sure to call
+ * IDP_FreeIterBeforeEnd().
+ */
 void *IDP_GetGroupIterator(IDProperty *prop)
 {
 	IDPIter *iter = MEM_callocN(sizeof(IDPIter), "IDPIter");
@@ -569,6 +602,12 @@ void *IDP_GetGroupIterator(IDProperty *prop)
 	return (void *) iter;
 }
 
+/**
+ * Returns the next item in the iteration.  To use, simple for a loop like the following:
+ * while (IDP_GroupIterNext(iter) != NULL) {
+ *     ...
+ * }
+ */
 IDProperty *IDP_GroupIterNext(void *vself)
 {
 	IDPIter *self = (IDPIter *) vself;
@@ -582,6 +621,10 @@ IDProperty *IDP_GroupIterNext(void *vself)
 	return (void *) next;
 }
 
+/**
+ * Frees the iterator pointed to at vself, only use this if iteration is stopped early;
+ * when the iterator hits the end of the list it'll automatically free itself.\
+ */
 void IDP_FreeIterBeforeEnd(void *vself)
 {
 	MEM_freeN(vself);
@@ -613,6 +656,11 @@ IDProperty *IDP_CopyProperty(IDProperty *prop)
 	}
 }
 
+/**
+ * Get the Group property that contains the id properties for ID id.  Set create_if_needed
+ * to create the Group property and attach it to id if it doesn't exist; otherwise
+ * the function will return NULL if there's no Group property attached to the ID.
+ */
 IDProperty *IDP_GetProperties(ID *id, int create_if_needed)
 {
 	if (id->properties) {
@@ -702,7 +750,31 @@ int IDP_EqualsProperties(IDProperty *prop1, IDProperty *prop2)
 	return IDP_EqualsProperties_ex(prop1, prop2, TRUE);
 }
 
-/* 'val' is never NULL, don't check */
+/**
+ * Allocate a new ID.
+ *
+ * This function takes three arguments: the ID property type, a union which defines
+ * it's initial value, and a name.
+ *
+ * The union is simple to use; see the top of this header file for its definition.
+ * An example of using this function:
+ *
+ *     IDPropertyTemplate val;
+ *     IDProperty *group, *idgroup, *color;
+ *     group = IDP_New(IDP_GROUP, val, "group1"); //groups don't need a template.
+ *
+ *     val.array.len = 4
+ *     val.array.type = IDP_FLOAT;
+ *     color = IDP_New(IDP_ARRAY, val, "color1");
+ *
+ *     idgroup = IDP_GetProperties(some_id, 1);
+ *     IDP_AddToGroup(idgroup, color);
+ *     IDP_AddToGroup(idgroup, group);
+ *
+ * Note that you MUST either attach the id property to an id property group with
+ * IDP_AddToGroup or MEM_freeN the property, doing anything else might result in
+ * a memory leak.
+ */
 IDProperty *IDP_New(const int type, const IDPropertyTemplate *val, const char *name)
 {
 	IDProperty *prop = NULL;
@@ -793,9 +865,11 @@ IDProperty *IDP_New(const int type, const IDPropertyTemplate *val, const char *n
 	return prop;
 }
 
-/* NOTE: this will free all child properties including list arrays and groups!
+/**
+ * \note this will free all child properties of list arrays and groups!
  * Also, note that this does NOT unlink anything!  Plus it doesn't free
- * the actual IDProperty struct either.*/
+ * the actual struct IDProperty struct either.
+ */
 void IDP_FreeProperty(IDProperty *prop)
 {
 	switch (prop->type) {
@@ -821,8 +895,11 @@ void IDP_ClearProperty(IDProperty *prop)
 	prop->len = prop->totallen = 0;
 }
 
-/* Unlinks any IDProperty<->ID linkage that might be going on.
- * note: currently unused.*/
+/**
+ * Unlinks any struct IDProperty<->ID linkage that might be going on.
+ *
+ * \note currently unused
+ */
 void IDP_UnlinkProperty(IDProperty *prop)
 {
 	switch (prop->type) {