Documentation/Doxygen fixes for UsefulBuf
diff --git a/doc/mainpage.dox b/doc/mainpage.dox
index 2a723ce..db8054c 100644
--- a/doc/mainpage.dox
+++ b/doc/mainpage.dox
@@ -1,10 +1,13 @@
/*! @mainpage QCBOR Documentation
+QCBOR is available for download @ref https://github.com/laurencelundblade/QCBOR "here on GitHub"
+
@par Table of Contents
-API Reference
+API Reference:
- Common
- Error codes and common constants: @ref inc/qcbor/qcbor_common.h "qcbor_common.h"
+ - Functions for managing buffers of binary data: @ref inc/qcbor/UsefulBuf.h "UsefulBuf.h"
- Encoding
- Main/Basic encode functions: @ref inc/qcbor/qcbor_main_encode.h "qcbor_main_encode.h"
- Number encode functions: @ref inc/qcbor/qcbor_number_encode.h "qcbor_number_encode.h"
@@ -15,9 +18,11 @@
- Tag decode functions: @ref inc/qcbor/qcbor_tag_decode.h "qcbor_tag_decode.h"
- Number decode functions: @ref inc/qcbor/qcbor_number_decode.h "qcbor_number_decode.h"
-Note: the API Reference is largely complete, the subject matter below is partial
+Note:
+- This is for QCBOR v2, but v1 is largely compatible
+- the API Reference is largely complete, the subject matter below is partial
-Subject Matter
+Subject Matter:
- @ref Overview "QCBOR overview and implementation limits"
- @ref Building "Building QCBOR with make and cmake"
- @ref CodeSize "Minimizing the amount of code linked and disabling features"
diff --git a/inc/qcbor/UsefulBuf.h b/inc/qcbor/UsefulBuf.h
index 80b5c78..f3b86da 100644
--- a/inc/qcbor/UsefulBuf.h
+++ b/inc/qcbor/UsefulBuf.h
@@ -43,6 +43,7 @@
when who what, where, why
-------- ---- --------------------------------------------------
+ 12/31/2024 llundblade Minor documentation tweaks for Doxygen.
08/31/2024 llundblade Add UsefulBufC_NTH_BYTE().
08/14/2024 llundblade Add UsefulOutBuf_RetrieveOutputStorage().
08/13/2024 llundblade Add UsefulInputBuf_RetrieveUndecodedInput().
@@ -498,7 +499,15 @@
static inline UsefulBufC UsefulBuf_FromSZ(const char *szString);
-/* Get the nth byte from a UsefulBufC. There's no length check! */
+/**
+ * @brief Get the nth byte from a UsefulBufC.
+ *
+ * @param[in] UBC UsefulBufC from which to get byte
+ * @param[in] n Index of byte to get
+ *
+ * WARNING: this doesn't check that @c is within the UsefulBufC. This point
+ * of this is to have the ugly cast in just one place.
+ */
#define UsefulBufC_NTH_BYTE(UBC, n) (((const uint8_t *)(UBC.ptr))[n])
@@ -864,11 +873,13 @@
* - 16 bytes (15 bytes plus alignment padding) on a 32-bit CPU
*/
typedef struct useful_out_buf {
- /* PRIVATE DATA STRUCTURE */
- UsefulBuf UB; /* Memory that is being output to */
- size_t data_len; /* length of the valid data, the insertion point */
- uint16_t magic; /* Used to detect corruption and lack
- * of initialization */
+ /** @private Memory that is being output to */
+ UsefulBuf UB;
+ /** @private length of the valid data, the insertion point */
+ size_t data_len;
+ /** @private Magic number to detect lack of initalization/corruption */
+ uint16_t magic;
+ /** @private Used to detect corruption and lack of initialization */
uint8_t err;
} UsefulOutBuf;
@@ -881,7 +892,7 @@
* returned @ref UsefulBufC has the size.
*
* As one can see, this is just a NULL pointer and very large size.
- * The NULL pointer tells UsefulOutputBuf to not copy any data.
+ * The NULL pointer tells @ref UsefulOutBuf to not copy any data.
*/
#ifdef __cplusplus
#define SizeCalculateUsefulBuf {NULL, SIZE_MAX}
@@ -1035,7 +1046,7 @@
/**
* @brief Insert a byte into the @ref UsefulOutBuf.
*
- * @param[in] pUOutBuf Pointer to the UsefulOutBuf.
+ * @param[in] pUOutBuf Pointer to the @ref UsefulOutBuf.
* @param[in] byte Bytes to insert.
* @param[in] uPos Index in output buffer at which to insert.
*
@@ -1348,7 +1359,7 @@
* UsefulOutBuf how much was written.
*
* Warning: this bypasses the buffer safety provided by
- * UsefulOutBuf!
+ * @ref UsefulOutBuf!
*/
static inline UsefulBuf
UsefulOutBuf_GetOutPlace(UsefulOutBuf *pUOutBuf);
@@ -1366,14 +1377,14 @@
* with UsefulOutBuf_GetOutPlace().
*
* Warning: this bypasses the buffer safety provided by
- * UsefulOutBuf!
+ * @ref UsefulOutBuf!
*/
void
UsefulOutBuf_Advance(UsefulOutBuf *pUOutBuf, size_t uAmount);
/**
- * @brief Returns the data put into a UsefulOutBuf.
+ * @brief Returns the data put into a @ref UsefulOutBuf.
*
* @param[in] pUOutBuf Pointer to the @ref UsefulOutBuf.
*
@@ -1391,7 +1402,7 @@
/**
- * @brief Copy out the data put into a UsefulOutBuf.
+ * @brief Copy out the data put into a @ref UsefulOutBuf.
*
* @param[in] pUOutBuf Pointer to the @ref UsefulOutBuf.
* @param[out] Dest The destination buffer to copy into.
@@ -1407,7 +1418,7 @@
/**
- * @brief Returns data starting at an offset that was put into a UsefulOutBuf.
+ * @brief Returns data starting at an offset that was put into a @ref UsefulOutBuf.
*
* @param[in] pUOutBuf Pointer to the @ref UsefulOutBuf.
* @param[in] uOffset Offset to bytes to return.
@@ -1430,7 +1441,7 @@
UsefulOutBuf_OutUBufOffset(UsefulOutBuf *pUOutBuf, size_t uOffset);
-/*
+/**
* @brief Return a substring of the output data.
*
* @param[in] pUOutBuf Pointer to the @ref UsefulOutBuf.
@@ -1573,13 +1584,17 @@
* - 32-bit machine: 8 + 4 + 2 + 1 (+ 1 byte padding to align) = 16 bytes
*/
typedef struct useful_input_buf {
- /* PRIVATE DATA STRUCTURE */
- UsefulBufC UB; /* Data being parsed */
- size_t cursor; /* Current offset in data being parse */
- uint16_t magic; /* Check for corrupted or uninitialized UsefulInputBuf */
- uint8_t err; /* Set request goes off end or magic number is bad */
+ /** @private Data being parsed */
+ UsefulBufC UB;
+ /** @private Current offset in data being parse */
+ size_t cursor;
+ /** @private Check for corrupted or uninitialized UsefulInputBuf */
+ uint16_t magic;
+ /** @private Set if request goes off end or magic number is bad */
+ uint8_t err;
} UsefulInputBuf;
+/** @private The actual value of @c magic in UsefulInputBuf. */
#define UIB_MAGIC (0xB00F)