diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-12-09 12:01:44 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-12-09 12:01:44 +0300 |
commit | 9e365069afe156f33fadfad9705e1325f894cd54 (patch) | |
tree | 78373044d029feb51f987b45208e0c1a36958625 /source/blender/blenlib/BLI_dynstr.h | |
parent | d8b42751625c915113b64f5a2d9c72f19f009fee (diff) |
Cleanup: move public doc-strings into headers for 'blenlib'
- Added space below non doc-string comments to make it clear
these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.
- Minor improvements to doc-strings.
Ref T92709
Diffstat (limited to 'source/blender/blenlib/BLI_dynstr.h')
-rw-r--r-- | source/blender/blenlib/BLI_dynstr.h | 62 |
1 files changed, 61 insertions, 1 deletions
diff --git a/source/blender/blenlib/BLI_dynstr.h b/source/blender/blenlib/BLI_dynstr.h index 4df773c7cc6..90d93f29bcb 100644 --- a/source/blender/blenlib/BLI_dynstr.h +++ b/source/blender/blenlib/BLI_dynstr.h @@ -39,25 +39,85 @@ extern "C" { struct DynStr; -/** The abstract DynStr type */ +/** The abstract DynStr type. */ typedef struct DynStr DynStr; +/** + * Create a new #DynStr. + * + * \return Pointer to a new #DynStr. + */ DynStr *BLI_dynstr_new(void) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT; +/** + * Create a new #DynStr. + * + * \return Pointer to a new #DynStr. + */ DynStr *BLI_dynstr_new_memarena(void) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT; +/** + * 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 *__restrict ds, const char *cstr) ATTR_NONNULL(); +/** + * 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 *__restrict ds, const char *cstr, int len) ATTR_NONNULL(); +/** + * 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 *__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); +/** + * Find the length of a #DynStr. + * + * \param ds: The #DynStr of interest. + * \return The length of \a ds. + */ int BLI_dynstr_get_len(const DynStr *ds) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); +/** + * Get a #DynStr's contents as a c-string. + * \return The c-string which must be freed using #MEM_freeN. + * + * \param ds: The #DynStr of interest. + * \return The contents of \a ds as a c-string. + */ char *BLI_dynstr_get_cstring(const DynStr *ds) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); +/** + * Get a #DynStr's contents as a c-string. + * The \a rets argument must be allocated to be at + * least the size of `BLI_dynstr_get_len(ds) + 1`. + * + * \param ds: The DynStr of interest. + * \param rets: The string to fill. + */ void BLI_dynstr_get_cstring_ex(const DynStr *__restrict ds, char *__restrict rets) ATTR_NONNULL(); +/** + * Clear the #DynStr + * + * \param ds: The DynStr to clear. + */ void BLI_dynstr_clear(DynStr *ds) ATTR_NONNULL(); +/** + * Free the #DynStr + * + * \param ds: The DynStr to free. + */ void BLI_dynstr_free(DynStr *ds) ATTR_NONNULL(); #ifdef __cplusplus |