BLI_dynstr: use function attributes and move comments into C file

1 files changed, 51 insertions, 0 deletions

diff --git a/source/blender/blenlib/intern/BLI_dynstr.c b/source/blender/blenlib/intern/BLI_dynstr.c
index 25607d8b499..5c9554203cb 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;