From 08aef8a7c8fc9fa25ab6881a4601c616d8152062 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Sun, 24 Mar 2013 01:51:54 +0000 Subject: code cleanup: move doxy docs from headers into source. also replace strncpy();str[len]=0 with BLI_strncpy() in BLI_stringdec(). --- source/blender/blenkernel/intern/idprop.c | 107 +++++++++++++++++++++++++----- 1 file changed, 92 insertions(+), 15 deletions(-) (limited to 'source/blender/blenkernel/intern/idprop.c') 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) { -- cgit v1.2.3