From 94fc617a5475343b89d3e1bf7743575b923350b6 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Pavel=20Filipensk=C3=BD?= <pfilipensky@samba.org>
Date: Wed, 3 Dec 2025 20:52:17 +0100
Subject: [PATCH] lib/util: Change comments to Doxygen in data_blob.h
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

Signed-off-by: Pavel Filipenský <pfilipensky@samba.org>
Reviewed-by: Andreas Schneider <asn@samba.org>
---
 lib/util/data_blob.h | 73 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 64 insertions(+), 9 deletions(-)

diff --git a/lib/util/data_blob.h b/lib/util/data_blob.h
index 9309230aca1..87a522ccd9a 100644
--- a/lib/util/data_blob.h
+++ b/lib/util/data_blob.h
@@ -34,6 +34,13 @@
 #include <stdbool.h>
 #include <stdint.h>
 
+/**
+ * @defgroup data_blob The data_blob API
+ * @brief The defines the data_blob API and provides function working with it.
+ *
+ * @{
+ */
+
 /* used to hold an arbitrary blob of data */
 typedef struct datablob {
 	uint8_t *data;
@@ -44,29 +51,75 @@ typedef struct datablob {
    a fair bit of code */
 #define ldb_val datablob
 
+#ifdef DOXYGEN
+/**
+ * @brief Construct a data blob using a new top level TALLOC_CTX.
+ *        You can pass NULL for ptr and get a blank data blob.
+ *        Blob must be freed with data_blob_free().
+ */
+DATA_BLOB data_blob(const void *ptr, size_t size);
+#else
 #define data_blob(ptr, size) data_blob_named(ptr, size, "DATA_BLOB: " __location__)
+#endif
+
+#ifdef DOXYGEN
+/**
+ * @brief Construct a data blob using supplied TALLOC_CTX.
+ *        You can pass NULL for ptr and get a blank data blob.
+ */
+DATA_BLOB data_blob_talloc(TALLOC_CTX *mem_ctx, const void *ptr, size_t size);
+#else
 #define data_blob_talloc(ctx, ptr, size) data_blob_talloc_named(ctx, ptr, size, "DATA_BLOB: " __location__)
+#endif
+
+#ifdef DOXYGEN
+/**
+ * @brief Construct a data blob using supplied TALLOC_CTX.
+ *        Data is initialized using provided blob.
+ */
+DATA_BLOB data_blob_dup_talloc(TALLOC_CTX *mem_ctx, DATA_BLOB blob);
+#else
 #define data_blob_dup_talloc(ctx, blob) data_blob_talloc_named(ctx, (blob).data, (blob).length, "DATA_BLOB: " __location__)
+#endif
 
+#ifdef DOXYGEN
 /**
- construct a data blob, must be freed with data_blob_free()
- you can pass NULL for p and get a blank data blob
-**/
+ * @brief Construct a data blob using a new top level TALLOC_CTX.
+ *        You can pass NULL for ptr and get a blank data blob.
+ *        Blob must be freed with data_blob_free().
+ */
+DATA_BLOB data_blob_named(const void *ptr, size_t size, const char *name);
+#else
 #define data_blob_named(ptr, size, name) \
 	data_blob_talloc_named(NULL, (ptr), (size), name)
+#endif
 
 /**
- construct a data blob, using supplied TALLOC_CTX
-**/
+ * @brief Construct a data blob using supplied TALLOC_CTX and using data
+ * supplied via ptr and length and give it an explicit talloc chunk name.
+ */
+/**
+ * @brief Construct a data blob, using data supplied pointer and length
+ *
+ * @param mem_ctx  memory context, if NULL a new top level context is used
+ * @param p        pointer to input data, you can pass NULL and get a blank data
+ * blob
+ * @param length   data length
+ * @param name     talloc chunk name
+ * @return         the blob
+ */
 _PUBLIC_ DATA_BLOB data_blob_talloc_named(TALLOC_CTX *mem_ctx, const void *p, size_t length, const char *name);
 
+#ifdef DOXYGEN
 /**
- construct a zero data blob, using supplied TALLOC_CTX.
- use this sparingly as it initialises data - better to initialise
- yourself if you want specific data in the blob
-**/
+ * @brief Construct a data blob using supplied TALLOC_CTX.
+ *        Data is initialized with zeros.
+ */
+DATA_BLOB data_blob_talloc_zero(TALLOC_CTX *mem_ctx, size_t size);
+#else
 #define data_blob_talloc_zero(ctx, size) \
 	_data_blob_talloc_zero((ctx), (size), "DATA_BLOB: " __location__)
+#endif
 
 /**
 free a data blob
@@ -154,4 +207,6 @@ _PUBLIC_ bool data_blob_pad(TALLOC_CTX *mem_ctx, DATA_BLOB *blob,
 
 extern const DATA_BLOB data_blob_null;
 
+/** @} */ /* data_blob */
+
 #endif /* _SAMBA_DATABLOB_H_ */
-- 
2.47.3