From 216abbc12149668c71e400c19d1f60a507fb68c8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kacper=20Michaj=C5=82ow?= <kasper93@gmail.com>
Date: Sun, 29 Sep 2024 16:26:44 +0200
Subject: [PATCH] bstr: add missing function docs

---
 misc/bstr.c |  6 ------
 misc/bstr.h | 43 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+), 6 deletions(-)

diff --git a/misc/bstr.c b/misc/bstr.c
index 120abef8fe..0b82244bca 100644
--- a/misc/bstr.c
+++ b/misc/bstr.c
@@ -361,11 +361,6 @@ static void resize_append(void *talloc_ctx, bstr *s, size_t append_min)
     }
 }
 
-// Append the string, so that *s = *s + append. s->start is expected to be
-// a talloc allocation (which can be realloced) or NULL.
-// This function will always implicitly append a \0 after the new string for
-// convenience.
-// talloc_ctx will be used as parent context, if s->start is NULL.
 void bstr_xappend(void *talloc_ctx, bstr *s, bstr append)
 {
     if (!append.len)
@@ -385,7 +380,6 @@ int bstr_xappend_asprintf(void *talloc_ctx, bstr *s, const char *fmt, ...)
     return ret;
 }
 
-// Exactly as bstr_xappend(), but with a formatted string.
 int bstr_xappend_vasprintf(void *talloc_ctx, bstr *s, const char *fmt,
                            va_list ap)
 {
diff --git a/misc/bstr.h b/misc/bstr.h
index d279a3a088..a586ef3442 100644
--- a/misc/bstr.h
+++ b/misc/bstr.h
@@ -135,9 +135,52 @@ static inline struct bstr bstr_getline(struct bstr str, struct bstr *rest)
 // and will remove the trailing \n or \r\n sequence.
 struct bstr bstr_strip_linebreaks(struct bstr str);
 
+/**
+ * @brief Append a string to the existing bstr.
+ *
+ * This function appends the content of the `append` bstr to the `s` bstr.
+ * `s->start` is expected to be a talloc allocation (which can be resized) or NULL.
+ * A null terminator ('\0') is always appended for convenience. If `s->start`
+ * is NULL, the `talloc_ctx` will be used as the parent context to allocate
+ * memory.
+ *
+ * @param talloc_ctx  The parent talloc context.
+ * @param s           The destination bstr to which the `append` string is appended.
+ * @param append      The string to append to `s`.
+ */
 void bstr_xappend(void *talloc_ctx, bstr *s, bstr append);
+
+/**
+ * @brief Append a formatted string to the existing bstr.
+ *
+ * This function works like bstr_xappend() but appends a formatted string using
+ * a format string and additional arguments. The formatted string is created
+ * using vsnprintf. The function takes care of resizing the destination
+ * buffer if necessary.
+ *
+ * @param talloc_ctx  The parent talloc context.
+ * @param s           The destination bstr to which the formatted string is appended.
+ * @param fmt         The format string (same as in vsnprintf).
+ * @param ...         Additional arguments for the format string.
+ * @return            The number of characters added (excluding the null terminator)
+ *                    or a negative value on error.
+ */
 int bstr_xappend_asprintf(void *talloc_ctx, bstr *s, const char *fmt, ...)
     PRINTF_ATTRIBUTE(3, 4);
+
+/**
+ * @brief Append a formatted string to the existing bstr using a va_list.
+ *
+ * This function is identical to bstr_xappend_asprintf() but takes a `va_list`
+ * instead of a variable number of arguments.
+ *
+ * @param talloc_ctx  The parent talloc context.
+ * @param s           The destination bstr to which the formatted string is appended.
+ * @param fmt         The format string (same as in printf).
+ * @param ap          The `va_list` containing the arguments for the format string.
+ * @return            The number of characters added (excluding the null terminator)
+ *                    or a negative value on error.
+ */
 int bstr_xappend_vasprintf(void *talloc_ctx, bstr *s, const char *fmt, va_list va)
     PRINTF_ATTRIBUTE(3, 0);