docs(src): add examples alias and general cleanup (#2763)

docs/Doxyfile

@@ -24,20 +24,25 @@
 # 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"
 
+CASE_SENSE_NAMES = YES
 DISABLE_INDEX = NO
 DOCBOOK_OUTPUT = doxydocbook
 DOCSET_BUNDLE_ID = dev.lizardbyte.Sunshine
 DOCSET_PUBLISHER_ID = dev.lizardbyte.Sunshine.documentation
 DOCSET_PUBLISHER_NAME = LizardByte
+DOT_GRAPH_MAX_NODES = 60
 DOT_IMAGE_FORMAT = svg
 
 # TODO: On Windows, Doxygen hangs when creating dot graphs if this is set to 0
 DOT_NUM_THREADS = 1
 
+EXTRACT_ALL = YES
 FULL_SIDEBAR = NO
 GENERATE_HTML = YES
 GENERATE_LATEX = NO
@@ -64,6 +69,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 +92,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 @@ for d in directories:
         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,114 @@
 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.
-
-Example Documentation Blocks
-----------------------------
-
-**file.h**
-
-.. code-block:: c
-
-   // functions
-   int main(int argc, char *argv[]);
-
-**file.cpp** (with markdown)
-
-.. code-block:: cpp
-
-   /**
-    * @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)
-
-.. 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
-   }
+Many examples exist throughout the codebase.
 
 Source
 ------
+For generated docs, refer to the `Doxygen Documentation <../doxyhtml/index.html>`_.
 
-Please refer to the `Doxygen Documentation <../doxyhtml/index.html>`_ for more details.
+Guidelines
+----------
 
-.. todo:: Sphinx and Breathe do not support the Objective-C Domain.
-   See https://github.com/breathe-doc/breathe/issues/129
+Doxygen Comments
+^^^^^^^^^^^^^^^^
 
-.. .. doxygenindex::
-..    :allow-dot-graphs:
+- Use Doxygen comments to document all files, functions, classes, and variables.
+- `Inline documentation block <Inline Documentation Blocks>`_ should use the following format:
 
-.. Ideally, we would use `doxygenfile` with `:allow-dot-graphs:`, but sphinx complains about duplicated namespaces...
+  .. 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.
+      */
+
+
+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.
+     * @return The exit code.
+     * @examples
+     * main(1, const char* args[] = {"hello", "markdown", nullptr});
+     * @end_examples
+     */
+   int main(int argc, char *argv[]);
+
+.. 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.
+
+In some cases, it could be valuable to have slightly different documentation for the definitions, especially when
+the definition may change depending on the platform or other factors. In such cases, you should put the documentation
+that is common in the declaration and the definition-specific documentation in the definition. Below is an example of
+how to document the declaration and definition of a function.
+
+.. code-block:: cpp
+
+    // myFile.h
+    /**
+     * @brief A brief description of the function.
+     * @param arg1 Describe the first argument.
+     * @param arg2 Describe the second argument.
+     * @return Describe the result.
+     */
+    int myFunction(int arg1, int arg2);
+
+    // myFile.cpp
+    /**
+     * This describes anything which is specific to the implementation of the function.
+     */
+    int myFunction(int arg1, int arg2)
+    {
+        // Implementation
+    }
+
+File Documentation
+^^^^^^^^^^^^^^^^^^
+The file documentation block must be placed at the top of the file. If it is not present, Doxygen will ignore the file.
+Understandably, it is difficult to make a creative description for every file although it is still required.
+Below is an example of a file documentation block.
+
+.. code-block:: cpp
+
+   /**
+    * @file src/main.cpp
+    * @brief Main application entry point.
+    */
+
+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.
+
+.. code-block:: cpp
+
+   enum class MyEnum
+   {
+       FIRST_VALUE,  ///< A brief description of the FIRST_VALUE
+       SECOND_VALUE  ///< A brief description of the SECOND_VALUE
+   };
+
+Custom Aliases
+^^^^^^^^^^^^^^
+We have defined some custom aliases to simplify documenting examples.
+
+- ``@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.