Improve doxygen-generated documentation

laurencelundblade · Dec 15, 2024 · f775466 · f775466
1 parent b6c7da4
commit f775466
Show file tree

Hide file tree

Showing 9 changed files with 855 additions and 463 deletions.
diff --git a/doc/Numbers.md b/doc/Numbers.md
@@ -1,6 +1,4 @@
 
-@file Numbers.md
-
 @anchor BigNumbers
 
 # Big Numbers

diff --git a/doc/Serialization.md b/doc/Serialization.md
@@ -1,4 +1,3 @@
-@file Serialization.md
 
 @anchor Serialization
 

diff --git a/doc/Tagging.md b/doc/Tagging.md
@@ -1,4 +1,3 @@
-@file Tagging.md
 
 @anchor CBORTags
 

diff --git a/doc/mainpage.dox b/doc/mainpage.dox
@@ -0,0 +1,15 @@
+/*! @mainpage QCBOR Documentation
+
+@par Table of Contents
+
+API Reference
+- Encoding functions: @ref inc/qcbor/qcbor_encode.h "qcbor_encode.h"
+- Main/Basic decode functions: @ref inc/qcbor/qcbor_main_decode.h "qcbor_main_decode.h"
+- Spiffy decode functions: @ref inc/qcbor/qcbor_spiffy_decode.h "qcbor_spiffy_decode.h"
+- 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"
+
+Subject Matter
+- @ref SpiffyDecode
+
+*/
diff --git a/doxygen/Doxyfile b/doxygen/Doxyfile
diff --git a/inc/qcbor/qcbor_main_decode.h b/inc/qcbor/qcbor_main_decode.h
@@ -463,7 +463,8 @@ typedef enum {
  * and warning. */
 #define QCBOR_TYPE_65BIT_NEG_INT 28
 
-#define QCBOR_TYPE_BREAK         31 /* Used internally; never returned */
+/** @private  Used internally; never returned  */
+#define QCBOR_TYPE_BREAK         31
 
 /** For @ref QCBOR_DECODE_MODE_MAP_AS_ARRAY decode mode, a map that is
  *  being traversed as an array. See QCBORDecode_Init() */
@@ -516,7 +517,8 @@ typedef enum {
 /* 79, 80, 82, 83 is used above for decimal fraction and big float */
 
 
-#define QCBOR_TYPE_TAG_NUMBER 127 /* Used internally; never returned */
+/** @private  Used internally; never returned  */
+#define QCBOR_TYPE_TAG_NUMBER 127
 
 /** Start of user-defined data types. The range is mainly for user-defined tag content
  * decoders. See QCBORTagContentCallBack */
@@ -1447,23 +1449,23 @@ QCBORDecode_CompatibilityV1(QCBORDecodeContext *pCtx);
 
 
 /* ========================================================================= *
- *    BEGINNING OF PRIVATE AND INLINE IMPLEMENTATION                             *
+ *    BEGINNING OF PRIVATE AND INLINE IMPLEMENTATION                         *
  * ========================================================================= */
 
-/* Semi-private function. See qcbor_decode.c */
+/** @private  Semi-private function. See qcbor_decode.c */
 QCBORError
 QCBORDecode_Private_GetNextTagContent(QCBORDecodeContext *pMe,
                                       QCBORItem          *pDecodedItem);
 
-/* Semi-private function. See qcbor_decode.c */
+/** @private  Semi-private function. See qcbor_decode.c */
 void
 QCBORDecode_Private_GetItemInMapNoCheckSZ(QCBORDecodeContext *pMe,
                                           const char         *szLabel,
                                           const uint8_t       uQcborType,
                                           QCBORItem          *pItem,
                                           size_t             *puOffset);
 
-/* Semi-private function. See qcbor_decode.c */
+/** @private  Semi-private function. See qcbor_decode.c */ // TODO: this a next are spiffy
 void
 QCBORDecode_Private_GetItemInMapNoCheckN(QCBORDecodeContext *pMe,
                                          const int64_t       nLabel,
@@ -1472,26 +1474,26 @@ QCBORDecode_Private_GetItemInMapNoCheckN(QCBORDecodeContext *pMe,
                                          size_t             *puOffset);
 
 
-/* Semi-private function. See qcbor_main_decode.c */
+/** @private  Semi-private function. See qcbor_decode.c */
 uint64_t
 QCBORDecode_Private_UnMapTagNumber(const QCBORDecodeContext *pMe,
                                    const uint16_t            uMappedTagNumber);
 
-/* Semi-private function. See qcbor_main_decode.c */
+/** @private  Semi-private function. See qcbor_decode.c */
 QCBORError
 QCBORDecode_Private_ConsumeItem(QCBORDecodeContext *pMe,
                                 const QCBORItem    *pItemToConsume,
                                 bool               *pbBreak,
                                 uint8_t            *puNextNestLevel);
 
-/* Semi-private function. See qcbor_main_decode.c */
+/** @private  Semi-private function. See qcbor_decode.c */
 QCBORError
 QCBORDecode_Private_GetItemChecks(QCBORDecodeContext *pMe,
                                   QCBORError          uErr,
                                   const size_t        uOffset,
                                   QCBORItem          *pDecodedItem);
 
-/* Semi-private function. See qcbor_decode.c */
+/** @private  Semi-private function. See qcbor_decode.c */
 QCBORError
 QCBORDecode_Private_NestLevelAscender(QCBORDecodeContext *pMe,
                                       bool                bMarkEnd,
@@ -1559,6 +1561,7 @@ QCBORDecode_SetError(QCBORDecodeContext *pMe, QCBORError uError)
 }
 
 
+/** @private */
 static inline void
 QCBORDecode_Private_SaveTagNumbers(QCBORDecodeContext *pMe, const QCBORItem *pItem)
 {
@@ -1570,7 +1573,7 @@ QCBORDecode_Private_SaveTagNumbers(QCBORDecodeContext *pMe, const QCBORItem *pIt
 #endif /* ! QCBOR_DISABLE_TAGS */
 }
 
-
+/** @private */
 static inline void
 QCBORDecode_Private_GetAndTell(QCBORDecodeContext *pMe, QCBORItem *Item, size_t *uOffset)
 {

diff --git a/inc/qcbor/qcbor_number_decode.h b/inc/qcbor/qcbor_number_decode.h
@@ -86,11 +86,13 @@ static void
 QCBORDecode_GetInt64(QCBORDecodeContext *pCtx,
                      int64_t            *pnValue);
 
+/** See QCBORDecode_GetInt64(). */
 static void
 QCBORDecode_GetInt64InMapN(QCBORDecodeContext *pCtx,
                            int64_t             nLabel,
                            int64_t            *pnValue);
 
+/** See QCBORDecode_GetInt64(). */
 static void
 QCBORDecode_GetInt64InMapSZ(QCBORDecodeContext *pCtx,
                             const char         *szLabel,
@@ -1419,45 +1421,45 @@ QCBORDecode_GetBigFloatBigInMapSZ(QCBORDecodeContext *pCtx,
  * ========================================================================= */
 
 
-/* Semi-private. See qcbor_number_decode.c */
+/** @private  Semi-private. See qcbor_number_decode.c */
 void
 QCBORDecode_Private_GetUInt64Convert(QCBORDecodeContext           *pCtx,
                                      enum QCBORDecodeNumberConvert uConvertTypes,
                                      uint64_t                     *puValue,
                                      QCBORItem                    *pItem);
 
-/* Semi-private. See qcbor_number_decode.c */
+/** @private  Semi-private. See qcbor_number_decode.c */
 void
 QCBORDecode_Private_GetUInt64ConvertInMapN(QCBORDecodeContext           *pCtx,
                                            int64_t                       nLabel,
                                            enum QCBORDecodeNumberConvert uConvertTypes,
                                            uint64_t                     *puValue,
                                            QCBORItem                    *pItem);
 
-/* Semi-private. See qcbor_number_decode.c */
+/** @private  Semi-private. See qcbor_number_decode.c */
 void
 QCBORDecode_Private_GetUInt64ConvertInMapSZ(QCBORDecodeContext           *pCtx,
                                             const char                   *szLabel,
                                             enum QCBORDecodeNumberConvert uConvertTypes,
                                             uint64_t                     *puValue,
                                             QCBORItem                    *pItem);
 
-/* Semi-private. See qcbor_number_decode.c */
+/** @private  Semi-private. See qcbor_number_decode.c */
 void
 QCBORDecode_Private_GetInt64Convert(QCBORDecodeContext           *pCtx,
                                     enum QCBORDecodeNumberConvert uConvertTypes,
                                     int64_t                      *pnValue,
                                     QCBORItem                    *pItem);
 
-/* Semi-private. See qcbor_number_decode.c */
+/** @private  Semi-private. See qcbor_number_decode.c */
 void
 QCBORDecode_Private_GetInt64ConvertInMapN(QCBORDecodeContext           *pCtx,
                                           int64_t                       nLabel,
                                           enum QCBORDecodeNumberConvert uConvertTypes,
                                           int64_t                      *pnValue,
                                           QCBORItem                    *pItem);
 
-/* Semi-private. See qcbor_number_decode.c */
+/** @private  Semi-private. See qcbor_number_decode.c */
 void
 QCBORDecode_Private_GetInt64ConvertInMapSZ(QCBORDecodeContext           *pCtx,
                                            const char                   *szLabel,
@@ -1467,22 +1469,22 @@ QCBORDecode_Private_GetInt64ConvertInMapSZ(QCBORDecodeContext           *pCtx,
 
 
 #ifndef USEFULBUF_DISABLE_ALL_FLOAT
-/* Semi-private. See qcbor_number_decode.c */
+/** @private  Semi-private. See qcbor_number_decode.c */
 void
 QCBORDecode_Private_GetDoubleConvert(QCBORDecodeContext           *pCtx,
                                      enum QCBORDecodeNumberConvert uConvertTypes,
                                      double                       *pValue,
                                      QCBORItem                    *pItem);
 
-/* Semi-private. See qcbor_number_decode.c */
+/** @private  Semi-private. See qcbor_number_decode.c */
 void
 QCBORDecode_Private_GetDoubleConvertInMapN(QCBORDecodeContext           *pCtx,
                                            int64_t                       nLabel,
                                            enum QCBORDecodeNumberConvert uConvertTypes,
                                            double                       *pdValue,
                                            QCBORItem                    *pItem);
 
-/* Semi-private. See qcbor_number_decode.c */
+/** @private  Semi-private. See qcbor_number_decode.c */
 void
 QCBORDecode_Private_GetDoubleConvertInMapSZ(QCBORDecodeContext           *pCtx,
                                             const char                   *szLabel,
Original file line number	Diff line number	Diff line change
		@@ -1,4 +1,3 @@
		@file Serialization.md

		@anchor Serialization

Expand Down