[Bf-blender-cvs] [8ccf999] master: BLI_dynstr: use function attributes and move comments into C file

[Campbell Barton]

Commit: 8ccf9993cfb87ff2646fbc8107d752c18540a1d5
Author: Campbell Barton
Date:   Sat Jun 14 18:40:48 2014 +1000
https://developer.blender.org/rB8ccf9993cfb87ff2646fbc8107d752c18540a1d5

BLI_dynstr: use function attributes and move comments into C file

===================================================================

M	source/blender/blenlib/BLI_dynstr.h
M	source/blender/blenlib/intern/BLI_dynstr.c

===================================================================

diff --git a/source/blender/blenlib/BLI_dynstr.h b/source/blender/blenlib/BLI_dynstr.h
index 61bdf23..484cddd 100644
--- a/source/blender/blenlib/BLI_dynstr.h
+++ b/source/blender/blenlib/BLI_dynstr.h
@@ -47,73 +47,17 @@ struct DynStr;
 /** The abstract DynStr type */
 typedef struct DynStr DynStr;
 
-/**
- * Create a new DynStr.
- *
- * \return Pointer to a new DynStr.
- */
-DynStr *BLI_dynstr_new(void);
+DynStr *BLI_dynstr_new(void) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
+void    BLI_dynstr_append(DynStr *__restrict ds, const char *cstr) ATTR_NONNULL();
+void    BLI_dynstr_nappend(DynStr *__restrict ds, const char *cstr, int len) ATTR_NONNULL();
 
-/**
- * Append a c-string to a DynStr.
- *
- * \param ds The DynStr to append to.
- * \param cstr The c-string to append.
- */
-void    BLI_dynstr_append(DynStr *ds, const char *cstr);
+void    BLI_dynstr_appendf(DynStr *__restrict ds, const char *__restrict format, ...) ATTR_PRINTF_FORMAT(2, 3) ATTR_NONNULL(1, 2);
+void    BLI_dynstr_vappendf(DynStr *__restrict ds, const char *__restrict format, va_list args) ATTR_PRINTF_FORMAT(2, 0) ATTR_NONNULL(1, 2);
 
-/**
- * Append a length clamped c-string to a DynStr.
- *
- * \param ds The DynStr to append to.
- * \param cstr The c-string to append.
- * \param len The maximum length of the c-string to copy.
- */
-void    BLI_dynstr_nappend(DynStr *ds, const char *cstr, int len);
-
-/**
- * Append a c-string to a DynStr, but with formatting like printf.
- *
- * \param ds The DynStr to append to.
- * \param format The printf format string to use.
- */
-void    BLI_dynstr_appendf(DynStr *ds, const char *format, ...) ATTR_PRINTF_FORMAT(2, 3);
-void    BLI_dynstr_vappendf(DynStr *ds, const char *format, va_list args) ATTR_PRINTF_FORMAT(2, 0);
-
-/**
- * Find the length of a DynStr.
- *
- * \param ds The DynStr of interest.
- * \return The length of \a ds.
- */
-int     BLI_dynstr_get_len(DynStr *ds);
-
-/**
- * Get a DynStr's contents as a c-string.
- * <i> The returned c-string should be freed
- * using MEM_freeN. </i>
- *
- * \param ds The DynStr of interest.
- * \return The contents of \a ds as a c-string.
- */
-char *BLI_dynstr_get_cstring(DynStr *ds);
-
-/**
- * Get a DynStr's contents as a c-string.
- * <i> The str argument must be allocated to be at
- * least the size of BLI_dynstr_get_len(ds) + 1. </i>
- *
- * \param ds The DynStr of interest.
- * \param str The string to fill.
- */
-void    BLI_dynstr_get_cstring_ex(DynStr *ds, char *str);
-
-/**
- * Free the DynStr
- *
- * \param ds The DynStr to free.
- */
-void    BLI_dynstr_free(DynStr *ds);
+int     BLI_dynstr_get_len(DynStr *ds) ATTR_NONNULL();
+char   *BLI_dynstr_get_cstring(DynStr *ds) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
 
