lib/util: Change comments to Doxygen in data_blob.h

Signed-off-by: Pavel Filipenský <pfilipensky@samba.org>
Reviewed-by: Andreas Schneider <asn@samba.org>

diff --git a/lib/util/data_blob.h b/lib/util/data_blob.h
index 9309230aca173163b0c67357f724ef03a00a11fb..87a522ccd9aca760a1746c4bcc7db80fee9a94bc 100644 (file)
--- 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_ */