diff options
author | Campbell Barton <ideasman42@gmail.com> | 2013-03-24 05:51:54 +0400 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2013-03-24 05:51:54 +0400 |
commit | 08aef8a7c8fc9fa25ab6881a4601c616d8152062 (patch) | |
tree | 9993345a0182765cbf7ffc58408ade1b4d4dc30f /source/blender/blenkernel | |
parent | 92d7955d133bd70e8cf01321fe34761b534be172 (diff) |
code cleanup: move doxy docs from headers into source. also replace strncpy();str[len]=0 with BLI_strncpy() in BLI_stringdec().
Diffstat (limited to 'source/blender/blenkernel')
-rw-r--r-- | source/blender/blenkernel/BKE_idcode.h | 42 | ||||
-rw-r--r-- | source/blender/blenkernel/BKE_idprop.h | 84 | ||||
-rw-r--r-- | source/blender/blenkernel/intern/idcode.c | 38 | ||||
-rw-r--r-- | source/blender/blenkernel/intern/idprop.c | 107 |
4 files changed, 133 insertions, 138 deletions
diff --git a/source/blender/blenkernel/BKE_idcode.h b/source/blender/blenkernel/BKE_idcode.h index 74dc8de753e..10a34838662 100644 --- a/source/blender/blenkernel/BKE_idcode.h +++ b/source/blender/blenkernel/BKE_idcode.h @@ -32,47 +32,11 @@ * \ingroup bke */ -/** - * Convert an idcode into a name. - * - * \param code The code to convert. - * \return A static string representing the name of - * the code. - */ const char *BKE_idcode_to_name(int code); - -/** - * Convert an idcode into a name (plural). - * - * \param code The code to convert. - * \return A static string representing the name of - * the code. - */ const char *BKE_idcode_to_name_plural(int code); - -/** - * Convert a name into an idcode (ie. ID_SCE) - * - * \param name The name to convert. - * \return The code for the name, or 0 if invalid. - */ -int BKE_idcode_from_name(const char *name); - -/** - * Return non-zero when an ID type is linkable. - * - * \param code The code to check. - * \return Boolean, 0 when non linkable. - */ -bool BKE_idcode_is_linkable(int code); - -/** - * Return if the ID code is a valid ID code. - * - * \param code The code to check. - * \return Boolean, 0 when invalid. - */ -bool BKE_idcode_is_valid(int code); +int BKE_idcode_from_name(const char *name); +bool BKE_idcode_is_linkable(int code); +bool BKE_idcode_is_valid(int code); /** * Return an ID code and steps the index forward 1. diff --git a/source/blender/blenkernel/BKE_idprop.h b/source/blender/blenkernel/BKE_idprop.h index ad3e4bb2251..d8ad3b2e892 100644 --- a/source/blender/blenkernel/BKE_idprop.h +++ b/source/blender/blenkernel/BKE_idprop.h @@ -58,8 +58,6 @@ typedef union IDPropertyTemplate { /* ----------- Property Array Type ---------- */ -/* 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) #ifdef __GNUC__ __attribute__((warn_unused_result)) @@ -136,18 +134,11 @@ __attribute__((nonnull)) #endif ; -/** - * replaces all properties with the same name in a destination group from a source group. - */ void IDP_ReplaceGroupInGroup(struct IDProperty *dest, struct IDProperty *src) #ifdef __GNUC__ __attribute__((nonnull)) #endif ; - -/** - * Checks if a property with the same name as prop exists, and if so replaces it. - * Use this to preserve order!*/ void IDP_ReplaceInGroup(struct IDProperty *group, struct IDProperty *prop) #ifdef __GNUC__ __attribute__((nonnull)) @@ -160,42 +151,17 @@ __attribute__((nonnull)) #endif ; -/** - * 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(struct IDProperty *group, struct IDProperty *prop) #ifdef __GNUC__ __attribute__((nonnull)) #endif ; - -/** this is the same as IDP_AddToGroup, only you pass an item - * in the group list to be inserted after. */ int IDP_InsertToGroup(struct IDProperty *group, struct IDProperty *previous, struct IDProperty *pnew) #ifdef __GNUC__ __attribute__((nonnull (1, 3))) /* 'group', 'pnew' */ #endif ; - -/** \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(struct IDProperty *group, struct IDProperty *prop) #ifdef __GNUC__ __attribute__((nonnull)) @@ -208,41 +174,23 @@ __attribute__((warn_unused_result)) __attribute__((nonnull)) #endif ; -/** same as above but ensure type match */ IDProperty *IDP_GetPropertyTypeFromGroup(struct IDProperty *prop, const char *name, const char type) #ifdef __GNUC__ __attribute__((warn_unused_result)) __attribute__((nonnull)) #endif ; - -/** - * 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(struct IDProperty *prop) #ifdef __GNUC__ __attribute__((warn_unused_result)) #endif ; - -/** - * 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) #ifdef __GNUC__ __attribute__((warn_unused_result)) __attribute__((nonnull)) #endif ; - -/** - * 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) #ifdef __GNUC__ __attribute__((nonnull)) @@ -250,9 +198,6 @@ __attribute__((nonnull)) ; /*-------- Main Functions --------*/ -/** 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.*/ struct IDProperty *IDP_GetProperties(struct ID *id, int create_if_needed) #ifdef __GNUC__ __attribute__((warn_unused_result)) @@ -278,31 +223,6 @@ __attribute__((warn_unused_result)) #endif ; -/** - * 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. - */ struct IDProperty *IDP_New(const int type, const IDPropertyTemplate *val, const char *name) #ifdef __GNUC__ __attribute__((warn_unused_result)) @@ -310,14 +230,10 @@ __attribute__((nonnull)) #endif ; -/** \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 struct IDProperty struct either.*/ void IDP_FreeProperty(struct IDProperty *prop); void IDP_ClearProperty(IDProperty *prop); -/** Unlinks any struct IDProperty<->ID linkage that might be going on.*/ void IDP_UnlinkProperty(struct IDProperty *prop); #define IDP_Int(prop) ((prop)->data.val) diff --git a/source/blender/blenkernel/intern/idcode.c b/source/blender/blenkernel/intern/idcode.c index 66f10e86a70..4e39025e48e 100644 --- a/source/blender/blenkernel/intern/idcode.c +++ b/source/blender/blenkernel/intern/idcode.c @@ -108,17 +108,36 @@ static IDType *idtype_from_code(int code) return NULL; } +/** + * Return if the ID code is a valid ID code. + * + * \param code The code to check. + * \return Boolean, 0 when invalid. + */ bool BKE_idcode_is_valid(int code) { return idtype_from_code(code) ? true : false; } +/** + * Return non-zero when an ID type is linkable. + * + * \param code The code to check. + * \return Boolean, 0 when non linkable. + */ bool BKE_idcode_is_linkable(int code) { IDType *idt = idtype_from_code(code); return idt ? ((idt->flags & IDTYPE_FLAGS_ISLINKABLE) != 0) : false; } +/** + * Convert an idcode into a name. + * + * \param code The code to convert. + * \return A static string representing the name of + * the code. + */ const char *BKE_idcode_to_name(int code) { IDType *idt = idtype_from_code(code); @@ -126,6 +145,12 @@ const char *BKE_idcode_to_name(int code) return idt ? idt->name : NULL; } +/** + * Convert a name into an idcode (ie. ID_SCE) + * + * \param name The name to convert. + * \return The code for the name, or 0 if invalid. + */ int BKE_idcode_from_name(const char *name) { IDType *idt = idtype_from_name(name); @@ -133,6 +158,13 @@ int BKE_idcode_from_name(const char *name) return idt ? idt->code : 0; } +/** + * Convert an idcode into a name (plural). + * + * \param code The code to convert. + * \return A static string representing the name of + * the code. + */ const char *BKE_idcode_to_name_plural(int code) { IDType *idt = idtype_from_code(code); @@ -140,6 +172,12 @@ const char *BKE_idcode_to_name_plural(int code) return idt ? idt->plural : NULL; } +/** + * Return an ID code and steps the index forward 1. + * + * \param index start as 0. + * \return the code, 0 when all codes have been returned. + */ int BKE_idcode_iter_step(int *index) { return (*index < nidtypes) ? idtypes[(*index)++].code : 0; 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) { |