docs(src): add examples alias and general cleanup

docs/Doxyfile

@@ -24,9 +24,11 @@
 # must be first
 DOXYFILE_ENCODING = UTF-8
 
-# https://breathe.readthedocs.io/en/latest/markups.html#aliases
-ALIASES = "rst=^^\verbatim embed:rst:leading-asterisk^^"
-ALIASES += "endrst=\endverbatim"
+ALIASES = ""
+ALIASES += "examples=^^**Examples**^^@code{.cpp}"
+ALIASES += "end_examples=@endcode^^"
+ALIASES += "rst=^^\verbatim embed:rst:leading-asterisk^^"
+ALIASES += "end_rst=\endverbatim"
 
 DISABLE_INDEX = NO
 DOCBOOK_OUTPUT = doxydocbook
@@ -79,4 +81,10 @@ WARN_AS_ERROR = FAIL_ON_WARNINGS
 # TODO: Enable this when we have complete documentation
 WARN_IF_UNDOCUMENTED = NO
 
+WARN_IF_DOC_ERROR = YES
+WARN_IF_INCOMPLETE_DOC = YES
+WARN_IF_UNDOC_ENUM_VAL = YES
+WARN_NO_PARAMDOC = YES
+WARNINGS = YES
+
 XML_OUTPUT = doxyxml

docs/source/conf.py

@@ -7,6 +7,7 @@
 # standard imports
 from datetime import datetime
 import os
+import shutil
 import subprocess
 from typing import Mapping, Optional
 
@@ -148,6 +149,12 @@ def _run_subprocess(
         exist_ok=True,
     )
 
