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

10 files changed, 209 insertions, 218 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) {
diff --git a/source/blender/blenlib/BLI_gsqueue.h b/source/blender/blenlib/BLI_gsqueue.h
index b9d8a8f9d14..e002545d189 100644
--- a/source/blender/blenlib/BLI_gsqueue.h
+++ b/source/blender/blenlib/BLI_gsqueue.h
@@ -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__ */
diff --git a/source/blender/blenlib/BLI_path_util.h b/source/blender/blenlib/BLI_path_util.h
index 136a51cf55e..1ba3c8b619c 100644
--- a/source/blender/blenlib/BLI_path_util.h
+++ b/source/blender/blenlib/BLI_path_util.h
@@ -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
diff --git a/source/blender/blenlib/BLI_vfontdata.h b/source/blender/blenlib/BLI_vfontdata.h
index ed7d10ab257..b0a57ee9288 100644
--- a/source/blender/blenlib/BLI_vfontdata.h
+++ b/source/blender/blenlib/BLI_vfontdata.h
@@ -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);
diff --git a/source/blender/blenlib/intern/freetypefont.c b/source/blender/blenlib/intern/freetypefont.c
index 2b3e2d233d9..24a8edae325 100644
--- a/source/blender/blenlib/intern/freetypefont.c
+++ b/source/blender/blenlib/intern/freetypefont.c
@@ -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;
diff --git a/source/blender/blenlib/intern/gsqueue.c b/source/blender/blenlib/intern/gsqueue.c
index 272f840296e..7f158bc3efb 100644
--- a/source/blender/blenlib/intern/gsqueue.c
+++ b/source/blender/blenlib/intern/gsqueue.c
@@ -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) {
diff --git a/source/blender/blenlib/intern/path_util.c b/source/blender/blenlib/intern/path_util.c
index c3bc35a906b..f9cf913157b 100644
--- a/source/blender/blenlib/intern/path_util.c
+++ b/source/blender/blenlib/intern/path_util.c
@@ -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)
 {