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

This commit is contained in:
Campbell Barton 2013-03-24 01:51:54 +00:00
parent 92d7955d13
commit 08aef8a7c8
10 changed files with 209 additions and 218 deletions

View File

@ -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.

View File

@ -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)

View File

@ -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;

View File

@ -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) {

View File

@ -36,63 +36,13 @@
typedef struct _GSQueue GSQueue;
/**
* Create a new GSQueue.
*
* \param elem_size The size of the structures in the queue.
* \retval The new queue
*/
GSQueue *BLI_gsqueue_new(int elem_size);
/**
* Query if the queue is empty
*/
bool BLI_gsqueue_is_empty(GSQueue *gq);
/**
* Query number elements in the queue
*/
int BLI_gsqueue_size(GSQueue *gq);
/**
* Access the item at the head of the queue
* without removing it.
*
* \param item_r A pointer to an appropriately
* sized structure (the size passed to BLI_gsqueue_new)
*/
void BLI_gsqueue_peek(GSQueue *gq, void *item_r);
/**
* Access the item at the head of the queue
* and remove it.
*
* \param item_r A pointer to an appropriately
* sized structure (the size passed to BLI_gsqueue_new).
* Can be NULL if desired.
*/
void BLI_gsqueue_pop(GSQueue *gq, void *item_r);
/**
* Push an element onto the tail of the queue.
*
* \param item A pointer to an appropriately
* sized structure (the size passed to BLI_gsqueue_new).
*/
void BLI_gsqueue_push(GSQueue *gq, void *item);
/**
* Push an element back onto the head of the queue (so
* it would be returned from the next call to BLI_gsqueue_pop).
*
* \param item A pointer to an appropriately
* sized structure (the size passed to BLI_gsqueue_new).
*/
void BLI_gsqueue_pushback(GSQueue *gq, void *item);
/**
* Free the queue
*/
void BLI_gsqueue_free(GSQueue *gq);
#endif /* __BLI_GSQUEUE_H__ */

View File

@ -170,14 +170,6 @@ bool BLI_path_is_rel(const char *path);
# define BLI_path_ncmp strncmp
#endif
/**
* Change every \a from in \a string into \a to. The
* result will be in \a string
*
* \a string The string to work on
* \a from The character to replace
* \a to The character to replace with
*/
void BLI_char_switch(char *string, char from, char to)
#ifdef __GNUC__
__attribute__((nonnull(1)))
@ -190,13 +182,9 @@ void BLI_init_program_path(const char *argv0);
* NOTE: On Window userdir will be set to the temporary directory! */
void BLI_init_temporary_dir(char *userdir);
/* Path to executable */
const char *BLI_program_path(void);
/* Path to directory of executable */
const char *BLI_program_dir(void);
/* Path to temporary directory (with trailing slash) */
const char *BLI_temporary_dir(void);
/* Path to the system temporary directory (with trailing slash) */
void BLI_system_temporary_dir(char *dir);
#ifdef WITH_ICONV

View File

@ -53,14 +53,6 @@ typedef struct VChar {
float *points;
} VChar;
/**
* Construct a new VFontData structure from
* Freetype font data in a PackedFile.
*
* \param pf The font data.
* \retval A new VFontData structure, or NULL
* if unable to load.
*/
VFontData *BLI_vfontdata_from_freetypefont(struct PackedFile *pf);
int BLI_vfontchar_from_freetypefont(struct VFont *vfont, unsigned long character);

View File

@ -467,7 +467,14 @@ static int check_freetypefont(PackedFile *pf)
return success;
}
/**
* Construct a new VFontData structure from
* Freetype font data in a PackedFile.
*
* \param pf The font data.
* \retval A new VFontData structure, or NULL
* if unable to load.
*/
VFontData *BLI_vfontdata_from_freetypefont(PackedFile *pf)
{
VFontData *vfd = NULL;

View File

@ -47,6 +47,12 @@ struct _GSQueue {
int elem_size;
};
/**
* Create a new GSQueue.
*
* \param elem_size The size of the structures in the queue.
* \retval The new queue
*/
GSQueue *BLI_gsqueue_new(int elem_size)
{
GSQueue *gq = MEM_mallocN(sizeof(*gq), "gqueue_new");
@ -56,11 +62,17 @@ GSQueue *BLI_gsqueue_new(int elem_size)
return gq;
}
/**
* Query if the queue is empty
*/
bool BLI_gsqueue_is_empty(GSQueue *gq)
{
return (gq->head == NULL);
}
/**
* Query number elements in the queue
*/
int BLI_gsqueue_size(GSQueue *gq)
{
GSQueueElem *elem;
@ -72,10 +84,26 @@ int BLI_gsqueue_size(GSQueue *gq)
return size;
}
/**
* Access the item at the head of the queue
* without removing it.
*
* \param item_r A pointer to an appropriately
* sized structure (the size passed to BLI_gsqueue_new)
*/
void BLI_gsqueue_peek(GSQueue *gq, void *item_r)
{
memcpy(item_r, &gq->head[1], gq->elem_size);
}
/**
* Access the item at the head of the queue
* and remove it.
*
* \param item_r A pointer to an appropriately
* sized structure (the size passed to BLI_gsqueue_new).
* Can be NULL if desired.
*/
void BLI_gsqueue_pop(GSQueue *gq, void *item_r)
{
GSQueueElem *elem = gq->head;
@ -89,6 +117,13 @@ void BLI_gsqueue_pop(GSQueue *gq, void *item_r)
if (item_r) memcpy(item_r, &elem[1], gq->elem_size);
MEM_freeN(elem);
}
/**
* Push an element onto the tail of the queue.
*
* \param item A pointer to an appropriately
* sized structure (the size passed to BLI_gsqueue_new).
*/
void BLI_gsqueue_push(GSQueue *gq, void *item)
{
GSQueueElem *elem;
@ -109,6 +144,14 @@ void BLI_gsqueue_push(GSQueue *gq, void *item)
gq->tail = gq->tail->next = elem;
}
}
/**
* Push an element back onto the head of the queue (so
* it would be returned from the next call to BLI_gsqueue_pop).
*
* \param item A pointer to an appropriately
* sized structure (the size passed to BLI_gsqueue_new).
*/
void BLI_gsqueue_pushback(GSQueue *gq, void *item)
{
GSQueueElem *elem = MEM_mallocN(sizeof(*elem) + gq->elem_size, "gqueue_push");
@ -123,6 +166,9 @@ void BLI_gsqueue_pushback(GSQueue *gq, void *item)
}
}
/**
* Free the queue
*/
void BLI_gsqueue_free(GSQueue *gq)
{
while (gq->head) {

View File

@ -122,6 +122,7 @@ int BLI_stringdec(const char *string, char *head, char *tail, unsigned short *nu
if (found_digit) break;
}
}
if (found_digit) {
if (tail) strcpy(tail, &string[nume + 1]);
if (head) {
@ -131,13 +132,14 @@ int BLI_stringdec(const char *string, char *head, char *tail, unsigned short *nu
if (numlen) *numlen = nume - nums + 1;
return ((int)atoi(&(string[nums])));
}
if (tail) strcpy(tail, string + name_end);
if (head) {
strncpy(head, string, name_end);
head[name_end] = '\0';
else {
if (tail) strcpy(tail, string + name_end);
if (head) {
BLI_strncpy(head, string, name_end);
}
if (numlen) *numlen = 0;
return 0;
}
if (numlen) *numlen = 0;
return 0;
}
@ -1364,7 +1366,12 @@ void BLI_clean(char *path)
}
/**
* Replaces occurrences of from with to in *string.
* Change every \a from in \a string into \a to. The
* result will be in \a string
*
* \param string The string to work on
* \param from The character to replace
* \param to The character to replace with
*/
void BLI_char_switch(char *string, char from, char to)
{
@ -2060,11 +2067,17 @@ void BLI_init_program_path(const char *argv0)
BLI_split_dir_part(bprogname, bprogdir, sizeof(bprogdir));
}
/**
* Path to executable
*/
const char *BLI_program_path(void)
{
return bprogname;
}
/**
* Path to directory of executable
*/
const char *BLI_program_dir(void)
{
return bprogdir;
@ -2137,7 +2150,7 @@ void BLI_init_temporary_dir(char *userdir)
}
/**
* Returns the path to the temporary directory.
* Path to temporary directory (with trailing slash)
*/
const char *BLI_temporary_dir(void)
{
@ -2145,7 +2158,7 @@ const char *BLI_temporary_dir(void)
}
/**
* Puts in *dir path to OS-specific temporary directory.
* Path to the system temporary directory (with trailing slash)
*/
void BLI_system_temporary_dir(char *dir)
{