+# remove existing html files
+# doxygen builds will not re-generated if the html directory already exists
+html_dir = os.path.join(source_dir, 'build', 'html')
+if os.path.exists(html_dir):
+    shutil.rmtree(html_dir)
+
 # run doxygen
 doxy_proc = _run_subprocess(
     args_list=[doxygen_cmd, 'Doxyfile'],

docs/source/source_code/source_code.rst

@@ -1,66 +1,76 @@
 Source Code
 ===========
 We are in process of improving the source code documentation. Code should be documented using Doxygen syntax.
-Some examples exist in `main.h` and `main.cpp`. In order for documentation within the code to appear in the
-rendered docs, the definition of the object must be in a header file, although the documentation itself can (and
-should) be in the source file.
+Many examples exist throughout the codebase.
 
-Example Documentation Blocks
-----------------------------
+Source
+------
+For generated docs, refer to the `Doxygen Documentation <../doxyhtml/index.html>`_.
 
-**file.h**
+Guidelines
+----------
 
-.. code-block:: c
+Doxygen Comments
+^^^^^^^^^^^^^^^^
 
-   // functions
-   int main(int argc, char *argv[]);
+- Use Doxygen comments to document all functions, classes, and variables.
+- `Inline documentation blocks <Inline Documentation Blocks>`_ should use the following format:
 
-**file.cpp** (with markdown)
+  .. code-block:: cpp
 
-.. code-block:: cpp
+     ///< A brief description of the member.
+
+- Multi-line comments, such as for a `documentation block <Documentation Blocks>`_, should use the following format:
+
+  .. code-block:: cpp
+
+     /**
+      * @brief A brief description of the member.
+      * More detailed description of the member.
+      */
 
-   /**
-    * @brief Main application entry point.
-    * @param argc The number of arguments.
-    * @param argv The arguments.
-    *
-    * EXAMPLES:
-    * ```cpp
-    * main(1, const char* args[] = {"hello", "markdown", nullptr});
-    * ```
-    */
-   int main(int argc, char *argv[]) {
-     // do stuff
-   }
-
-**file.cpp** (with ReStructuredText)
+
+Documentation Blocks
+^^^^^^^^^^^^^^^^^^^^
+Documentation blocks should be placed above the declaration of the function, class, or variable. Below is an example
+of a documentation block for the main function.
 
 .. code-block:: cpp
 
-   /**
-    * @brief Main application entry point.
-    * @param argc The number of arguments.
-    * @param argv The arguments.
-    * @rst
-    * EXAMPLES:
-    *
-    * .. code-block:: cpp
-    *    main(1, const char* args[] = {"hello", "rst", nullptr});
-    * @endrst
-    */
-   int main(int argc, char *argv[]) {
-     // do stuff
-   }
+    /**
+     * @brief Main application entry point.
+     * @param argc The number of arguments.
+     * @param argv The arguments.
+     * @return The exit code.
+     * @examples
+     * main(1, const char* args[] = {"hello", "markdown", nullptr});
+     * @end_examples
+     */
+   int main(int argc, char *argv[]);
 
-Source
-------
+.. attention:: The `@examples` and `@end_examples` tags are not standard Doxygen tags. They are custom aliases
+   we have specified to simplify documenting examples. Do not confuse this with the standard `@example` tag.
+
+Inline Documentation Blocks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Inline comments can be used to describe enum values, variables, and other code constructs.
+To document the members of a file, struct, union, class, or enum, it is sometimes desired to place the documentation
+block after the member instead of before. For this purpose you have to put an additional `<` marker in the comment
+block. Below is an example of an inline comment for an enum value.
 
-Please refer to the `Doxygen Documentation <../doxyhtml/index.html>`_ for more details.
+.. code-block:: cpp
 
-.. todo:: Sphinx and Breathe do not support the Objective-C Domain.
-   See https://github.com/breathe-doc/breathe/issues/129
+   enum class MyEnum
+   {
+       FIRST_VALUE,  ///< A brief description of the FIRST_VALUE
+       SECOND_VALUE  ///< A brief description of the SECOND_VALUE
+   };
 
-.. .. doxygenindex::
-..    :allow-dot-graphs:
+Custom Aliases
+^^^^^^^^^^^^^^
+We have defined some custom aliases to simplify documenting examples.
 
-.. Ideally, we would use `doxygenfile` with `:allow-dot-graphs:`, but sphinx complains about duplicated namespaces...
+- ``@examples`` - Start of an example block. This will format the following text as ``cpp``.
+- ``@examples_end`` - End of an example block.
+- ``@rst`` - Start of a reStructuredText block. This will format the following text as reStructuredText.
+- ``@rst_end`` - End of a reStructuredText block.

src/audio.h

@@ -8,13 +8,13 @@
 #include "utility.h"
 namespace audio {
   enum stream_config_e : int {
-    STEREO,
-    HIGH_STEREO,
-    SURROUND51,
-    HIGH_SURROUND51,
-    SURROUND71,
-    HIGH_SURROUND71,
-    MAX_STREAM_CONFIG
+    STEREO,  ///< Stereo
+    HIGH_STEREO,  ///< High stereo
+    SURROUND51,  ///< Surround 5.1
+    HIGH_SURROUND51,  ///< High surround 5.1
+    SURROUND71,  ///< Surround 7.1
+    HIGH_SURROUND71,  ///< High surround 7.1
+    MAX_STREAM_CONFIG  ///< Maximum audio stream configuration
   };
 
   struct opus_stream_config_t {
@@ -37,10 +37,10 @@ namespace audio {
 
   struct config_t {
     enum flags_e : int {
-      HIGH_QUALITY,
-      HOST_AUDIO,
-      CUSTOM_SURROUND_PARAMS,
-      MAX_FLAGS
+      HIGH_QUALITY,  ///< High quality audio
+      HOST_AUDIO,  ///< Host audio
+      CUSTOM_SURROUND_PARAMS,  ///< Custom surround parameters
+      MAX_FLAGS  ///< Maximum number of flags
     };
 
     int packetDuration;

src/config.cpp

@@ -107,72 +107,72 @@ namespace config {
 #endif
 
     enum class quality_av1_e : int {
-      speed = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_SPEED,
-      quality = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_QUALITY,
-      balanced = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_BALANCED
+      speed = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_SPEED,  ///< Speed preset
+      quality = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_QUALITY,  ///< Quality preset
+      balanced = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_BALANCED  ///< Balanced preset
     };
 
     enum class quality_hevc_e : int {
-      speed = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_SPEED,
-      quality = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_QUALITY,
-      balanced = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_BALANCED
+      speed = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_SPEED,  ///< Speed preset
+      quality = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_QUALITY,  ///< Quality preset
+      balanced = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_BALANCED  ///< Balanced preset
     };
 
     enum class quality_h264_e : int {
-      speed = AMF_VIDEO_ENCODER_QUALITY_PRESET_SPEED,
-      quality = AMF_VIDEO_ENCODER_QUALITY_PRESET_QUALITY,
-      balanced = AMF_VIDEO_ENCODER_QUALITY_PRESET_BALANCED
+      speed = AMF_VIDEO_ENCODER_QUALITY_PRESET_SPEED,  ///< Speed preset
+      quality = AMF_VIDEO_ENCODER_QUALITY_PRESET_QUALITY,  ///< Quality preset
+      balanced = AMF_VIDEO_ENCODER_QUALITY_PRESET_BALANCED  ///< Balanced preset
     };
 
     enum class rc_av1_e : int {
-      cbr = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_CBR,
-      cqp = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_CONSTANT_QP,
-      vbr_latency = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_LATENCY_CONSTRAINED_VBR,
-      vbr_peak = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_PEAK_CONSTRAINED_VBR
+      cbr = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_CBR,  ///< CBR
+      cqp = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_CONSTANT_QP,  ///< CQP
+      vbr_latency = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_LATENCY_CONSTRAINED_VBR,  ///< VBR with latency constraints
+      vbr_peak = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_PEAK_CONSTRAINED_VBR  ///< VBR with peak constraints
     };
 
     enum class rc_hevc_e : int {
-      cbr = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_CBR,
-      cqp = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_CONSTANT_QP,
-      vbr_latency = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_LATENCY_CONSTRAINED_VBR,
-      vbr_peak = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_PEAK_CONSTRAINED_VBR
+      cbr = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_CBR,  ///< CBR
+      cqp = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_CONSTANT_QP,  ///< CQP
+      vbr_latency = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_LATENCY_CONSTRAINED_VBR,  ///< VBR with latency constraints
+      vbr_peak = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_PEAK_CONSTRAINED_VBR  ///< VBR with peak constraints
     };
 
     enum class rc_h264_e : int {
-      cbr = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_CBR,
-      cqp = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_CONSTANT_QP,
-      vbr_latency = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_LATENCY_CONSTRAINED_VBR,
-      vbr_peak = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_PEAK_CONSTRAINED_VBR
+      cbr = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_CBR,  ///< CBR
+      cqp = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_CONSTANT_QP,  ///< CQP
+      vbr_latency = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_LATENCY_CONSTRAINED_VBR,  ///< VBR with latency constraints
+      vbr_peak = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_PEAK_CONSTRAINED_VBR  ///< VBR with peak constraints
     };
 
     enum class usage_av1_e : int {
-      transcoding = AMF_VIDEO_ENCODER_AV1_USAGE_TRANSCODING,
-      webcam = AMF_VIDEO_ENCODER_AV1_USAGE_WEBCAM,
-      lowlatency_high_quality = AMF_VIDEO_ENCODER_AV1_USAGE_LOW_LATENCY_HIGH_QUALITY,
-      lowlatency = AMF_VIDEO_ENCODER_AV1_USAGE_LOW_LATENCY,
-      ultralowlatency = AMF_VIDEO_ENCODER_AV1_USAGE_ULTRA_LOW_LATENCY
+      transcoding = AMF_VIDEO_ENCODER_AV1_USAGE_TRANSCODING,  ///< Transcoding preset
+      webcam = AMF_VIDEO_ENCODER_AV1_USAGE_WEBCAM,  ///< Webcam preset
+      lowlatency_high_quality = AMF_VIDEO_ENCODER_AV1_USAGE_LOW_LATENCY_HIGH_QUALITY,  ///< Low latency high quality preset
+      lowlatency = AMF_VIDEO_ENCODER_AV1_USAGE_LOW_LATENCY,  ///< Low latency preset
+      ultralowlatency = AMF_VIDEO_ENCODER_AV1_USAGE_ULTRA_LOW_LATENCY  ///< Ultra low latency preset
     };
 
     enum class usage_hevc_e : int {
-      transcoding = AMF_VIDEO_ENCODER_HEVC_USAGE_TRANSCODING,
-      webcam = AMF_VIDEO_ENCODER_HEVC_USAGE_WEBCAM,
-      lowlatency_high_quality = AMF_VIDEO_ENCODER_HEVC_USAGE_LOW_LATENCY_HIGH_QUALITY,
-      lowlatency = AMF_VIDEO_ENCODER_HEVC_USAGE_LOW_LATENCY,
-      ultralowlatency = AMF_VIDEO_ENCODER_HEVC_USAGE_ULTRA_LOW_LATENCY
+      transcoding = AMF_VIDEO_ENCODER_HEVC_USAGE_TRANSCODING,  ///< Transcoding preset
+      webcam = AMF_VIDEO_ENCODER_HEVC_USAGE_WEBCAM,  ///< Webcam preset
+      lowlatency_high_quality = AMF_VIDEO_ENCODER_HEVC_USAGE_LOW_LATENCY_HIGH_QUALITY,  ///< Low latency high quality preset
+      lowlatency = AMF_VIDEO_ENCODER_HEVC_USAGE_LOW_LATENCY,  ///< Low latency preset
+      ultralowlatency = AMF_VIDEO_ENCODER_HEVC_USAGE_ULTRA_LOW_LATENCY  ///< Ultra low latency preset
     };
 
     enum class usage_h264_e : int {
-      transcoding = AMF_VIDEO_ENCODER_USAGE_TRANSCODING,
-      webcam = AMF_VIDEO_ENCODER_USAGE_WEBCAM,
-      lowlatency_high_quality = AMF_VIDEO_ENCODER_USAGE_LOW_LATENCY_HIGH_QUALITY,
-      lowlatency = AMF_VIDEO_ENCODER_USAGE_LOW_LATENCY,
-      ultralowlatency = AMF_VIDEO_ENCODER_USAGE_ULTRA_LOW_LATENCY
+      transcoding = AMF_VIDEO_ENCODER_USAGE_TRANSCODING,  ///< Transcoding preset
+      webcam = AMF_VIDEO_ENCODER_USAGE_WEBCAM,  ///< Webcam preset
+      lowlatency_high_quality = AMF_VIDEO_ENCODER_USAGE_LOW_LATENCY_HIGH_QUALITY,  ///< Low latency high quality preset
+      lowlatency = AMF_VIDEO_ENCODER_USAGE_LOW_LATENCY,  ///< Low latency preset
+      ultralowlatency = AMF_VIDEO_ENCODER_USAGE_ULTRA_LOW_LATENCY  ///< Ultra low latency preset
     };
 
     enum coder_e : int {
-      _auto = AMF_VIDEO_ENCODER_UNDEFINED,
-      cabac = AMF_VIDEO_ENCODER_CABAC,
-      cavlc = AMF_VIDEO_ENCODER_CALV
+      _auto = AMF_VIDEO_ENCODER_UNDEFINED,  ///< Auto
+      cabac = AMF_VIDEO_ENCODER_CABAC,  ///< CABAC
+      cavlc = AMF_VIDEO_ENCODER_CALV  ///< CAVLC
     };
 
     template <class T>
@@ -226,19 +226,19 @@ namespace config {
 
   namespace qsv {
     enum preset_e : int {
-      veryslow = 1,
-      slower = 2,
-      slow = 3,
-      medium = 4,
-      fast = 5,
-      faster = 6,
-      veryfast = 7
+      veryslow = 1,  ///< veryslow preset
+      slower = 2,  ///< slower preset
+      slow = 3,  ///< slow preset
+      medium = 4,  ///< medium preset
+      fast = 5,  ///< fast preset
+      faster = 6,  ///< faster preset
+      veryfast = 7  ///< veryfast preset
     };
 
     enum cavlc_e : int {
-      _auto = false,
-      enabled = true,
-      disabled = false
+      _auto = false,  ///< Auto
+      enabled = true,  ///< Enabled
+      disabled = false  ///< Disabled
     };
 
     std::optional<int>
@@ -269,9 +269,9 @@ namespace config {
   namespace vt {
 
     enum coder_e : int {
-      _auto = 0,
-      cabac,
-      cavlc
+      _auto = 0,  ///< Auto
+      cabac,  ///< CABAC
+      cavlc  ///< CAVLC
     };
 
     int

src/config.h

@@ -143,12 +143,12 @@ namespace config {
 
   namespace flag {
     enum flag_e : std::size_t {
-      PIN_STDIN = 0,  // Read PIN from stdin instead of http
-      FRESH_STATE,  // Do not load or save state
-      FORCE_VIDEO_HEADER_REPLACE,  // force replacing headers inside video data
-      UPNP,  // Try Universal Plug 'n Play
-      CONST_PIN,  // Use "universal" pin
-      FLAG_SIZE
+      PIN_STDIN = 0,  ///< Read PIN from stdin instead of http
+      FRESH_STATE,  ///< Do not load or save state
+      FORCE_VIDEO_HEADER_REPLACE,  ///< force replacing headers inside video data
+      UPNP,  ///< Try Universal Plug 'n Play
+      CONST_PIN,  ///< Use "universal" pin
+      FLAG_SIZE  ///< Number of flags
     };
   }
 

src/confighttp.cpp

@@ -54,8 +54,8 @@ namespace confighttp {
   using req_https_t = std::shared_ptr<typename SimpleWeb::ServerBase<SimpleWeb::HTTPS>::Request>;
 
   enum class op_e {
-    ADD,
-    REMOVE
+    ADD,  ///< ADD
+    REMOVE  ///< REMOVE
   };
 
   void