-#endif
+void    BLI_dynstr_get_cstring_ex(DynStr *__restrict ds, char *__restrict str) ATTR_NONNULL();
+void    BLI_dynstr_free(DynStr *ds) ATTR_NONNULL();
 
+#endif  /* __BLI_DYNSTR_H__ */
diff --git a/source/blender/blenlib/intern/BLI_dynstr.c b/source/blender/blenlib/intern/BLI_dynstr.c
index 25607d8..5c95542 100644
--- a/source/blender/blenlib/intern/BLI_dynstr.c
+++ b/source/blender/blenlib/intern/BLI_dynstr.c
@@ -68,6 +68,11 @@ struct DynStr {
 
 /***/
 
+/**
+ * Create a new DynStr.
+ *
+ * \return Pointer to a new DynStr.
+ */
 DynStr *BLI_dynstr_new(void)
 {
 	DynStr *ds = MEM_mallocN(sizeof(*ds), "DynStr");
@@ -77,6 +82,12 @@ DynStr *BLI_dynstr_new(void)
 	return ds;
 }
 
+/**
+ * Append a c-string to a DynStr.
+ *
+ * \param ds The DynStr to append to.
+ * \param cstr The c-string to append.
+ */
 void BLI_dynstr_append(DynStr *ds, const char *cstr)
 {
 	DynStrElem *dse = malloc(sizeof(*dse));
@@ -94,6 +105,13 @@ void BLI_dynstr_append(DynStr *ds, const char *cstr)
 	ds->curlen += cstrlen;
 }
 
+/**
+ * Append a length clamped c-string to a DynStr.
+ *
+ * \param ds The DynStr to append to.
+ * \param cstr The c-string to append.
+ * \param len The maximum length of the c-string to copy.
+ */
 void BLI_dynstr_nappend(DynStr *ds, const char *cstr, int len)
 {
 	DynStrElem *dse = malloc(sizeof(*dse));
@@ -165,6 +183,12 @@ void BLI_dynstr_vappendf(DynStr *ds, const char *format, va_list args)
 	}
 }
 
+/**
+ * Append a c-string to a DynStr, but with formatting like printf.
+ *
+ * \param ds The DynStr to append to.
+ * \param format The printf format string to use.
+ */
 void BLI_dynstr_appendf(DynStr *ds, const char *format, ...)
 {
 	va_list args;
@@ -221,11 +245,25 @@ void BLI_dynstr_appendf(DynStr *ds, const char *format, ...)
 	}
 }
 
+/**
+ * Find the length of a DynStr.
+ *
+ * \param ds The DynStr of interest.
+ * \return The length of \a ds.
+ */
 int BLI_dynstr_get_len(DynStr *ds)
 {
 	return ds->curlen;
 }
 
+/**
+ * Get a DynStr's contents as a c-string.
+ * <i> The str argument must be allocated to be at
+ * least the size of BLI_dynstr_get_len(ds) + 1. </i>
+ *
+ * \param ds The DynStr of interest.
+ * \param str The string to fill.
+ */
 void BLI_dynstr_get_cstring_ex(DynStr *ds, char *rets)
 {
 	char *s;
@@ -242,6 +280,14 @@ void BLI_dynstr_get_cstring_ex(DynStr *ds, char *rets)
 	rets[ds->curlen] = '\0';
 }
 
+/**
+ * Get a DynStr's contents as a c-string.
+ * <i> The returned c-string should be freed
+ * using MEM_freeN. </i>
+ *
+ * \param ds The DynStr of interest.
+ * \return The contents of \a ds as a c-string.
+ */
 char *BLI_dynstr_get_cstring(DynStr *ds)
 {
 	char *rets = MEM_mallocN(ds->curlen + 1, "dynstr_cstring");
@@ -249,6 +295,11 @@ char *BLI_dynstr_get_cstring(DynStr *ds)
 	return rets;
 }
 
+/**
+ * Free the DynStr
+ *
+ * \param ds The DynStr to free.
+ */
 void BLI_dynstr_free(DynStr *ds)
 {
 	DynStrElem *dse;