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 += "examples_end=@endcode^^"
+ALIASES += "rst=^^\verbatim embed:rst:leading-asterisk^^"
+ALIASES += "rst_end=\endverbatim"
 
 DISABLE_INDEX = NO
 DOCBOOK_OUTPUT = doxydocbook
@@ -64,6 +66,14 @@ MACRO_EXPANSION = YES
 MAN_OUTPUT = doxyman
 NUM_PROC_THREADS = 1
 PREDEFINED = DOXYGEN
+PREDEFINED += __APPLE__
+PREDEFINED += linux
+PREDEFINED += __linux
+PREDEFINED += __linux__
+PREDEFINED += __MACH__
+PREDEFINED += _WIN32
+PREDEFINED += SUNSHINE_BUILD_WAYLAND
+PREDEFINED += SUNSHINE_TRAY=1
 PROJECT_BRIEF = "Self-hosted game stream host for Moonlight."
 PROJECT_ICON = ../sunshine.ico
 PROJECT_LOGO = ../sunshine.png
@@ -79,4 +89,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 block <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.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/audio.cpp
- * @brief todo
+ * @brief Definitions for audio capture and encoding.
  */
 #include <thread>
 

src/audio.h

@@ -1,20 +1,20 @@
 /**
  * @file src/audio.h
- * @brief todo
+ * @brief Declarations for audio capture and encoding.
  */
 #pragma once
 
 #include "thread_safe.h"
 #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/cbs.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/cbs.cpp
- * @brief todo
+ * @brief Definitions for FFmpeg Coded Bitstream API.
  */
 extern "C" {
 #include <cbs/cbs_h264.h>
@@ -217,6 +217,11 @@ namespace cbs {
     };
   }
 
+  /**
+   * This function initializes a Coded Bitstream Context and reads the packet into a Coded Bitstream Fragment.
+   * It then checks if the SPS->VUI (Video Usability Information) is present in the active SPS of the packet.
+   * This is done for both H264 and H265 codecs.
+   */
   bool
   validate_sps(const AVPacket *packet, int codec_id) {
     cbs::ctx_t ctx;

src/cbs.h

@@ -1,6 +1,6 @@
 /**
  * @file src/cbs.h
- * @brief todo
+ * @brief Declarations for FFmpeg Coded Bitstream API.
  */
 #pragma once
 
@@ -31,7 +31,10 @@ namespace cbs {
   make_sps_h264(const AVCodecContext *ctx, const AVPacket *packet);
 
   /**
-   * Check if SPS->VUI is present
+   * @brief Validates the Sequence Parameter Set (SPS) of a given packet.
+   * @param packet The packet to validate.
+   * @param codec_id The ID of the codec used (either AV_CODEC_ID_H264 or AV_CODEC_ID_H265).
+   * @return True if the SPS->VUI is present in the active SPS of the packet, false otherwise.
    */
   bool
   validate_sps(const AVPacket *packet, int codec_id);