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 = ""
-ALIASES = "rst=^^\verbatim embed:rst:leading-asterisk^^"
+ALIASES += "examples=^^**Examples**^^@code{.cpp}"
-ALIASES += "endrst=\endverbatim"
+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
+Many examples exist throughout the codebase.
-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
-   }
 
 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.
+Doxygen Comments
-   See https://github.com/breathe-doc/breathe/issues/129
+^^^^^^^^^^^^^^^^
 
-.. .. doxygenindex::
+- Use Doxygen comments to document all files, functions, classes, and variables.
-..    :allow-dot-graphs:
+- `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.

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,6 +1,6 @@
 /**
  * @file src/audio.h
- * @brief todo
+ * @brief Declarations for audio capture and encoding.
  */
 #pragma once
 
@@ -8,13 +8,13 @@
 #include "utility.h"
 namespace audio {
   enum stream_config_e : int {
-    STEREO,
+    STEREO,  ///< Stereo
-    HIGH_STEREO,
+    HIGH_STEREO,  ///< High stereo
-    SURROUND51,
+    SURROUND51,  ///< Surround 5.1
-    HIGH_SURROUND51,
+    HIGH_SURROUND51,  ///< High surround 5.1
-    SURROUND71,
+    SURROUND71,  ///< Surround 7.1
-    HIGH_SURROUND71,
+    HIGH_SURROUND71,  ///< High surround 7.1
-    MAX_STREAM_CONFIG
+    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,
+      HIGH_QUALITY,  ///< High quality audio
-      HOST_AUDIO,
+      HOST_AUDIO,  ///< Host audio
-      CUSTOM_SURROUND_PARAMS,
+      CUSTOM_SURROUND_PARAMS,  ///< Custom surround parameters
-      MAX_FLAGS
+      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);

src/config.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/config.cpp
- * @brief todo
+ * @brief Definitions for the configuration of Sunshine.
  */
 #include <algorithm>
 #include <filesystem>
@@ -107,72 +107,72 @@ namespace config {
 #endif
 
     enum class quality_av1_e : int {
-      speed = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_SPEED,
+      speed = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_SPEED,  ///< Speed preset
-      quality = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_QUALITY,
+      quality = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_QUALITY,  ///< Quality preset
-      balanced = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_BALANCED
+      balanced = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_BALANCED  ///< Balanced preset
     };
 
     enum class quality_hevc_e : int {
-      speed = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_SPEED,
+      speed = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_SPEED,  ///< Speed preset
-      quality = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_QUALITY,
+      quality = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_QUALITY,  ///< Quality preset
-      balanced = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_BALANCED
+      balanced = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_BALANCED  ///< Balanced preset
     };
 
     enum class quality_h264_e : int {
-      speed = AMF_VIDEO_ENCODER_QUALITY_PRESET_SPEED,
+      speed = AMF_VIDEO_ENCODER_QUALITY_PRESET_SPEED,  ///< Speed preset
-      quality = AMF_VIDEO_ENCODER_QUALITY_PRESET_QUALITY,
+      quality = AMF_VIDEO_ENCODER_QUALITY_PRESET_QUALITY,  ///< Quality preset
-      balanced = AMF_VIDEO_ENCODER_QUALITY_PRESET_BALANCED
+      balanced = AMF_VIDEO_ENCODER_QUALITY_PRESET_BALANCED  ///< Balanced preset
     };
 
     enum class rc_av1_e : int {
-      cbr = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_CBR,
+      cbr = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_CBR,  ///< CBR
-      cqp = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_CONSTANT_QP,
+      cqp = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_CONSTANT_QP,  ///< CQP
-      vbr_latency = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_LATENCY_CONSTRAINED_VBR,
+      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_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,
+      cbr = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_CBR,  ///< CBR
-      cqp = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_CONSTANT_QP,
+      cqp = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_CONSTANT_QP,  ///< CQP
-      vbr_latency = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_LATENCY_CONSTRAINED_VBR,
+      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_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,
+      cbr = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_CBR,  ///< CBR
-      cqp = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_CONSTANT_QP,
+      cqp = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_CONSTANT_QP,  ///< CQP
-      vbr_latency = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_LATENCY_CONSTRAINED_VBR,
+      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_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,
+      transcoding = AMF_VIDEO_ENCODER_AV1_USAGE_TRANSCODING,  ///< Transcoding preset
-      webcam = AMF_VIDEO_ENCODER_AV1_USAGE_WEBCAM,
+      webcam = AMF_VIDEO_ENCODER_AV1_USAGE_WEBCAM,  ///< Webcam preset
-      lowlatency_high_quality = AMF_VIDEO_ENCODER_AV1_USAGE_LOW_LATENCY_HIGH_QUALITY,
+      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,
+      lowlatency = AMF_VIDEO_ENCODER_AV1_USAGE_LOW_LATENCY,  ///< Low latency preset
-      ultralowlatency = AMF_VIDEO_ENCODER_AV1_USAGE_ULTRA_LOW_LATENCY
+      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,
+      transcoding = AMF_VIDEO_ENCODER_HEVC_USAGE_TRANSCODING,  ///< Transcoding preset
-      webcam = AMF_VIDEO_ENCODER_HEVC_USAGE_WEBCAM,
+      webcam = AMF_VIDEO_ENCODER_HEVC_USAGE_WEBCAM,  ///< Webcam preset
-      lowlatency_high_quality = AMF_VIDEO_ENCODER_HEVC_USAGE_LOW_LATENCY_HIGH_QUALITY,
+      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,
+      lowlatency = AMF_VIDEO_ENCODER_HEVC_USAGE_LOW_LATENCY,  ///< Low latency preset
-      ultralowlatency = AMF_VIDEO_ENCODER_HEVC_USAGE_ULTRA_LOW_LATENCY
+      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,
+      transcoding = AMF_VIDEO_ENCODER_USAGE_TRANSCODING,  ///< Transcoding preset
-      webcam = AMF_VIDEO_ENCODER_USAGE_WEBCAM,
+      webcam = AMF_VIDEO_ENCODER_USAGE_WEBCAM,  ///< Webcam preset
-      lowlatency_high_quality = AMF_VIDEO_ENCODER_USAGE_LOW_LATENCY_HIGH_QUALITY,
+      lowlatency_high_quality = AMF_VIDEO_ENCODER_USAGE_LOW_LATENCY_HIGH_QUALITY,  ///< Low latency high quality preset
-      lowlatency = AMF_VIDEO_ENCODER_USAGE_LOW_LATENCY,
+      lowlatency = AMF_VIDEO_ENCODER_USAGE_LOW_LATENCY,  ///< Low latency preset
-      ultralowlatency = AMF_VIDEO_ENCODER_USAGE_ULTRA_LOW_LATENCY
+      ultralowlatency = AMF_VIDEO_ENCODER_USAGE_ULTRA_LOW_LATENCY  ///< Ultra low latency preset
     };
 
     enum coder_e : int {
-      _auto = AMF_VIDEO_ENCODER_UNDEFINED,
+      _auto = AMF_VIDEO_ENCODER_UNDEFINED,  ///< Auto
-      cabac = AMF_VIDEO_ENCODER_CABAC,
+      cabac = AMF_VIDEO_ENCODER_CABAC,  ///< CABAC
-      cavlc = AMF_VIDEO_ENCODER_CALV
+      cavlc = AMF_VIDEO_ENCODER_CALV  ///< CAVLC
     };
 
     template <class T>
@@ -226,19 +226,19 @@ namespace config {
 
   namespace qsv {
     enum preset_e : int {
-      veryslow = 1,
+      veryslow = 1,  ///< veryslow preset
-      slower = 2,
+      slower = 2,  ///< slower preset
-      slow = 3,
+      slow = 3,  ///< slow preset
-      medium = 4,
+      medium = 4,  ///< medium preset
-      fast = 5,
+      fast = 5,  ///< fast preset
-      faster = 6,
+      faster = 6,  ///< faster preset
-      veryfast = 7
+      veryfast = 7  ///< veryfast preset
     };
 
     enum cavlc_e : int {
-      _auto = false,
+      _auto = false,  ///< Auto
-      enabled = true,
+      enabled = true,  ///< Enabled
-      disabled = false
+      disabled = false  ///< Disabled
     };
 
     std::optional<int>
@@ -269,9 +269,9 @@ namespace config {
   namespace vt {
 
     enum coder_e : int {
-      _auto = 0,
+      _auto = 0,  ///< Auto
-      cabac,
+      cabac,  ///< CABAC
-      cavlc
+      cavlc  ///< CAVLC
     };
 
     int

src/config.h

@@ -1,6 +1,6 @@
 /**
  * @file src/config.h
- * @brief todo
+ * @brief Declarations for the configuration of Sunshine.
  */
 #pragma once
 
@@ -143,12 +143,12 @@ namespace config {
 
   namespace flag {
     enum flag_e : std::size_t {
-      PIN_STDIN = 0,  // Read PIN from stdin instead of http
+      PIN_STDIN = 0,  ///< Read PIN from stdin instead of http
-      FRESH_STATE,  // Do not load or save state
+      FRESH_STATE,  ///< Do not load or save state
-      FORCE_VIDEO_HEADER_REPLACE,  // force replacing headers inside video data
+      FORCE_VIDEO_HEADER_REPLACE,  ///< force replacing headers inside video data
-      UPNP,  // Try Universal Plug 'n Play
+      UPNP,  ///< Try Universal Plug 'n Play
-      CONST_PIN,  // Use "universal" pin
+      CONST_PIN,  ///< Use "universal" pin
-      FLAG_SIZE
+      FLAG_SIZE  ///< Number of flags
     };
   }
 

src/confighttp.cpp

@@ -1,10 +1,9 @@
 /**
  * @file src/confighttp.cpp
- * @brief todo
+ * @brief Definitions for the Web UI Config HTTP server.
  *
  * @todo Authentication, better handling of routes common to nvhttp, cleanup
  */
-
 #define BOOST_BIND_GLOBAL_PLACEHOLDERS
 
 #include "process.h"
@@ -54,8 +53,8 @@ namespace confighttp {
   using req_https_t = std::shared_ptr<typename SimpleWeb::ServerBase<SimpleWeb::HTTPS>::Request>;
 
   enum class op_e {
-    ADD,
+    ADD,  ///< Add client
-    REMOVE
+    REMOVE  ///< Remove client
   };
 
   void
@@ -156,7 +155,9 @@ namespace confighttp {
               << data.str();
   }
 
-  // todo - combine these functions into a single function that accepts the page, i.e "index", "pin", "apps"
+  /**
+   * @todo combine these functions into a single function that accepts the page, i.e "index", "pin", "apps"
+   */
   void
   getIndexPage(resp_https_t response, req_https_t request) {
     if (!authenticate(response, request)) return;
@@ -255,10 +256,12 @@ namespace confighttp {
     response->write(content, headers);
   }
 
+  /**
+   * @todo combine function with getSunshineLogoImage and possibly getNodeModules
+   * @todo use mime_types map
+   */
   void
   getFaviconImage(resp_https_t response, req_https_t request) {
-    // todo - combine function with getSunshineLogoImage and possibly getNodeModules
-    // todo - use mime_types map
     print_req(request);
 
     std::ifstream in(WEB_DIR "images/sunshine.ico", std::ios::binary);
@@ -267,10 +270,12 @@ namespace confighttp {
     response->write(SimpleWeb::StatusCode::success_ok, in, headers);
   }
 
+  /**
+   * @todo combine function with getFaviconImage and possibly getNodeModules
+   * @todo use mime_types map
+   */
   void
   getSunshineLogoImage(resp_https_t response, req_https_t request) {
-    // todo - combine function with getFaviconImage and possibly getNodeModules
-    // todo - use mime_types map
     print_req(request);
 
     std::ifstream in(WEB_DIR "images/logo-sunshine-45.png", std::ios::binary);

src/confighttp.h

@@ -1,6 +1,6 @@
 /**
  * @file src/confighttp.h
- * @brief todo
+ * @brief Declarations for the Web UI Config HTTP server.
  */
 #pragma once
 

src/crypto.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/crypto.cpp
- * @brief todo
+ * @brief Definitions for cryptography functions.
  */
 #include "crypto.h"
 #include <openssl/pem.h>
@@ -30,7 +30,7 @@ namespace crypto {
       // Expired or not-yet-valid certificates are fine. Sometimes Moonlight is running on embedded devices
       // that don't have accurate clocks (or haven't yet synchronized by the time Moonlight first runs).
       // This behavior also matches what GeForce Experience does.
-      // FIXME: Checking for X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY is a temporary workaround to get moonlight-embedded to work on the raspberry pi
+      // TODO: Checking for X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY is a temporary workaround to get moonlight-embedded to work on the raspberry pi
       case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY:
       case X509_V_ERR_CERT_NOT_YET_VALID:
       case X509_V_ERR_CERT_HAS_EXPIRED:
@@ -42,11 +42,14 @@ namespace crypto {
   }
 
   /**
+   * @brief Verify the certificate chain.
    * When certificates from two or more instances of Moonlight have been added to x509_store_t,
    * only one of them will be verified by X509_verify_cert, resulting in only a single instance of
    * Moonlight to be able to use Sunshine
    *
    * To circumvent this, x509_store_t instance will be created for each instance of the certificates.
+   * @param cert The certificate to verify.
+   * @return nullptr if the certificate is valid, otherwise an error string.
    */
   const char *
   cert_chain_t::verify(x509_t::element_type *cert) {
@@ -176,6 +179,11 @@ namespace crypto {
       return 0;
     }
 
+    /**
+     * This function encrypts the given plaintext using the AES key in GCM mode. The initialization vector (IV) is also provided.
+     * The function handles the creation and initialization of the encryption context, and manages the encryption process.
+     * The resulting ciphertext and the GCM tag are written into the tagged_cipher buffer.
+     */
     int
     gcm_t::encrypt(const std::string_view &plaintext, std::uint8_t *tagged_cipher, aes_t *iv) {
       if (!encrypt_ctx && init_encrypt_gcm(encrypt_ctx, &key, iv, padding)) {
@@ -267,6 +275,11 @@ namespace crypto {
       return 0;
     }
 
+    /**
+     * This function encrypts the given plaintext using the AES key in CBC mode. The initialization vector (IV) is also provided.
+     * The function handles the creation and initialization of the encryption context, and manages the encryption process.
+     * The resulting ciphertext is written into the cipher buffer.
+     */
     int
     cbc_t::encrypt(const std::string_view &plaintext, std::uint8_t *cipher, aes_t *iv) {
       if (!encrypt_ctx && init_encrypt_cbc(encrypt_ctx, &key, iv, padding)) {

src/crypto.h

@@ -1,6 +1,6 @@
 /**
  * @file src/crypto.h
- * @brief todo
+ * @brief Declarations for cryptography functions.
  */
 #pragma once
 
@@ -126,10 +126,12 @@ namespace crypto {
       gcm_t(const crypto::aes_t &key, bool padding = true);
 
       /**
+       * @brief Encrypts the plaintext using AES GCM mode.
        * length of cipher must be at least: round_to_pkcs7_padded(plaintext.size()) + crypto::cipher::tag_size
-       *
+       * @param plaintext The plaintext data to be encrypted.
-       * return -1 on error
+       * @param tagged_cipher The buffer where the resulting ciphertext and GCM tag will be written.
-       * return bytes written on success
+       * @param iv The initialization vector to be used for the encryption.
+       * @return The total length of the ciphertext and GCM tag written into tagged_cipher. Returns -1 in case of an error.
        */
       int
       encrypt(const std::string_view &plaintext, std::uint8_t *tagged_cipher, aes_t *iv);
@@ -148,10 +150,12 @@ namespace crypto {
       cbc_t(const crypto::aes_t &key, bool padding = true);
 
       /**
+       * @brief Encrypts the plaintext using AES CBC mode.
        * length of cipher must be at least: round_to_pkcs7_padded(plaintext.size())
-       *
+       * @param plaintext The plaintext data to be encrypted.
-       * return -1 on error
+       * @param cipher The buffer where the resulting ciphertext will be written.
-       * return bytes written on success
+       * @param iv The initialization vector to be used for the encryption.
+       * @return The total length of the ciphertext written into cipher. Returns -1 in case of an error.
        */
       int
       encrypt(const std::string_view &plaintext, std::uint8_t *cipher, aes_t *iv);

src/entry_handler.cpp

@@ -1,8 +1,7 @@
 /**
  * @file entry_handler.cpp
- * @brief Entry point related functions.
+ * @brief Definitions for entry handling functions.
  */
-
 // standard includes
 #include <csignal>
 #include <iostream>
@@ -27,28 +26,12 @@ extern "C" {
 
 using namespace std::literals;
 
-/**
- * @brief Launch the Web UI.
- *
- * EXAMPLES:
- * ```cpp
- * launch_ui();
- * ```
- */
 void
 launch_ui() {
   std::string url = "https://localhost:" + std::to_string(net::map_port(confighttp::PORT_HTTPS));
   platf::open_url(url);
 }
 
-/**
- * @brief Launch the Web UI at a specific endpoint.
- *
- * EXAMPLES:
- * ```cpp
- * launch_ui_with_path("/pin");
- * ```
- */
 void
 launch_ui_with_path(std::string path) {
   std::string url = "https://localhost:" + std::to_string(net::map_port(confighttp::PORT_HTTPS)) + path;
@@ -56,22 +39,10 @@ launch_ui_with_path(std::string path) {
 }
 
 namespace args {
-  /**
-   * @brief Reset the user credentials.
-   *
-   * @param name The name of the program.
-   * @param argc The number of arguments.
-   * @param argv The arguments.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * creds("sunshine", 2, {"new_username", "new_password"});
-   * ```
-   */
   int
   creds(const char *name, int argc, char *argv[]) {
     if (argc < 2 || argv[0] == "help"sv || argv[1] == "help"sv) {
-      help(name, argc, argv);
+      help(name);
     }
 
     http::save_user_creds(config::sunshine.credentials_file, argv[0], argv[1]);
@@ -79,59 +50,21 @@ namespace args {
     return 0;
   }
 
-  /**
-   * @brief Print help to stdout, then exit.
-   * @param name The name of the program.
-   * @param argc The number of arguments. (Unused)
-   * @param argv The arguments. (Unused)
-   *
-   * EXAMPLES:
-   * ```cpp
-   * help("sunshine", 0, nullptr);
-   * ```
-   */
   int
-  help(const char *name, int argc, char *argv[]) {
+  help(const char *name) {
     logging::print_help(name);
     return 0;
   }
 
-  /**
-   * @brief Print the version to stdout, then exit.
-   * @param name The name of the program. (Unused)
-   * @param argc The number of arguments. (Unused)
-   * @param argv The arguments. (Unused)
-   *
-   * EXAMPLES:
-   * ```cpp
-   * version("sunshine", 0, nullptr);
-   * ```
-   */
   int
-  version(const char *name, int argc, char *argv[]) {
+  version() {
     // version was already logged at startup
     return 0;
   }
 
 #ifdef _WIN32
-  /**
-   * @brief Restore global NVIDIA control panel settings.
-   *
-   * If Sunshine was improperly terminated, this function restores
-   * the global NVIDIA control panel settings to the undo file left
-   * by Sunshine. This function is typically called by the uninstaller.
-   *
-   * @param name The name of the program. (Unused)
-   * @param argc The number of arguments. (Unused)
-   * @param argv The arguments. (Unused)
-   *
-   * EXAMPLES:
-   * ```cpp
-   * restore_nvprefs_undo("sunshine", 0, nullptr);
-   * ```
-   */
   int
-  restore_nvprefs_undo(const char *name, int argc, char *argv[]) {
+  restore_nvprefs_undo() {
     if (nvprefs_instance.load()) {
       nvprefs_instance.restore_from_and_delete_undo_file_if_exists();
       nvprefs_instance.unload();
@@ -145,11 +78,6 @@ namespace lifetime {
   char **argv;
   std::atomic_int desired_exit_code;
 
-  /**
-   * @brief Terminates Sunshine gracefully with the provided exit code.
-   * @param exit_code The exit code to return from main().
-   * @param async Specifies whether our termination will be non-blocking.
-   */
   void
   exit_sunshine(int exit_code, bool async) {
     // Store the exit code of the first exit_sunshine() call
@@ -166,9 +94,6 @@ namespace lifetime {
     }
   }
 
-  /**
-   * @brief Breaks into the debugger or terminates Sunshine if no debugger is attached.
-   */
   void
   debug_trap() {
 #ifdef _WIN32
@@ -178,9 +103,6 @@ namespace lifetime {
 #endif
   }
 
-  /**
-   * @brief Gets the argv array passed to main().
-   */
   char **
   get_argv() {
     return argv;
@@ -188,10 +110,6 @@ namespace lifetime {
 }  // namespace lifetime
 
 #ifdef _WIN32
-/**
- * @brief Check if NVIDIA's GameStream software is running.
- * @return `true` if GameStream is enabled, `false` otherwise.
- */
 bool
 is_gamestream_enabled() {
   DWORD enabled;
@@ -284,14 +202,6 @@ namespace service_ctrl {
     SC_HANDLE service_handle = NULL;
   };
 
-  /**
-   * @brief Check if the service is running.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * is_service_running();
-   * ```
-   */
   bool
   is_service_running() {
     service_controller sc { SERVICE_QUERY_STATUS };
@@ -304,14 +214,6 @@ namespace service_ctrl {
     return status.dwCurrentState == SERVICE_RUNNING;
   }
 
-  /**
-   * @brief Start the service and wait for startup to complete.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * start_service();
-   * ```
-   */
   bool
   start_service() {
     service_controller sc { SERVICE_QUERY_STATUS | SERVICE_START };
@@ -338,14 +240,6 @@ namespace service_ctrl {
     return true;
   }
 
-  /**
-   * @brief Wait for the UI to be ready after Sunshine startup.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * wait_for_ui_ready();
-   * ```
-   */
   bool
   wait_for_ui_ready() {
     std::cout << "Waiting for Web UI to be ready...";

src/entry_handler.h

@@ -1,6 +1,6 @@
 /**
  * @file entry_handler.h
- * @brief Header file for entry point functions.
+ * @brief Declarations for entry handling functions.
  */
 #pragma once
 
@@ -12,50 +12,138 @@
 #include "thread_pool.h"
 #include "thread_safe.h"
 
-// functions
+/**
+ * @brief Launch the Web UI.
+ * @examples
+ * launch_ui();
+ * @examples_end
+ */
 void
 launch_ui();
+
+/**
+ * @brief Launch the Web UI at a specific endpoint.
+ * @examples
+ * launch_ui_with_path("/pin");
+ * @examples_end
+ */
 void
 launch_ui_with_path(std::string path);
 
-#ifdef _WIN32
+/**
-// windows only functions
+ * @brief Functions for handling command line arguments.
-bool
+ */
-is_gamestream_enabled();
-#endif
-
 namespace args {
+  /**
+   * @brief Reset the user credentials.
+   * @param name The name of the program.
+   * @param argc The number of arguments.
+   * @param argv The arguments.
+   * @examples
+   * creds("sunshine", 2, {"new_username", "new_password"});
+   * @examples_end
+   */
   int
   creds(const char *name, int argc, char *argv[]);
+
+  /**
+   * @brief Print help to stdout, then exit.
+   * @param name The name of the program.
+   * @examples
+   * help("sunshine");
+   * @examples_end
+   */
   int
-  help(const char *name, int argc, char *argv[]);
+  help(const char *name);
+
+  /**
+   * @brief Print the version to stdout, then exit.
+   * @examples
+   * version();
+   * @examples_end
+   */
   int
-  version(const char *name, int argc, char *argv[]);
+  version();
+
 #ifdef _WIN32
+  /**
+   * @brief Restore global NVIDIA control panel settings.
+   * If Sunshine was improperly terminated, this function restores
+   * the global NVIDIA control panel settings to the undo file left
+   * by Sunshine. This function is typically called by the uninstaller.
+   * @examples
+   * restore_nvprefs_undo();
+   * @examples_end
+   */
   int
-  restore_nvprefs_undo(const char *name, int argc, char *argv[]);
+  restore_nvprefs_undo();
 #endif
 }  // namespace args
 
+/**
+ * @brief Functions for handling the lifetime of Sunshine.
+ */
 namespace lifetime {
   extern char **argv;
   extern std::atomic_int desired_exit_code;
+
+  /**
+   * @brief Terminates Sunshine gracefully with the provided exit code.
+   * @param exit_code The exit code to return from main().
+   * @param async Specifies whether our termination will be non-blocking.
+   */
   void
   exit_sunshine(int exit_code, bool async);
+
+  /**
+   * @brief Breaks into the debugger or terminates Sunshine if no debugger is attached.
+   */
   void
   debug_trap();
+
+  /**
+   * @brief Get the argv array passed to main().
+   */
   char **
   get_argv();
 }  // namespace lifetime
 
 #ifdef _WIN32
+/**
+ * @brief Check if NVIDIA's GameStream software is running.
+ * @return `true` if GameStream is enabled, `false` otherwise.
+ */
+bool
+is_gamestream_enabled();
+
+/**
+ * @brief Namespace for controlling the Sunshine service model on Windows.
+ */
 namespace service_ctrl {
+  /**
+   * @brief Check if the service is running.
+   * @examples
+   * is_service_running();
+   * @examples_end
+   */
   bool
   is_service_running();
 
+  /**
+   * @brief Start the service and wait for startup to complete.
+   * @examples
+   * start_service();
+   * @examples_end
+   */
   bool
   start_service();
 
+  /**
+   * @brief Wait for the UI to be ready after Sunshine startup.
+   * @examples
+   * wait_for_ui_ready();
+   * @examples_end
+   */
   bool
   wait_for_ui_ready();
 }  // namespace service_ctrl

src/file_handler.cpp

@@ -1,6 +1,6 @@
 /**
  * @file file_handler.cpp
- * @brief File handling functions.
+ * @brief Definitions for file handling functions.
  */
 
 // standard includes
@@ -12,11 +12,6 @@
 #include "logging.h"
 
 namespace file_handler {
-  /**
-   * @brief Get the parent directory of a file or directory.
-   * @param path The path of the file or directory.
-   * @return `std::string` : The parent directory.
-   */
   std::string
   get_parent_directory(const std::string &path) {
     // remove any trailing path separators
@@ -29,11 +24,6 @@ namespace file_handler {
     return p.parent_path().string();
   }
 
-  /**
-   * @brief Make a directory.
-   * @param path The path of the directory.
-   * @return `bool` : `true` on success, `false` on failure.
-   */
   bool
   make_directory(const std::string &path) {
     // first, check if the directory already exists
@@ -44,16 +34,6 @@ namespace file_handler {
     return std::filesystem::create_directories(path);
   }
 
-  /**
-   * @brief Read a file to string.
-   * @param path The path of the file.
-   * @return `std::string` : The contents of the file.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * std::string contents = read_file("path/to/file");
-   * ```
-   */
   std::string
   read_file(const char *path) {
     if (!std::filesystem::exists(path)) {
@@ -65,17 +45,6 @@ namespace file_handler {
     return std::string { (std::istreambuf_iterator<char>(in)), std::istreambuf_iterator<char>() };
   }
 
-  /**
-   * @brief Writes a file.
-   * @param path The path of the file.
-   * @param contents The contents to write.
-   * @return `int` : `0` on success, `-1` on failure.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * int write_status = write_file("path/to/file", "file contents");
-   * ```
-   */
   int
   write_file(const char *path, const std::string_view &contents) {
     std::ofstream out(path);

src/file_handler.h

@@ -1,21 +1,57 @@
 /**
  * @file file_handler.h
- * @brief Header file for file handling functions.
+ * @brief Declarations for file handling functions.
  */
 #pragma once
 
 #include <string>
 
+/**
+ * @brief Responsible for file handling functions.
+ */
 namespace file_handler {
+  /**
+   * @brief Get the parent directory of a file or directory.
+   * @param path The path of the file or directory.
+   * @return The parent directory.
+   * @examples
+   * std::string parent_dir = get_parent_directory("path/to/file");
+   * @examples_end
+   */
   std::string
   get_parent_directory(const std::string &path);
 
+  /**
+   * @brief Make a directory.
+   * @param path The path of the directory.
+   * @return `true` on success, `false` on failure.
+   * @examples
+   * bool dir_created = make_directory("path/to/directory");
+   * @examples_end
+   */
   bool
   make_directory(const std::string &path);
 
+  /**
+   * @brief Read a file to string.
+   * @param path The path of the file.
+   * @return The contents of the file.
+   * @examples
+   * std::string contents = read_file("path/to/file");
+   * @examples_end
+   */
   std::string
   read_file(const char *path);
 
+  /**
+   * @brief Writes a file.
+   * @param path The path of the file.
+   * @param contents The contents to write.
+   * @return ``0`` on success, ``-1`` on failure.
+   * @examples
+   * int write_status = write_file("path/to/file", "file contents");
+   * @examples_end
+   */
   int
   write_file(const char *path, const std::string_view &contents);
 }  // namespace file_handler

src/globals.cpp

@@ -1,27 +1,13 @@
 /**
  * @file globals.cpp
- * @brief Implementation for globally accessible variables and functions.
+ * @brief Definitions for globally accessible variables and functions.
  */
 #include "globals.h"
 
-/**
- * @brief A process-wide communication mechanism.
- */
 safe::mail_t mail::man;
-
-/**
- * @brief A thread pool for processing tasks.
- */
 thread_pool_util::ThreadPool task_pool;
-
-/**
- * @brief A boolean flag to indicate whether the cursor should be displayed.
- */
 bool display_cursor = true;
 
 #ifdef _WIN32
-/**
- * @brief A global singleton used for NVIDIA control panel modifications.
- */
 nvprefs::nvprefs_interface nvprefs_instance;
 #endif

src/globals.h

@@ -1,27 +1,44 @@
 /**
  * @file globals.h
- * @brief Header for globally accessible variables and functions.
+ * @brief Declarations for globally accessible variables and functions.
  */
 #pragma once
 
 #include "entry_handler.h"
 #include "thread_pool.h"
 
+/**
+ * @brief A thread pool for processing tasks.
+ */
 extern thread_pool_util::ThreadPool task_pool;
+
+/**
+ * @brief A boolean flag to indicate whether the cursor should be displayed.
+ */
 extern bool display_cursor;
 
 #ifdef _WIN32
   // Declare global singleton used for NVIDIA control panel modifications
   #include "platform/windows/nvprefs/nvprefs_interface.h"
+
+/**
+ * @brief A global singleton used for NVIDIA control panel modifications.
+ */
 extern nvprefs::nvprefs_interface nvprefs_instance;
 #endif
 
+/**
+ * @brief Handles process-wide communication.
+ */
 namespace mail {
 #define MAIL(x)                         \
   constexpr auto x = std::string_view { \
     #x                                  \
   }
 
+  /**
+   * @brief A process-wide communication mechanism.
+   */
   extern safe::mail_t man;
 
   // Global mail

src/httpcommon.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/httpcommon.cpp
- * @brief todo
+ * @brief Definitions for common HTTP.
  */
 #define BOOST_BIND_GLOBAL_PLACEHOLDERS
 

src/httpcommon.h

@@ -1,6 +1,6 @@
 /**
  * @file src/httpcommon.h
- * @brief todo
+ * @brief Declarations for common HTTP.
  */
 #pragma once
 

src/input.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/input.cpp
- * @brief todo
+ * @brief Definitions for gamepad, keyboard, and mouse input handling.
  */
 // define uint32_t for <moonlight-common-c/src/Input.h>
 #include <cstdint>
@@ -49,9 +49,9 @@ namespace input {
   constexpr auto VKEY_RMENU = 0xA5;
 
   enum class button_state_e {
-    NONE,
+    NONE,  ///< No button state
-    DOWN,
+    DOWN,  ///< Button is down
-    UP
+    UP  ///< Button is up
   };
 
   template <std::size_t N>
@@ -88,9 +88,9 @@ namespace input {
   }
 
   /**
-   * @brief Converts a little-endian netfloat to a native endianness float.
+   * @brief Convert a little-endian netfloat to a native endianness float.
    * @param f Netfloat value.
-   * @return Float value.
+   * @return The native endianness float value.
    */
   float
   from_netfloat(netfloat f) {
@@ -98,11 +98,11 @@ namespace input {
   }
 
   /**
-   * @brief Converts a little-endian netfloat to a native endianness float and clamps it.
+   * @brief Convert a little-endian netfloat to a native endianness float and clamps it.
    * @param f Netfloat value.
    * @param min The minimium value for clamping.
    * @param max The maximum value for clamping.
-   * @return Clamped float value.
+   * @return Clamped native endianess float value.
    */
   float
   from_clamped_netfloat(netfloat f, float min, float max) {
@@ -150,11 +150,10 @@ namespace input {
 
   struct input_t {
     enum shortkey_e {
-      CTRL = 0x1,
+      CTRL = 0x1,  ///< Control key
-      ALT = 0x2,
+      ALT = 0x2,  ///< Alt key
-      SHIFT = 0x4,
+      SHIFT = 0x4,  ///< Shift key
-
+      SHORTCUT = CTRL | ALT | SHIFT  ///< Shortcut combination
-      SHORTCUT = CTRL | ALT | SHIFT
     };
 
     input_t(
@@ -191,11 +190,9 @@ namespace input {
   };
 
   /**
-   * Apply shortcut based on VKEY
+   * @brief Apply shortcut based on VKEY
-   * On success
+   * @param keyCode The VKEY code
-   *    return > 0
+   * @return 0 if no shortcut applied, > 0 if shortcut applied.
-   * On nothing
-   *    return 0
    */
   inline int
   apply_shortcut(short keyCode) {
@@ -499,7 +496,7 @@ namespace input {
   }
 
   /**
-   * @brief Multiplies a polar coordinate pair by a cartesian scaling factor.
+   * @brief Multiply a polar coordinate pair by a cartesian scaling factor.
    * @param r The radial coordinate.
    * @param angle The angular coordinate (radians).
    * @param scalar The scalar cartesian coordinate pair.
@@ -519,17 +516,10 @@ namespace input {
     return std::sqrt(std::pow(x, 2) + std::pow(y, 2));
   }
 
-  /**
-   * @brief Scales the ellipse axes according to the provided size.
-   * @param val The major and minor axis pair.
-   * @param rotation The rotation value from the touch/pen event.
-   * @param scalar The scalar cartesian coordinate pair.
-   * @return The major and minor axis pair.
-   */
   std::pair<float, float>
   scale_client_contact_area(const std::pair<float, float> &val, uint16_t rotation, const std::pair<float, float> &scalar) {
     // If the rotation is unknown, we'll just scale both axes equally by using
-    // a 45 degree angle for our scaling calculations
+    // a 45-degree angle for our scaling calculations
     float angle = rotation == LI_ROT_UNKNOWN ? (M_PI / 4) : (rotation * (M_PI / 180));
 
     // If we have a major but not a minor axis, treat the touch as circular
@@ -650,7 +640,7 @@ namespace input {
   }
 
   /**
-   * Update flags for keyboard shortcut combo's
+   * @brief Update flags for keyboard shortcut combo's
    */
   inline void
   update_shortcutFlags(int *flags, short keyCode, bool release) {
@@ -1242,16 +1232,16 @@ namespace input {
   }
 
   enum class batch_result_e {
-    batched,  // This entry was batched with the source entry
+    batched,  ///< This entry was batched with the source entry
-    not_batchable,  // Not eligible to batch but continue attempts to batch
+    not_batchable,  ///< Not eligible to batch but continue attempts to batch
-    terminate_batch,  // Stop trying to batch with this entry
+    terminate_batch,  ///< Stop trying to batch with this entry
   };
 
   /**
    * @brief Batch two relative mouse messages.
    * @param dest The original packet to batch into.
    * @param src A later packet to attempt to batch.
-   * @return `batch_result_e` : The status of the batching operation.
+   * @return The status of the batching operation.
    */
   batch_result_e
   batch(PNV_REL_MOUSE_MOVE_PACKET dest, PNV_REL_MOUSE_MOVE_PACKET src) {
@@ -1275,7 +1265,7 @@ namespace input {
    * @brief Batch two absolute mouse messages.
    * @param dest The original packet to batch into.
    * @param src A later packet to attempt to batch.
-   * @return `batch_result_e` : The status of the batching operation.
+   * @return The status of the batching operation.
    */
   batch_result_e
   batch(PNV_ABS_MOUSE_MOVE_PACKET dest, PNV_ABS_MOUSE_MOVE_PACKET src) {
@@ -1293,7 +1283,7 @@ namespace input {
    * @brief Batch two vertical scroll messages.
    * @param dest The original packet to batch into.
    * @param src A later packet to attempt to batch.
-   * @return `batch_result_e` : The status of the batching operation.
+   * @return The status of the batching operation.
    */
   batch_result_e
   batch(PNV_SCROLL_PACKET dest, PNV_SCROLL_PACKET src) {
@@ -1314,7 +1304,7 @@ namespace input {
    * @brief Batch two horizontal scroll messages.
    * @param dest The original packet to batch into.
    * @param src A later packet to attempt to batch.
-   * @return `batch_result_e` : The status of the batching operation.
+   * @return The status of the batching operation.
    */
   batch_result_e
   batch(PSS_HSCROLL_PACKET dest, PSS_HSCROLL_PACKET src) {
@@ -1334,7 +1324,7 @@ namespace input {
    * @brief Batch two controller state messages.
    * @param dest The original packet to batch into.
    * @param src A later packet to attempt to batch.
-   * @return `batch_result_e` : The status of the batching operation.
+   * @return The status of the batching operation.
    */
   batch_result_e
   batch(PNV_MULTI_CONTROLLER_PACKET dest, PNV_MULTI_CONTROLLER_PACKET src) {
@@ -1363,7 +1353,7 @@ namespace input {
    * @brief Batch two touch messages.
    * @param dest The original packet to batch into.
    * @param src A later packet to attempt to batch.
-   * @return `batch_result_e` : The status of the batching operation.
+   * @return The status of the batching operation.
    */
   batch_result_e
   batch(PSS_TOUCH_PACKET dest, PSS_TOUCH_PACKET src) {
@@ -1398,7 +1388,7 @@ namespace input {
    * @brief Batch two pen messages.
    * @param dest The original packet to batch into.
    * @param src A later packet to attempt to batch.
-   * @return `batch_result_e` : The status of the batching operation.
+   * @return The status of the batching operation.
    */
   batch_result_e
   batch(PSS_PEN_PACKET dest, PSS_PEN_PACKET src) {
@@ -1432,7 +1422,7 @@ namespace input {
    * @brief Batch two controller touch messages.
    * @param dest The original packet to batch into.
    * @param src A later packet to attempt to batch.
-   * @return `batch_result_e` : The status of the batching operation.
+   * @return The status of the batching operation.
    */
   batch_result_e
   batch(PSS_CONTROLLER_TOUCH_PACKET dest, PSS_CONTROLLER_TOUCH_PACKET src) {
@@ -1473,7 +1463,7 @@ namespace input {
    * @brief Batch two controller motion messages.
    * @param dest The original packet to batch into.
    * @param src A later packet to attempt to batch.
-   * @return `batch_result_e` : The status of the batching operation.
+   * @return The status of the batching operation.
    */
   batch_result_e
   batch(PSS_CONTROLLER_MOTION_PACKET dest, PSS_CONTROLLER_MOTION_PACKET src) {
@@ -1497,7 +1487,7 @@ namespace input {
    * @brief Batch two input messages.
    * @param dest The original packet to batch into.
    * @param src A later packet to attempt to batch.
-   * @return `batch_result_e` : The status of the batching operation.
+   * @return The status of the batching operation.
    */
   batch_result_e
   batch(PNV_INPUT_HEADER dest, PNV_INPUT_HEADER src) {

src/input.h

@@ -1,6 +1,6 @@
 /**
  * @file src/input.h
- * @brief todo
+ * @brief Declarations for gamepad, keyboard, and mouse input handling.
  */
 #pragma once
 
@@ -42,6 +42,13 @@ namespace input {
     }
   };
 
+  /**
+   * @brief Scale the ellipse axes according to the provided size.
+   * @param val The major and minor axis pair.
+   * @param rotation The rotation value from the touch/pen event.
+   * @param scalar The scalar cartesian coordinate pair.
+   * @return The major and minor axis pair.
+   */
   std::pair<float, float>
   scale_client_contact_area(const std::pair<float, float> &val, uint16_t rotation, const std::pair<float, float> &scalar);
 }  // namespace input

src/logging.cpp

@@ -1,8 +1,7 @@
 /**
  * @file src/logging.cpp
- * @brief Logging implementation file for the Sunshine application.
+ * @brief Definitions for logging related functions.
  */
-
 // standard includes
 #include <fstream>
 #include <iostream>
@@ -38,21 +37,10 @@ bl::sources::severity_logger<int> fatal(5);  // Unrecoverable errors
 BOOST_LOG_ATTRIBUTE_KEYWORD(severity, "Severity", int)
 
 namespace logging {
-  /**
-   * @brief A destructor that restores the initial state.
-   */
   deinit_t::~deinit_t() {
     deinit();
   }
 
-  /**
-   * @brief Deinitialize the logging system.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * deinit();
-   * ```
-   */
   void
   deinit() {
     log_flush();
@@ -60,17 +48,6 @@ namespace logging {
     sink.reset();
   }
 
-  /**
-   * @brief Initialize the logging system.
-   * @param min_log_level The minimum log level to output.
-   * @param log_file The log file to write to.
-   * @returns A deinit_t object that will deinitialize the logging system when it goes out of scope.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * log_init(2, "sunshine.log");
-   * ```
-   */
   [[nodiscard]] std::unique_ptr<deinit_t>
   init(int min_log_level, const std::string &log_file) {
     if (sink) {
@@ -131,10 +108,6 @@ namespace logging {
     return std::make_unique<deinit_t>();
   }
 
-  /**
-   * @brief Setup AV logging.
-   * @param min_log_level The log level.
-   */
   void
   setup_av_logging(int min_log_level) {
     if (min_log_level >= 1) {
@@ -169,14 +142,6 @@ namespace logging {
     });
   }
 
-  /**
-   * @brief Flush the log.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * log_flush();
-   * ```
-   */
   void
   log_flush() {
     if (sink) {
@@ -184,15 +149,6 @@ namespace logging {
     }
   }
 
-  /**
-   * @brief Print help to stdout.
-   * @param name The name of the program.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * print_help("sunshine");
-   * ```
-   */
   void
   print_help(const char *name) {
     std::cout

src/logging.h

@@ -1,9 +1,7 @@
 /**
  * @file src/logging.h
- * @brief Logging header file for the Sunshine application.
+ * @brief Declarations for logging related functions.
  */
-
-// macros
 #pragma once
 
 // lib includes
@@ -19,20 +17,62 @@ extern boost::log::sources::severity_logger<int> warning;
 extern boost::log::sources::severity_logger<int> error;
 extern boost::log::sources::severity_logger<int> fatal;
 
+/**
+ * @brief Handles the initialization and deinitialization of the logging system.
+ */
 namespace logging {
   class deinit_t {
   public:
+    /**
+     * @brief A destructor that restores the initial state.
+     */
     ~deinit_t();
   };
 
+  /**
+   * @brief Deinitialize the logging system.
+   * @examples
+   * deinit();
+   * @examples_end
+   */
   void
   deinit();
+
+  /**
+   * @brief Initialize the logging system.
+   * @param min_log_level The minimum log level to output.
+   * @param log_file The log file to write to.
+   * @return An object that will deinitialize the logging system when it goes out of scope.
+   * @examples
+   * log_init(2, "sunshine.log");
+   * @examples_end
+   */
   [[nodiscard]] std::unique_ptr<deinit_t>
   init(int min_log_level, const std::string &log_file);
+
+  /**
+   * @brief Setup AV logging.
+   * @param min_log_level The log level.
+   */
   void
   setup_av_logging(int min_log_level);
+
+  /**
+   * @brief Flush the log.
+   * @examples
+   * log_flush();
+   * @examples_end
+   */
   void
   log_flush();
+
+  /**
+   * @brief Print help to stdout.
+   * @param name The name of the program.
+   * @examples
+   * print_help("sunshine");
+   * @examples_end
+   */
   void
   print_help(const char *name);
 }  // namespace logging

src/main.cpp

@@ -1,8 +1,7 @@
 /**
  * @file src/main.cpp
- * @brief Main entry point for Sunshine.
+ * @brief Definitions for the main entry point for Sunshine.
  */
-
 // standard includes
 #include <codecvt>
 #include <csignal>
@@ -44,11 +43,11 @@ on_signal(int sig, FN &&fn) {
 }
 
 std::map<std::string_view, std::function<int(const char *name, int argc, char **argv)>> cmd_to_func {
-  { "creds"sv, args::creds },
+  { "creds"sv, [](const char *name, int argc, char **argv) { return args::creds(name, argc, argv); } },
-  { "help"sv, args::help },
+  { "help"sv, [](const char *name, int argc, char **argv) { return args::help(name); } },
-  { "version"sv, args::version },
+  { "version"sv, [](const char *name, int argc, char **argv) { return args::version(); } },
 #ifdef _WIN32
-  { "restore-nvprefs-undo"sv, args::restore_nvprefs_undo },
+  { "restore-nvprefs-undo"sv, [](const char *name, int argc, char **argv) { return args::restore_nvprefs_undo(); } },
 #endif
 };
 
@@ -74,16 +73,6 @@ SessionMonitorWindowProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam) {
 }
 #endif
 
-/**
- * @brief Main application entry point.
- * @param argc The number of arguments.
- * @param argv The arguments.
- *
- * EXAMPLES:
- * ```cpp
- * main(1, const char* args[] = {"sunshine", nullptr});
- * ```
- */
 int
 main(int argc, char *argv[]) {
   lifetime::argv = argv;

src/main.h

@@ -1,11 +1,16 @@
 /**
  * @file src/main.h
- * @brief Main header file for the Sunshine application.
+ * @brief Declarations for the main entry point for Sunshine.
  */
-
-// macros
 #pragma once
 
-// functions
+/**
+ * @brief Main application entry point.
+ * @param argc The number of arguments.
+ * @param argv The arguments.
+ * @examples
+ * main(1, const char* args[] = {"sunshine", nullptr});
+ * @examples_end
+ */
 int
 main(int argc, char *argv[]);

src/move_by_copy.h

@@ -1,10 +1,14 @@
 /**
  * @file src/move_by_copy.h
- * @brief todo
+ * @brief Declarations for the MoveByCopy utility class.
  */
 #pragma once
 
 #include <utility>
+
+/**
+ * @brief Contains utilities for moving objects by copying them.
+ */
 namespace move_by_copy_util {
   /**
    * When a copy is made, it moves the object

src/network.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/network.cpp
- * @brief todo
+ * @brief Definitions for networking related functions.
  */
 #include "network.h"
 #include "config.h"
@@ -94,11 +94,6 @@ namespace net {
     return "wan"sv;
   }
 
-  /**
-   * @brief Returns the `af_e` enum value for the `address_family` config option value.
-   * @param view The config option value.
-   * @return The `af_e` enum value.
-   */
   af_e
   af_from_enum_string(const std::string_view &view) {
     if (view == "ipv4") {
@@ -112,11 +107,6 @@ namespace net {
     return BOTH;
   }
 
-  /**
-   * @brief Returns the wildcard binding address for a given address family.
-   * @param af Address family.
-   * @return Normalized address.
-   */
   std::string_view
   af_to_any_address_string(af_e af) {
     switch (af) {
@@ -130,12 +120,6 @@ namespace net {
     return "::"sv;
   }
 
-  /**
-   * @brief Converts an address to a normalized form.
-   * @details Normalization converts IPv4-mapped IPv6 addresses into IPv4 addresses.
-   * @param address The address to normalize.
-   * @return Normalized address.
-   */
   boost::asio::ip::address
   normalize_address(boost::asio::ip::address address) {
     // Convert IPv6-mapped IPv4 addresses into regular IPv4 addresses
@@ -149,23 +133,11 @@ namespace net {
     return address;
   }
 
-  /**
-   * @brief Returns the given address in normalized string form.
-   * @details Normalization converts IPv4-mapped IPv6 addresses into IPv4 addresses.
-   * @param address The address to normalize.
-   * @return Normalized address in string form.
-   */
   std::string
   addr_to_normalized_string(boost::asio::ip::address address) {
     return normalize_address(address).to_string();
   }
 
-  /**
-   * @brief Returns the given address in a normalized form for in the host portion of a URL.
-   * @details Normalization converts IPv4-mapped IPv6 addresses into IPv4 addresses.
-   * @param address The address to normalize and escape.
-   * @return Normalized address in URL-escaped string.
-   */
   std::string
   addr_to_url_escaped_string(boost::asio::ip::address address) {
     address = normalize_address(address);
@@ -179,11 +151,6 @@ namespace net {
     }
   }
 
-  /**
-   * @brief Returns the encryption mode for the given remote endpoint address.
-   * @param address The address used to look up the desired encryption mode.
-   * @return The WAN or LAN encryption mode, based on the provided address.
-   */
   int
   encryption_mode_for_address(boost::asio::ip::address address) {
     auto nettype = net::from_address(address.to_string());
@@ -227,16 +194,6 @@ namespace net {
     enet_host_destroy(host);
   }
 
-  /**
-   * @brief Map a specified port based on the base port.
-   * @param port The port to map as a difference from the base port.
-   * @return `std:uint16_t` : The mapped port number.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * std::uint16_t mapped_port = net::map_port(1);
-   * ```
-   */
   std::uint16_t
   map_port(int port) {
     // calculate the port from the config port
@@ -247,8 +204,6 @@ namespace net {
       BOOST_LOG(warning) << "Port out of range: "sv << mapped_port;
     }
 
-    // TODO: Ensure port is not already in use by another application
-
     return mapped_port;
   }
 }  // namespace net

src/network.h

@@ -1,6 +1,6 @@
 /**
  * @file src/network.h
- * @brief todo
+ * @brief Declarations for networking related functions.
  */
 #pragma once
 
@@ -17,6 +17,15 @@ namespace net {
   void
   free_host(ENetHost *host);
 
+  /**
+   * @brief Map a specified port based on the base port.
+   * @param port The port to map as a difference from the base port.
+   * @return The mapped port number.
+   * @examples
+   * std::uint16_t mapped_port = net::map_port(1);
+   * @examples_end
+   * @todo Ensure port is not already in use by another application.
+   */
   std::uint16_t
   map_port(int port);
 
@@ -25,14 +34,14 @@ namespace net {
   using packet_t = util::safe_ptr<ENetPacket, enet_packet_destroy>;
 
   enum net_e : int {
-    PC,
+    PC,  ///< PC
-    LAN,
+    LAN,  ///< LAN
-    WAN
+    WAN  ///< WAN
   };
 
   enum af_e : int {
-    IPV4,
+    IPV4,  ///< IPv4 only
-    BOTH
+    BOTH  ///< IPv4 and IPv6
   };
 
   net_e
@@ -47,15 +56,15 @@ namespace net {
   host_create(af_e af, ENetAddress &addr, std::size_t peers, std::uint16_t port);
 
   /**
-   * @brief Returns the `af_e` enum value for the `address_family` config option value.
+   * @brief Get the address family enum value from a string.
    * @param view The config option value.
-   * @return The `af_e` enum value.
+   * @return The address family enum value.
    */
   af_e
   af_from_enum_string(const std::string_view &view);
 
   /**
-   * @brief Returns the wildcard binding address for a given address family.
+   * @brief Get the wildcard binding address for a given address family.
    * @param af Address family.
    * @return Normalized address.
    */
@@ -63,7 +72,7 @@ namespace net {
   af_to_any_address_string(af_e af);
 
   /**
-   * @brief Converts an address to a normalized form.
+   * @brief Convert an address to a normalized form.
    * @details Normalization converts IPv4-mapped IPv6 addresses into IPv4 addresses.
    * @param address The address to normalize.
    * @return Normalized address.
@@ -72,7 +81,7 @@ namespace net {
   normalize_address(boost::asio::ip::address address);
 
   /**
-   * @brief Returns the given address in normalized string form.
+   * @brief Get the given address in normalized string form.
    * @details Normalization converts IPv4-mapped IPv6 addresses into IPv4 addresses.
    * @param address The address to normalize.
    * @return Normalized address in string form.
@@ -81,7 +90,7 @@ namespace net {
   addr_to_normalized_string(boost::asio::ip::address address);
 
   /**
-   * @brief Returns the given address in a normalized form for in the host portion of a URL.
+   * @brief Get the given address in a normalized form for the host portion of a URL.
    * @details Normalization converts IPv4-mapped IPv6 addresses into IPv4 addresses.
    * @param address The address to normalize and escape.
    * @return Normalized address in URL-escaped string.
@@ -90,7 +99,7 @@ namespace net {
   addr_to_url_escaped_string(boost::asio::ip::address address);
 
   /**
-   * @brief Returns the encryption mode for the given remote endpoint address.
+   * @brief Get the encryption mode for the given remote endpoint address.
    * @param address The address used to look up the desired encryption mode.
    * @return The WAN or LAN encryption mode, based on the provided address.
    */

src/nvenc/nvenc_base.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/nvenc/nvenc_base.cpp
+ * @brief Definitions for base NVENC encoder.
+ */
 #include "nvenc_base.h"
 
 #include "src/config.h"
@@ -600,14 +604,6 @@ namespace nvenc {
     return false;
   }
 
-  /**
-   * @brief This function returns the corresponding struct version for the minimum API required by the codec.
-   * @details Reducing the struct versions maximizes driver compatibility by avoiding needless API breaks.
-   * @param version The raw structure version from `NVENCAPI_STRUCT_VERSION()`.
-   * @param v11_struct_version Optionally specifies the struct version to use with v11 SDK major versions.
-   * @param v12_struct_version Optionally specifies the struct version to use with v12 SDK major versions.
-   * @return A suitable struct version for the active codec.
-   */
   uint32_t
   nvenc_base::min_struct_version(uint32_t version, uint32_t v11_struct_version, uint32_t v12_struct_version) {
     assert(minimum_api_version);

src/nvenc/nvenc_base.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/nvenc/nvenc_base.h
+ * @brief Declarations for base NVENC encoder.
+ */
 #pragma once
 
 #include "nvenc_colorspace.h"

src/nvenc/nvenc_colorspace.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/nvenc/nvenc_colorspace.h
+ * @brief Declarations for base NVENC colorspace.
+ */
 #pragma once
 
 #include <ffnvcodec/nvEncodeAPI.h>

src/nvenc/nvenc_config.h

@@ -1,16 +1,15 @@
+/**
+ * @file src/nvenc/nvenc_config.h
+ * @brief Declarations for base NVENC configuration.
+ */
 #pragma once
 
 namespace nvenc {
 
   enum class nvenc_two_pass {
-    // Single pass, the fastest and no extra vram
+    disabled,  ///< Single pass, the fastest and no extra vram
-    disabled,
+    quarter_resolution,  ///< Larger motion vectors being caught, faster and uses less extra vram
-
+    full_resolution,  ///< Better overall statistics, slower and uses more extra vram
-    // Larger motion vectors being caught, faster and uses less extra vram
-    quarter_resolution,
-
-    // Better overall statistics, slower and uses more extra vram
-    full_resolution,
   };
 
   struct nvenc_config {

src/nvenc/nvenc_d3d11.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/nvenc/nvenc_d3d11.cpp
+ * @brief Definitions for base NVENC d3d11.
+ */
 #include "src/logging.h"
 
 #ifdef _WIN32

src/nvenc/nvenc_d3d11.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/nvenc/nvenc_d3d11.h
+ * @brief Declarations for base NVENC d3d11.
+ */
 #pragma once
 #ifdef _WIN32
 

src/nvenc/nvenc_encoded_frame.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/nvenc/nvenc_encoded_frame.h
+ * @brief Declarations for base NVENC encoded frame.
+ */
 #pragma once
 
 #include <cstdint>

src/nvenc/nvenc_utils.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/nvenc/nvenc_utils.cpp
+ * @brief Definitions for base NVENC utilities.
+ */
 #include <cassert>
 
 #include "nvenc_utils.h"

src/nvenc/nvenc_utils.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/nvenc/nvenc_utils.h
+ * @brief Declarations for base NVENC utilities.
+ */
 #pragma once
 
 #ifdef _WIN32

src/nvhttp.cpp

@@ -1,8 +1,7 @@
 /**
- * @file src/nvhttp.h
+ * @file src/nvhttp.cpp
- * @brief todo
+ * @brief Definitions for the nvhttp (GameStream) server.
  */
-
 // macros
 #define BOOST_BIND_GLOBAL_PLACEHOLDERS
 
@@ -161,8 +160,8 @@ namespace nvhttp {
   using req_http_t = std::shared_ptr<typename SimpleWeb::ServerBase<SimpleWeb::HTTP>::Request>;
 
   enum class op_e {
-    ADD,
+    ADD,  ///< Add certificate
-    REMOVE
+    REMOVE  ///< Remove certificate
   };
 
   std::string
@@ -610,17 +609,6 @@ namespace nvhttp {
     }
   }
 
-  /**
-   * @brief Compare the user supplied pin to the Moonlight pin.
-   * @param pin The user supplied pin.
-   * @param name The user supplied name.
-   * @return `true` if the pin is correct, `false` otherwise.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * bool pin_status = nvhttp::pin("1234", "laptop");
-   * ```
-   */
   bool
   pin(std::string pin, std::string name) {
     pt::ptree tree;
@@ -1050,14 +1038,6 @@ namespace nvhttp {
     response->close_connection_after_response = true;
   }
 
-  /**
-   * @brief Start the nvhttp server.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * nvhttp::start();
-   * ```
-   */
   void
   start() {
     auto shutdown_event = mail::man->event<bool>(mail::shutdown);
@@ -1188,14 +1168,6 @@ namespace nvhttp {
     tcp.join();
   }
 
-  /**
-   * @brief Remove all paired clients.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * nvhttp::erase_all_clients();
-   * ```
-   */
   void
   erase_all_clients() {
     client_t client;
@@ -1204,14 +1176,6 @@ namespace nvhttp {
     save_state();
   }
 
-  /**
-   * @brief Remove single client.
-   *
-   * EXAMPLES:
-   * ```cpp
-   * nvhttp::unpair_client("4D7BB2DD-5704-A405-B41C-891A022932E1");
-   * ```
-   */
   int
   unpair_client(std::string uuid) {
     int removed = 0;

src/nvhttp.h

@@ -1,8 +1,7 @@
 /**
  * @file src/nvhttp.h
- * @brief todo
+ * @brief Declarations for the nvhttp (GameStream) server.
  */
-
 // macros
 #pragma once
 
@@ -16,7 +15,7 @@
 #include "thread_safe.h"
 
 /**
- * @brief This namespace contains all the functions and variables related to the nvhttp (GameStream) server.
+ * @brief Contains all the functions and variables related to the nvhttp (GameStream) server.
  */
 namespace nvhttp {
 
@@ -42,15 +41,52 @@ namespace nvhttp {
    */
   constexpr auto PORT_HTTPS = -5;
 
-  // functions
+  /**
+   * @brief Start the nvhttp server.
+   * @examples
+   * nvhttp::start();
+   * @examples_end
+   */
   void
   start();
+
+  /**
+   * @brief Compare the user supplied pin to the Moonlight pin.
+   * @param pin The user supplied pin.
+   * @param name The user supplied name.
+   * @return `true` if the pin is correct, `false` otherwise.
+   * @examples
+   * bool pin_status = nvhttp::pin("1234", "laptop");
+   * @examples_end
+   */
   bool
   pin(std::string pin, std::string name);
+
+  /**
+   * @brief Remove single client.
+   * @examples
+   * nvhttp::unpair_client("4D7BB2DD-5704-A405-B41C-891A022932E1");
+   * @examples_end
+   */
   int
   unpair_client(std::string uniqueid);
+
+  /**
+   * @brief Get all paired clients.
+   * @return The list of all paired clients.
+   * @examples
+   * boost::property_tree::ptree clients = nvhttp::get_all_clients();
+   * @examples_end
+   */
   boost::property_tree::ptree
   get_all_clients();
+
+  /**
+   * @brief Remove all paired clients.
+   * @examples
+   * nvhttp::erase_all_clients();
+   * @examples_end
+   */
   void
   erase_all_clients();
 }  // namespace nvhttp

src/platform/common.h

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/common.h
- * @brief todo
+ * @brief Declarations for common platform specific utilities.
  */
 #pragma once
 
@@ -87,10 +87,10 @@ namespace platf {
   };
 
   enum class gamepad_feedback_e {
-    rumble,
+    rumble,  ///< Rumble
-    rumble_triggers,
+    rumble_triggers,  ///< Rumble triggers
-    set_motion_event_state,
+    set_motion_event_state,  ///< Set motion event state
-    set_rgb_led,
+    set_rgb_led,  ///< Set RGB LED
   };
 
   struct gamepad_feedback_msg_t {
@@ -158,15 +158,15 @@ namespace platf {
 
   namespace speaker {
     enum speaker_e {
-      FRONT_LEFT,
+      FRONT_LEFT,  ///< Front left
-      FRONT_RIGHT,
+      FRONT_RIGHT,  ///< Front right
-      FRONT_CENTER,
+      FRONT_CENTER,  ///< Front center
-      LOW_FREQUENCY,
+      LOW_FREQUENCY,  ///< Low frequency
-      BACK_LEFT,
+      BACK_LEFT,  ///< Back left
-      BACK_RIGHT,
+      BACK_RIGHT,  ///< Back right
-      SIDE_LEFT,
+      SIDE_LEFT,  ///< Side left
-      SIDE_RIGHT,
+      SIDE_RIGHT,  ///< Side right
-      MAX_SPEAKERS,
+      MAX_SPEAKERS,  ///< Maximum number of speakers
     };
 
     constexpr std::uint8_t map_stereo[] {
@@ -193,20 +193,20 @@ namespace platf {
   }  // namespace speaker
 
   enum class mem_type_e {
-    system,
+    system,  ///< System memory
-    vaapi,
+    vaapi,  ///< VAAPI
-    dxgi,
+    dxgi,  ///< DXGI
-    cuda,
+    cuda,  ///< CUDA
-    videotoolbox,
+    videotoolbox,  ///< VideoToolbox
-    unknown
+    unknown  ///< Unknown
   };
 
   enum class pix_fmt_e {
-    yuv420p,
+    yuv420p,  ///< YUV 4:2:0
-    yuv420p10,
+    yuv420p10,  ///< YUV 4:2:0 10-bit
-    nv12,
+    nv12,  ///< NV12
-    p010,
+    p010,  ///< P010
-    unknown
+    unknown  ///< Unknown
   };
 
   inline std::string_view
@@ -382,7 +382,8 @@ namespace platf {
     }
 
     /**
-     * implementations must take ownership of 'frame'
+     * @brief Set the frame to be encoded.
+     * @note Implementations must take ownership of 'frame'.
      */
     virtual int
     set_frame(AVFrame *frame, AVBufferRef *hw_frames_ctx) {
@@ -391,13 +392,15 @@ namespace platf {
     };
 
     /**
-     * Implementations may set parameters during initialization of the hwframes context
+     * @brief Initialize the hwframes context.
+     * @note Implementations may set parameters during initialization of the hwframes context.
      */
     virtual void
     init_hwframes(AVHWFramesContext *frames) {};
 
     /**
-     * Implementations may make modifications required before context derivation
+     * @brief Prepare to derive a context.
+     * @note Implementations may make modifications required before context derivation
      */
     virtual int
     prepare_to_derive_context(int hw_device_type) {
@@ -413,34 +416,30 @@ namespace platf {
   };
 
   enum class capture_e : int {
-    ok,
+    ok,  ///< Success
-    reinit,
+    reinit,  ///< Need to reinitialize
-    timeout,
+    timeout,  ///< Timeout
-    interrupted,
+    interrupted,  ///< Capture was interrupted
-    error
+    error  ///< Error
   };
 
   class display_t {
   public:
     /**
+     * @brief Callback for when a new image is ready.
      * When display has a new image ready or a timeout occurs, this callback will be called with the image.
      * If a frame was captured, frame_captured will be true. If a timeout occurred, it will be false.
-     *
+     * @retval true On success
-     * On Break Request -->
+     * @retval false On break request
-     *    Returns false
-     *
-     * On Success -->
-     *    Returns true
      */
     using push_captured_image_cb_t = std::function<bool(std::shared_ptr<img_t> &&img, bool frame_captured)>;
 
     /**
-     * Use to get free image from the pool. Calls must be synchronized.
+     * @brief Get free image from pool.
+     * Calls must be synchronized.
      * Blocks until there is free image in the pool or capture is interrupted.
-     *
+     * @retval true On success, img_out contains free image
-     * Returns:
+     * @retval false When capture has been interrupted, img_out contains nullptr
-     *     'true' on success, img_out contains free image
-     *     'false' when capture has been interrupted, img_out contains nullptr
      */
     using pull_free_image_cb_t = std::function<bool(std::shared_ptr<img_t> &img_out)>;
 
@@ -448,18 +447,16 @@ namespace platf {
         offset_x { 0 }, offset_y { 0 } {}
 
     /**
-     * push_captured_image_cb --> The callback that is called with captured image,
+     * @brief Capture a frame.
-     *                            must be called from the same thread as capture()
+     * @param push_captured_image_cb The callback that is called with captured image,
-     * pull_free_image_cb --> Capture backends call this callback to get empty image
+     * must be called from the same thread as capture()
-     *                        from the pool. If backend uses multiple threads, calls to this
+     * @param pull_free_image_cb Capture backends call this callback to get empty image from the pool.
-     *                        callback must be synchronized. Calls to this callback and
+     * If backend uses multiple threads, calls to this callback must be synchronized.
-     *                        push_captured_image_cb must be synchronized as well.
+     * Calls to this callback and push_captured_image_cb must be synchronized as well.
-     * bool *cursor --> A pointer to the flag that indicates whether the cursor should be captured as well
+     * @param cursor A pointer to the flag that indicates whether the cursor should be captured as well.
-     *
+     * @retval capture_e::ok When stopping
-     * Returns either:
+     * @retval capture_e::error On error
-     *    capture_e::ok when stopping
+     * @retval capture_e::reinit When need of reinitialization
-     *    capture_e::error on error
-     *    capture_e::reinit when need of reinitialization
      */
     virtual capture_e
     capture(const push_captured_image_cb_t &push_captured_image_cb, const pull_free_image_cb_t &pull_free_image_cb, bool *cursor) = 0;
@@ -492,10 +489,10 @@ namespace platf {
     }
 
     /**
-     * @brief Checks that a given codec is supported by the display device.
+     * @brief Check that a given codec is supported by the display device.
      * @param name The FFmpeg codec name (or similar for non-FFmpeg codecs).
      * @param config The codec configuration.
-     * @return true if supported, false otherwise.
+     * @return `true` if supported, `false` otherwise.
      */
     virtual bool
     is_codec_supported(std::string_view name, const ::video::config_t &config) {
@@ -570,11 +567,11 @@ namespace platf {
 
   /**
    * @brief Get the display_t instance for the given hwdevice_type.
-   * @param display_name The name of the monitor that SHOULD be displayed
    * If display_name is empty, use the first monitor that's compatible you can find
    * If you require to use this parameter in a separate thread, make a copy of it.
+   * @param display_name The name of the monitor that SHOULD be displayed
    * @param config Stream configuration
-   * @returns display_t based on hwdevice_type
+   * @return The display_t instance based on hwdevice_type.
    */
   std::shared_ptr<display_t>
   display(mem_type_e hwdevice_type, const std::string &display_name, const video::config_t &config);
@@ -584,7 +581,7 @@ namespace platf {
   display_names(mem_type_e hwdevice_type);
 
   /**
-   * @brief Returns if GPUs/drivers have changed since the last call to this function.
+   * @brief Check if GPUs/drivers have changed since the last call to this function.
    * @return `true` if a change has occurred or if it is unknown whether a change occurred.
    */
   bool
@@ -594,10 +591,10 @@ namespace platf {
   run_command(bool elevated, bool interactive, const std::string &cmd, boost::filesystem::path &working_dir, const boost::process::environment &env, FILE *file, std::error_code &ec, boost::process::group *group);
 
   enum class thread_priority_e : int {
-    low,
+    low,  ///< Low priority
-    normal,
+    normal,  ///< Normal priority
-    high,
+    high,  ///< High priority
-    critical
+    critical  ///< Critical priority
   };
   void
   adjust_thread_priority(thread_priority_e priority);
@@ -637,12 +634,12 @@ namespace platf {
   send(send_info_t &send_info);
 
   enum class qos_data_type_e : int {
-    audio,
+    audio,  ///< Audio
-    video
+    video  ///< Video
   };
 
   /**
-   * @brief Enables QoS on the given socket for traffic to the specified destination.
+   * @brief Enable QoS on the given socket for traffic to the specified destination.
    * @param native_socket The native socket handle.
    * @param address The destination address for traffic sent on this socket.
    * @param port The destination port for traffic sent on this socket.
@@ -662,15 +659,15 @@ namespace platf {
   /**
    * @brief Attempt to gracefully terminate a process group.
    * @param native_handle The native handle of the process group.
-   * @return true if termination was successfully requested.
+   * @return `true` if termination was successfully requested.
    */
   bool
   request_process_group_exit(std::uintptr_t native_handle);
 
   /**
-   * @brief Checks if a process group still has running children.
+   * @brief Check if a process group still has running children.
    * @param native_handle The native handle of the process group.
-   * @return true if processes are still running.
+   * @return `true` if processes are still running.
    */
   bool
   process_group_running(std::uintptr_t native_handle);
@@ -678,14 +675,12 @@ namespace platf {
   input_t
   input();
   /**
-   * @brief Gets the current mouse position on screen
+   * @brief Get the current mouse position on screen
    * @param input The input_t instance to use.
-   * @return util::point_t (x, y)
+   * @return Screen coordinates of the mouse.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * auto [x, y] = get_mouse_loc(input);
-   * ```
+   * @examples_end
    */
   util::point_t
   get_mouse_loc(input_t &input);
@@ -709,7 +704,7 @@ namespace platf {
   typedef deinit_t client_input_t;
 
   /**
-   * @brief Allocates a context to store per-client input data.
+   * @brief Allocate a context to store per-client input data.
    * @param input The global input context.
    * @return A unique pointer to a per-client input data context.
    */
@@ -717,7 +712,7 @@ namespace platf {
   allocate_client_input_context(input_t &input);
 
   /**
-   * @brief Sends a touch event to the OS.
+   * @brief Send a touch event to the OS.
    * @param input The client-specific input context.
    * @param touch_port The current viewport for translating to screen coordinates.
    * @param touch The touch event.
@@ -726,7 +721,7 @@ namespace platf {
   touch_update(client_input_t *input, const touch_port_t &touch_port, const touch_input_t &touch);
 
   /**
-   * @brief Sends a pen event to the OS.
+   * @brief Send a pen event to the OS.
    * @param input The client-specific input context.
    * @param touch_port The current viewport for translating to screen coordinates.
    * @param pen The pen event.
@@ -735,7 +730,7 @@ namespace platf {
   pen_update(client_input_t *input, const touch_port_t &touch_port, const pen_input_t &pen);
 
   /**
-   * @brief Sends a gamepad touch event to the OS.
+   * @brief Send a gamepad touch event to the OS.
    * @param input The global input context.
    * @param touch The touch event.
    */
@@ -743,7 +738,7 @@ namespace platf {
   gamepad_touch(input_t &input, const gamepad_touch_t &touch);
 
   /**
-   * @brief Sends a gamepad motion event to the OS.
+   * @brief Send a gamepad motion event to the OS.
    * @param input The global input context.
    * @param motion The motion event.
    */
@@ -751,7 +746,7 @@ namespace platf {
   gamepad_motion(input_t &input, const gamepad_motion_t &motion);
 
   /**
-   * @brief Sends a gamepad battery event to the OS.
+   * @brief Send a gamepad battery event to the OS.
    * @param input The global input context.
    * @param battery The battery event.
    */
@@ -759,7 +754,7 @@ namespace platf {
   gamepad_battery(input_t &input, const gamepad_battery_t &battery);
 
   /**
-   * @brief Creates a new virtual gamepad.
+   * @brief Create a new virtual gamepad.
    * @param input The global input context.
    * @param id The gamepad ID.
    * @param metadata Controller metadata from client (empty if none provided).
@@ -772,7 +767,7 @@ namespace platf {
   free_gamepad(input_t &input, int nr);
 
   /**
-   * @brief Returns the supported platform capabilities to advertise to the client.
+   * @brief Get the supported platform capabilities to advertise to the client.
    * @return Capability flags.
    */
   platform_caps::caps_t

src/platform/linux/audio.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/audio.cpp
- * @brief todo
+ * @brief Definitions for audio control on Linux.
  */
 #include <bitset>
 #include <sstream>

src/platform/linux/cuda.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/cuda.cpp
- * @brief todo
+ * @brief Definitions for CUDA encoding.
  */
 #include <bitset>
 #include <fcntl.h>

src/platform/linux/cuda.cu

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/cuda.cu
- * @brief todo
+ * @brief CUDA implementation for Linux.
  */
 // #include <algorithm>
 #include <helper_math.h>

src/platform/linux/cuda.h

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/cuda.h
- * @brief todo
+ * @brief Definitions for CUDA implementation.
  */
 #pragma once
 

src/platform/linux/graphics.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/graphics.cpp
- * @brief todo
+ * @brief Definitions for graphics related functions.
  */
 #include "graphics.h"
 #include "src/file_handler.h"
@@ -507,7 +507,7 @@ namespace egl {
   }
 
   /**
-   * @brief Returns EGL attributes for eglCreateImage() to import the provided surface.
+   * @brief Get EGL attributes for eglCreateImage() to import the provided surface.
    * @param surface The surface descriptor.
    * @return Vector of EGL attributes.
    */
@@ -576,7 +576,7 @@ namespace egl {
   }
 
   /**
-   * @brief Creates a black RGB texture of the specified image size.
+   * @brief Create a black RGB texture of the specified image size.
    * @param img The image to use for texture sizing.
    * @return The new RGB texture.
    */
@@ -655,7 +655,7 @@ namespace egl {
   }
 
   /**
-   * @brief Creates biplanar YUV textures to render into.
+   * @brief Create biplanar YUV textures to render into.
    * @param width Width of the target frame.
    * @param height Height of the target frame.
    * @param format Format of the target frame.

src/platform/linux/graphics.h

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/graphics.h
- * @brief todo
+ * @brief Declarations for graphics related functions.
  */
 #pragma once
 

src/platform/linux/input/inputtino.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/input/inputtino.cpp
+ * @brief Definitions for the inputtino Linux input handling.
+ */
 #include <inputtino/input.hpp>
 #include <libevdev/libevdev.h>
 

src/platform/linux/input/inputtino_common.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/input/inputtino_common.h
+ * @brief Declarations for inputtino common input handling.
+ */
 #pragma once
 
 #include <boost/locale.hpp>

src/platform/linux/input/inputtino_gamepad.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/input/inputtino_gamepad.cpp
+ * @brief Definitions for inputtino gamepad input handling.
+ */
 #include <boost/locale.hpp>
 #include <inputtino/input.hpp>
 #include <libevdev/libevdev.h>
@@ -15,10 +19,10 @@ using namespace std::literals;
 namespace platf::gamepad {
 
   enum GamepadStatus {
-    UHID_NOT_AVAILABLE = 0,
+    UHID_NOT_AVAILABLE = 0,  ///< UHID is not available
-    UINPUT_NOT_AVAILABLE,
+    UINPUT_NOT_AVAILABLE,  ///< UINPUT is not available
-    XINPUT_NOT_AVAILABLE,
+    XINPUT_NOT_AVAILABLE,  ///< XINPUT is not available
-    GAMEPAD_STATUS  // Helper to indicate the number of status
+    GAMEPAD_STATUS  ///< Helper to indicate the number of status
   };
 
   auto

src/platform/linux/input/inputtino_gamepad.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/input/inputtino_gamepad.h
+ * @brief Declarations for inputtino gamepad input handling.
+ */
 #pragma once
 
 #include <boost/locale.hpp>
@@ -13,9 +17,9 @@ using namespace std::literals;
 namespace platf::gamepad {
 
   enum ControllerType {
-    XboxOneWired,
+    XboxOneWired,  ///< Xbox One Wired Controller
-    DualSenseWired,
+    DualSenseWired,  ///< DualSense Wired Controller
-    SwitchProWired
+    SwitchProWired  ///< Switch Pro Wired Controller
   };
 
   int

src/platform/linux/input/inputtino_keyboard.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/input/inputtino_keyboard.cpp
+ * @brief Definitions for inputtino keyboard input handling.
+ */
 #include <boost/locale.hpp>
 #include <inputtino/input.hpp>
 #include <libevdev/libevdev.h>

src/platform/linux/input/inputtino_keyboard.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/input/inputtino_keyboard.h
+ * @brief Declarations for inputtino keyboard input handling.
+ */
 #pragma once
 
 #include <boost/locale.hpp>

src/platform/linux/input/inputtino_mouse.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/input/inputtino_mouse.cpp
+ * @brief Definitions for inputtino mouse input handling.
+ */
 #include <boost/locale.hpp>
 #include <inputtino/input.hpp>
 #include <libevdev/libevdev.h>

src/platform/linux/input/inputtino_mouse.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/input/inputtino_mouse.h
+ * @brief Declarations for inputtino mouse input handling.
+ */
 #pragma once
 
 #include <boost/locale.hpp>

src/platform/linux/input/inputtino_pen.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/input/inputtino_pen.cpp
+ * @brief Definitions for inputtino pen input handling.
+ */
 #include <boost/locale.hpp>
 #include <inputtino/input.hpp>
 #include <libevdev/libevdev.h>

src/platform/linux/input/inputtino_pen.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/input/inputtino_pen.h
+ * @brief Declarations for inputtino pen input handling.
+ */
 #pragma once
 
 #include <boost/locale.hpp>

src/platform/linux/input/inputtino_touch.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/input/inputtino_touch.cpp
+ * @brief Definitions for inputtino touch input handling.
+ */
 #include <boost/locale.hpp>
 #include <inputtino/input.hpp>
 #include <libevdev/libevdev.h>

src/platform/linux/input/inputtino_touch.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/input/inputtino_touch.h
+ * @brief Declarations for inputtino touch input handling.
+ */
 #pragma once
 
 #include <boost/locale.hpp>

src/platform/linux/input/legacy_input.cpp

@@ -1074,11 +1074,9 @@ namespace platf {
    * @param input The input_t instance to use.
    * @param x Absolute x position.
    * @param y Absolute y position.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * x_abs_mouse(input, 0, 0);
-   * ```
+   * @examples_end
    */
   static void
   x_abs_mouse(input_t &input, float x, float y) {
@@ -1128,11 +1126,9 @@ namespace platf {
    * @param touch_port The touch_port instance to use.
    * @param x Absolute x position.
    * @param y Absolute y position.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * abs_mouse(input, touch_port, 0, 0);
-   * ```
+   * @examples_end
    */
   void
   abs_mouse(input_t &input, const touch_port_t &touch_port, float x, float y) {
@@ -1160,11 +1156,9 @@ namespace platf {
    * @param input The input_t instance to use.
    * @param deltaX Relative x position.
    * @param deltaY Relative y position.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * x_move_mouse(input, 10, 10);  // Move mouse 10 pixels down and right
-   * ```
+   * @examples_end
    */
   static void
   x_move_mouse(input_t &input, int deltaX, int deltaY) {
@@ -1183,11 +1177,9 @@ namespace platf {
    * @param input The input_t instance to use.
    * @param deltaX Relative x position.
    * @param deltaY Relative y position.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * move_mouse(input, 10, 10); // Move mouse 10 pixels down and right
-   * ```
+   * @examples_end
    */
   void
   move_mouse(input_t &input, int deltaX, int deltaY) {
@@ -1218,11 +1210,9 @@ namespace platf {
    * @param input The input_t instance to use.
    * @param button Which mouse button to emulate.
    * @param release Whether the event was a press (false) or a release (true)
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * x_button_mouse(input, 1, false); // Press left mouse button
-   * ```
+   * @examples_end
    */
   static void
   x_button_mouse(input_t &input, int button, bool release) {
@@ -1261,11 +1251,9 @@ namespace platf {
    * @param input The input_t instance to use.
    * @param button Which mouse button to emulate.
    * @param release Whether the event was a press (false) or a release (true)
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * button_mouse(input, 1, false);  // Press left mouse button
-   * ```
+   * @examples_end
    */
   void
   button_mouse(input_t &input, int button, bool release) {
@@ -1348,11 +1336,9 @@ namespace platf {
    * @param distance How far to scroll.
    * @param button_pos Which mouse button to emulate for positive scroll.
    * @param button_neg Which mouse button to emulate for negative scroll.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * x_scroll(input, 10, 4, 5);
-   * ```
+   * @examples_end
    */
   static void
   x_scroll(input_t &input, int distance, int button_pos, int button_neg) {
@@ -1375,11 +1361,9 @@ namespace platf {
    * @brief Vertical mouse scroll.
    * @param input The input_t instance to use.
    * @param high_res_distance How far to scroll.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * scroll(input, 1200);
-   * ```
+   * @examples_end
    */
   void
   scroll(input_t &input, int high_res_distance) {
@@ -1409,11 +1393,9 @@ namespace platf {
    * @brief Horizontal mouse scroll.
    * @param input The input_t instance to use.
    * @param high_res_distance How far to scroll.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * hscroll(input, 1200);
-   * ```
+   * @examples_end
    */
   void
   hscroll(input_t &input, int high_res_distance) {
@@ -1454,11 +1436,9 @@ namespace platf {
    * @param modcode The moonlight key code.
    * @param release Whether the event was a press (false) or a release (true).
    * @param flags SS_KBE_FLAG_* values.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * x_keyboard(input, 0x5A, false, 0);  // Press Z
-   * ```
+   * @examples_end
    */
   static void
   x_keyboard(input_t &input, uint16_t modcode, bool release, uint8_t flags) {
@@ -1489,11 +1469,9 @@ namespace platf {
    * @param modcode The moonlight key code.
    * @param release Whether the event was a press (false) or a release (true).
    * @param flags SS_KBE_FLAG_* values.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * keyboard(input, 0x5A, false, 0);  // Press Z
-   * ```
+   * @examples_end
    */
   void
   keyboard_update(input_t &input, uint16_t modcode, bool release, uint8_t flags) {
@@ -2106,11 +2084,9 @@ namespace platf {
 
   /**
    * @brief Initialize a new keyboard and return it.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * auto my_keyboard = keyboard();
-   * ```
+   * @examples_end
    */
   evdev_t
   keyboard() {
@@ -2135,11 +2111,9 @@ namespace platf {
 
   /**
    * @brief Initialize a new `uinput` virtual relative mouse and return it.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * auto my_mouse = mouse_rel();
-   * ```
+   * @examples_end
    */
   evdev_t
   mouse_rel() {
@@ -2186,11 +2160,9 @@ namespace platf {
 
   /**
    * @brief Initialize a new `uinput` virtual absolute mouse and return it.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * auto my_mouse = mouse_abs();
-   * ```
+   * @examples_end
    */
   evdev_t
   mouse_abs() {
@@ -2241,11 +2213,9 @@ namespace platf {
 
   /**
    * @brief Initialize a new `uinput` virtual touchscreen and return it.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * auto my_touchscreen = touchscreen();
-   * ```
+   * @examples_end
    */
   evdev_t
   touchscreen() {
@@ -2348,11 +2318,9 @@ namespace platf {
 
   /**
    * @brief Initialize a new `uinput` virtual pen pad and return it.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * auto my_penpad = penpad();
-   * ```
+   * @examples_end
    */
   evdev_t
   penpad() {
@@ -2447,11 +2415,9 @@ namespace platf {
 
   /**
    * @brief Initialize a new `uinput` virtual X360 gamepad and return it.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * auto my_x360 = x360();
-   * ```
+   * @examples_end
    */
   evdev_t
   x360() {
@@ -2524,11 +2490,9 @@ namespace platf {
 
   /**
    * @brief Initialize the input system and return it.
-   *
+   * @examples
-   * EXAMPLES:
-   * ```cpp
    * auto my_input = input();
-   * ```
+   * @examples_end
    */
   input_t
   input() {

src/platform/linux/kmsgrab.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/kmsgrab.cpp
- * @brief todo
+ * @brief Definitions for KMS screen capture.
  */
 #include <drm_fourcc.h>
 #include <errno.h>

src/platform/linux/misc.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/misc.cpp
- * @brief todo
+ * @brief Miscellaneous definitions for Linux.
  */
 
 // Required for in6_pktinfo with glibc headers
@@ -747,18 +747,18 @@ namespace platf {
   namespace source {
     enum source_e : std::size_t {
 #ifdef SUNSHINE_BUILD_CUDA
-      NVFBC,
+      NVFBC,  ///< NvFBC
 #endif
 #ifdef SUNSHINE_BUILD_WAYLAND
-      WAYLAND,
+      WAYLAND,  ///< Wayland
 #endif
 #ifdef SUNSHINE_BUILD_DRM
-      KMS,
+      KMS,  ///< KMS
 #endif
 #ifdef SUNSHINE_BUILD_X11
-      X11,
+      X11,  ///< X11
 #endif
-      MAX_FLAGS
+      MAX_FLAGS  ///< The maximum number of flags
     };
   }  // namespace source
 

src/platform/linux/misc.h

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/misc.h
- * @brief todo
+ * @brief Miscellaneous declarations for Linux.
  */
 #pragma once
 
@@ -16,9 +16,9 @@ KITTY_USING_MOVE_T(file_t, int, -1, {
 });
 
 enum class window_system_e {
-  NONE,
+  NONE,  ///< No window system
-  X11,
+  X11,  ///< X11
-  WAYLAND,
+  WAYLAND,  ///< Wayland
 };
 
 extern window_system_e window_system;

src/platform/linux/publish.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/publish.cpp
- * @brief todo
+ * @brief Definitions for publishing services on Linux.
  * @note Adapted from https://www.avahi.org/doxygen/html/client-publish-service_8c-example.html
  * @todo Use a common file for this and src/platform/macos/publish.cpp
  */
@@ -21,122 +21,118 @@ namespace avahi {
    * @brief Error codes used by avahi.
    */
   enum err_e {
-    OK = 0, /**< OK */
+    OK = 0,  ///< OK
-    ERR_FAILURE = -1, /**< Generic error code */
+    ERR_FAILURE = -1,  ///< Generic error code
-    ERR_BAD_STATE = -2, /**< Object was in a bad state */
+    ERR_BAD_STATE = -2,  ///< Object was in a bad state
-    ERR_INVALID_HOST_NAME = -3, /**< Invalid host name */
+    ERR_INVALID_HOST_NAME = -3,  ///< Invalid host name
-    ERR_INVALID_DOMAIN_NAME = -4, /**< Invalid domain name */
+    ERR_INVALID_DOMAIN_NAME = -4,  ///< Invalid domain name
-    ERR_NO_NETWORK = -5, /**< No suitable network protocol available */
+    ERR_NO_NETWORK = -5,  ///< No suitable network protocol available
-    ERR_INVALID_TTL = -6, /**< Invalid DNS TTL */
+    ERR_INVALID_TTL = -6,  ///< Invalid DNS TTL
-    ERR_IS_PATTERN = -7, /**< RR key is pattern */
+    ERR_IS_PATTERN = -7,  ///< RR key is pattern
-    ERR_COLLISION = -8, /**< Name collision */
+    ERR_COLLISION = -8,  ///< Name collision
-    ERR_INVALID_RECORD = -9, /**< Invalid RR */
+    ERR_INVALID_RECORD = -9,  ///< Invalid RR
 
-    ERR_INVALID_SERVICE_NAME = -10, /**< Invalid service name */
+    ERR_INVALID_SERVICE_NAME = -10,  ///< Invalid service name
-    ERR_INVALID_SERVICE_TYPE = -11, /**< Invalid service type */
+    ERR_INVALID_SERVICE_TYPE = -11,  ///< Invalid service type
-    ERR_INVALID_PORT = -12, /**< Invalid port number */
+    ERR_INVALID_PORT = -12,  ///< Invalid port number
-    ERR_INVALID_KEY = -13, /**< Invalid key */
+    ERR_INVALID_KEY = -13,  ///< Invalid key
-    ERR_INVALID_ADDRESS = -14, /**< Invalid address */
+    ERR_INVALID_ADDRESS = -14,  ///< Invalid address
-    ERR_TIMEOUT = -15, /**< Timeout reached */
+    ERR_TIMEOUT = -15,  ///< Timeout reached
-    ERR_TOO_MANY_CLIENTS = -16, /**< Too many clients */
+    ERR_TOO_MANY_CLIENTS = -16,  ///< Too many clients
-    ERR_TOO_MANY_OBJECTS = -17, /**< Too many objects */
+    ERR_TOO_MANY_OBJECTS = -17,  ///< Too many objects
-    ERR_TOO_MANY_ENTRIES = -18, /**< Too many entries */
+    ERR_TOO_MANY_ENTRIES = -18,  ///< Too many entries
-    ERR_OS = -19, /**< OS error */
+    ERR_OS = -19,  ///< OS error
 
-    ERR_ACCESS_DENIED = -20, /**< Access denied */
+    ERR_ACCESS_DENIED = -20,  ///< Access denied
-    ERR_INVALID_OPERATION = -21, /**< Invalid operation */
+    ERR_INVALID_OPERATION = -21,  ///< Invalid operation
-    ERR_DBUS_ERROR = -22, /**< An unexpected D-Bus error occurred */
+    ERR_DBUS_ERROR = -22,  ///< An unexpected D-Bus error occurred
-    ERR_DISCONNECTED = -23, /**< Daemon connection failed */
+    ERR_DISCONNECTED = -23,  ///< Daemon connection failed
-    ERR_NO_MEMORY = -24, /**< Memory exhausted */
+    ERR_NO_MEMORY = -24,  ///< Memory exhausted
-    ERR_INVALID_OBJECT = -25, /**< The object passed to this function was invalid */
+    ERR_INVALID_OBJECT = -25,  ///< The object passed to this function was invalid
-    ERR_NO_DAEMON = -26, /**< Daemon not running */
+    ERR_NO_DAEMON = -26,  ///< Daemon not running
-    ERR_INVALID_INTERFACE = -27, /**< Invalid interface */
+    ERR_INVALID_INTERFACE = -27,  ///< Invalid interface
-    ERR_INVALID_PROTOCOL = -28, /**< Invalid protocol */
+    ERR_INVALID_PROTOCOL = -28,  ///< Invalid protocol
-    ERR_INVALID_FLAGS = -29, /**< Invalid flags */
+    ERR_INVALID_FLAGS = -29,  ///< Invalid flags
 
-    ERR_NOT_FOUND = -30, /**< Not found */
+    ERR_NOT_FOUND = -30,  ///< Not found
-    ERR_INVALID_CONFIG = -31, /**< Configuration error */
+    ERR_INVALID_CONFIG = -31,  ///< Configuration error
-    ERR_VERSION_MISMATCH = -32, /**< Version mismatch */
+    ERR_VERSION_MISMATCH = -32,  ///< Version mismatch
-    ERR_INVALID_SERVICE_SUBTYPE = -33, /**< Invalid service subtype */
+    ERR_INVALID_SERVICE_SUBTYPE = -33,  ///< Invalid service subtype
-    ERR_INVALID_PACKET = -34, /**< Invalid packet */
+    ERR_INVALID_PACKET = -34,  ///< Invalid packet
-    ERR_INVALID_DNS_ERROR = -35, /**< Invalid DNS return code */
+    ERR_INVALID_DNS_ERROR = -35,  ///< Invalid DNS return code
-    ERR_DNS_FORMERR = -36, /**< DNS Error: Form error */
+    ERR_DNS_FORMERR = -36,  ///< DNS Error: Form error
-    ERR_DNS_SERVFAIL = -37, /**< DNS Error: Server Failure */
+    ERR_DNS_SERVFAIL = -37,  ///< DNS Error: Server Failure
-    ERR_DNS_NXDOMAIN = -38, /**< DNS Error: No such domain */
+    ERR_DNS_NXDOMAIN = -38,  ///< DNS Error: No such domain
-    ERR_DNS_NOTIMP = -39, /**< DNS Error: Not implemented */
+    ERR_DNS_NOTIMP = -39,  ///< DNS Error: Not implemented
 
-    ERR_DNS_REFUSED = -40, /**< DNS Error: Operation refused */
+    ERR_DNS_REFUSED = -40,  ///< DNS Error: Operation refused
-    ERR_DNS_YXDOMAIN = -41,
+    ERR_DNS_YXDOMAIN = -41,  ///< TODO
-    ERR_DNS_YXRRSET = -42,
+    ERR_DNS_YXRRSET = -42,  ///< TODO
-    ERR_DNS_NXRRSET = -43,
+    ERR_DNS_NXRRSET = -43,  ///< TODO
-    ERR_DNS_NOTAUTH = -44, /**< DNS Error: Not authorized */
+    ERR_DNS_NOTAUTH = -44,  ///< DNS Error: Not authorized
-    ERR_DNS_NOTZONE = -45,
+    ERR_DNS_NOTZONE = -45,  ///< TODO
-    ERR_INVALID_RDATA = -46, /**< Invalid RDATA */
+    ERR_INVALID_RDATA = -46,  ///< Invalid RDATA
-    ERR_INVALID_DNS_CLASS = -47, /**< Invalid DNS class */
+    ERR_INVALID_DNS_CLASS = -47,  ///< Invalid DNS class
-    ERR_INVALID_DNS_TYPE = -48, /**< Invalid DNS type */
+    ERR_INVALID_DNS_TYPE = -48,  ///< Invalid DNS type
-    ERR_NOT_SUPPORTED = -49, /**< Not supported */
+    ERR_NOT_SUPPORTED = -49,  ///< Not supported
 
-    ERR_NOT_PERMITTED = -50, /**< Operation not permitted */
+    ERR_NOT_PERMITTED = -50,  ///< Operation not permitted
-    ERR_INVALID_ARGUMENT = -51, /**< Invalid argument */
+    ERR_INVALID_ARGUMENT = -51,  ///< Invalid argument
-    ERR_IS_EMPTY = -52, /**< Is empty */
+    ERR_IS_EMPTY = -52,  ///< Is empty
-    ERR_NO_CHANGE = -53, /**< The requested operation is invalid because it is redundant */
+    ERR_NO_CHANGE = -53,  ///< The requested operation is invalid because it is redundant
 
-    ERR_MAX = -54
+    ERR_MAX = -54  ///< TODO
   };
 
   constexpr auto IF_UNSPEC = -1;
   enum proto {
-    PROTO_INET = 0, /**< IPv4 */
+    PROTO_INET = 0,  ///< IPv4
-    PROTO_INET6 = 1, /**< IPv6 */
+    PROTO_INET6 = 1,  ///< IPv6
-    PROTO_UNSPEC = -1 /**< Unspecified/all protocol(s) */
+    PROTO_UNSPEC = -1  ///< Unspecified/all protocol(s)
   };
 
   enum ServerState {
-    SERVER_INVALID, /**< Invalid state (initial) */
+    SERVER_INVALID,  ///< Invalid state (initial)
-    SERVER_REGISTERING, /**< Host RRs are being registered */
+    SERVER_REGISTERING,  ///< Host RRs are being registered
-    SERVER_RUNNING, /**< All host RRs have been established */
+    SERVER_RUNNING,  ///< All host RRs have been established
-    SERVER_COLLISION, /**< There is a collision with a host RR. All host RRs have been withdrawn, the user should set a new host name via avahi_server_set_host_name() */
+    SERVER_COLLISION,  ///< There is a collision with a host RR. All host RRs have been withdrawn, the user should set a new host name via avahi_server_set_host_name()
-    SERVER_FAILURE /**< Some fatal failure happened, the server is unable to proceed */
+    SERVER_FAILURE  ///< Some fatal failure happened, the server is unable to proceed
   };
 
   enum ClientState {
-    CLIENT_S_REGISTERING = SERVER_REGISTERING, /**< Server state: REGISTERING */
+    CLIENT_S_REGISTERING = SERVER_REGISTERING,  ///< Server state: REGISTERING
-    CLIENT_S_RUNNING = SERVER_RUNNING, /**< Server state: RUNNING */
+    CLIENT_S_RUNNING = SERVER_RUNNING,  ///< Server state: RUNNING
-    CLIENT_S_COLLISION = SERVER_COLLISION, /**< Server state: COLLISION */
+    CLIENT_S_COLLISION = SERVER_COLLISION,  ///< Server state: COLLISION
-    CLIENT_FAILURE = 100, /**< Some kind of error happened on the client side */
+    CLIENT_FAILURE = 100,  ///< Some kind of error happened on the client side
-    CLIENT_CONNECTING = 101 /**< We're still connecting. This state is only entered when AVAHI_CLIENT_NO_FAIL has been passed to avahi_client_new() and the daemon is not yet available. */
+    CLIENT_CONNECTING = 101  ///< We're still connecting. This state is only entered when AVAHI_CLIENT_NO_FAIL has been passed to avahi_client_new() and the daemon is not yet available.
   };
 
   enum EntryGroupState {
-    ENTRY_GROUP_UNCOMMITED, /**< The group has not yet been committed, the user must still call avahi_entry_group_commit() */
+    ENTRY_GROUP_UNCOMMITED,  ///< The group has not yet been committed, the user must still call avahi_entry_group_commit()
-    ENTRY_GROUP_REGISTERING, /**< The entries of the group are currently being registered */
+    ENTRY_GROUP_REGISTERING,  ///< The entries of the group are currently being registered
-    ENTRY_GROUP_ESTABLISHED, /**< The entries have successfully been established */
+    ENTRY_GROUP_ESTABLISHED,  ///< The entries have successfully been established
-    ENTRY_GROUP_COLLISION, /**< A name collision for one of the entries in the group has been detected, the entries have been withdrawn */
+    ENTRY_GROUP_COLLISION,  ///< A name collision for one of the entries in the group has been detected, the entries have been withdrawn
-    ENTRY_GROUP_FAILURE /**< Some kind of failure happened, the entries have been withdrawn */
+    ENTRY_GROUP_FAILURE  ///< Some kind of failure happened, the entries have been withdrawn
   };
 
   enum ClientFlags {
-    CLIENT_IGNORE_USER_CONFIG = 1, /**< Don't read user configuration */
+    CLIENT_IGNORE_USER_CONFIG = 1,  ///< Don't read user configuration
-    CLIENT_NO_FAIL = 2 /**< Don't fail if the daemon is not available when avahi_client_new() is called, instead enter CLIENT_CONNECTING state and wait for the daemon to appear */
+    CLIENT_NO_FAIL = 2  ///< Don't fail if the daemon is not available when avahi_client_new() is called, instead enter CLIENT_CONNECTING state and wait for the daemon to appear
   };
 
   /**
    * @brief Flags for publishing functions.
    */
   enum PublishFlags {
-    PUBLISH_UNIQUE = 1, /**< For raw records: The RRset is intended to be unique */
+    PUBLISH_UNIQUE = 1,  ///< For raw records: The RRset is intended to be unique
-    PUBLISH_NO_PROBE = 2, /**< For raw records: Though the RRset is intended to be unique no probes shall be sent */
+    PUBLISH_NO_PROBE = 2,  ///< For raw records: Though the RRset is intended to be unique no probes shall be sent
-    PUBLISH_NO_ANNOUNCE = 4, /**< For raw records: Do not announce this RR to other hosts */
+    PUBLISH_NO_ANNOUNCE = 4,  ///< For raw records: Do not announce this RR to other hosts
-    PUBLISH_ALLOW_MULTIPLE = 8, /**< For raw records: Allow multiple local records of this type, even if they are intended to be unique */
+    PUBLISH_ALLOW_MULTIPLE = 8,  ///< For raw records: Allow multiple local records of this type, even if they are intended to be unique
-    /** \cond fulldocs */
+    PUBLISH_NO_REVERSE = 16,  ///< For address records: don't create a reverse (PTR) entry
-    PUBLISH_NO_REVERSE = 16, /**< For address records: don't create a reverse (PTR) entry */
+    PUBLISH_NO_COOKIE = 32,  ///< For service records: do not implicitly add the local service cookie to TXT data
-    PUBLISH_NO_COOKIE = 32, /**< For service records: do not implicitly add the local service cookie to TXT data */
+    PUBLISH_UPDATE = 64,  ///< Update existing records instead of adding new ones
-    /** \endcond */
+    PUBLISH_USE_WIDE_AREA = 128,  ///< Register the record using wide area DNS (i.e. unicast DNS update)
-    PUBLISH_UPDATE = 64, /**< Update existing records instead of adding new ones */
+    PUBLISH_USE_MULTICAST = 256  ///< Register the record using multicast DNS
-    /** \cond fulldocs */
-    PUBLISH_USE_WIDE_AREA = 128, /**< Register the record using wide area DNS (i.e. unicast DNS update) */
-    PUBLISH_USE_MULTICAST = 256 /**< Register the record using multicast DNS */
-    /** \endcond */
   };
 
   using IfIndex = int;

src/platform/linux/vaapi.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/vaapi.cpp
- * @brief todo
+ * @brief Definitions for VA-API hardware accelerated capture.
  */
 #include <sstream>
 #include <string>

src/platform/linux/vaapi.h

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/vaapi.h
- * @brief todo
+ * @brief Declarations for VA-API hardware accelerated capture.
  */
 #pragma once
 

src/platform/linux/wayland.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/wayland.cpp
- * @brief todo
+ * @brief Definitions for Wayland capture.
  */
 #include <poll.h>
 #include <wayland-client.h>
@@ -65,7 +65,7 @@ namespace wl {
   /**
    * @brief Waits up to the specified timeout to dispatch new events on the wl_display.
    * @param timeout The timeout in milliseconds.
-   * @return true if new events were dispatched or false if the timeout expired.
+   * @return `true` if new events were dispatched or `false` if the timeout expired.
    */
   bool
   display_t::dispatch(std::chrono::milliseconds timeout) {

src/platform/linux/wayland.h

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/wayland.h
- * @brief todo
+ * @brief Declarations for Wayland capture.
  */
 #pragma once
 
@@ -17,7 +17,7 @@
  * The classes defined in this macro block should only be used by
  * cpp files whose compilation depends on SUNSHINE_BUILD_WAYLAND
  */
-#if defined(SUNSHINE_BUILD_WAYLAND) || defined(DOXYGEN)
+#ifdef SUNSHINE_BUILD_WAYLAND
 
 namespace wl {
   using display_internal_t = util::safe_ptr<wl_display, wl_display_disconnect>;
@@ -34,9 +34,9 @@ namespace wl {
   class dmabuf_t {
   public:
     enum status_e {
-      WAITING,
+      WAITING,  ///< Waiting for a frame
-      READY,
+      READY,  ///< Frame is ready
-      REINIT,
+      REINIT,  ///< Reinitialize the frame
     };
 
     dmabuf_t(dmabuf_t &&) = delete;
@@ -154,9 +154,9 @@ namespace wl {
 
   public:
     enum interface_e {
-      XDG_OUTPUT,
+      XDG_OUTPUT,  ///< xdg-output
-      WLR_EXPORT_DMABUF,
+      WLR_EXPORT_DMABUF,  ///< Export dmabuf
-      MAX_INTERFACES,
+      MAX_INTERFACES,  ///< Maximum number of interfaces
     };
 
     interface_t(interface_t &&) = delete;

src/platform/linux/wlgrab.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/wlgrab.cpp
- * @brief todo
+ * @brief Definitions for wlgrab capture.
  */
 #include <thread>
 

src/platform/linux/x11grab.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/x11grab.cpp
- * @brief todo
+ * @brief Definitions for x11 capture.
  */
 #include "src/platform/common.h"
 

src/platform/linux/x11grab.h

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/linux/x11grab.h
- * @brief todo
+ * @brief Declarations for x11 capture.
  */
 #pragma once
 

src/platform/macos/av_audio.h

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/macos/av_audio.h
- * @brief todo
+ * @brief Declarations for audio capture on macOS.
  */
 #pragma once
 

src/platform/macos/av_audio.m

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/macos/av_audio.m
- * @brief todo
+ * @brief Definitions for audio capture on macOS.
  */
 #import "av_audio.h"
 

src/platform/macos/av_img_t.h

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/macos/av_img_t.h
- * @brief todo
+ * @brief Declarations for AV image types on macOS.
  */
 #pragma once
 

src/platform/macos/av_video.h

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/macos/av_video.h
- * @brief todo
+ * @brief Declarations for video capture on macOS.
  */
 #pragma once
 

src/platform/macos/av_video.m

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/macos/av_video.m
- * @brief todo
+ * @brief Definitions for video capture on macOS.
  */
 #import "av_video.h"
 

src/platform/macos/display.mm

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/macos/display.mm
- * @brief todo
+ * @brief Definitions for display capture on macOS.
  */
 #include "src/platform/common.h"
 #include "src/platform/macos/av_img_t.h"

src/platform/macos/input.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/macos/input.cpp
- * @brief todo
+ * @brief Definitions for macOS input handling.
  */
 #include "src/input.h"
 

src/platform/macos/microphone.mm

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/macos/microphone.mm
- * @brief todo
+ * @brief Definitions for microphone capture on macOS.
  */
 #include "src/platform/common.h"
 #include "src/platform/macos/av_audio.h"

src/platform/macos/misc.h

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/macos/misc.h
- * @brief todo
+ * @brief Miscellaneous declarations for macOS platform.
  */
 #pragma once
 

src/platform/macos/misc.mm

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/macos/misc.mm
- * @brief todo
+ * @brief Miscellaneous definitions for macOS platform.
  */
 
 // Required for IPV6_PKTINFO with Darwin headers

src/platform/macos/nv12_zero_device.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/macos/nv12_zero_device.cpp
- * @brief todo
+ * @brief Definitions for NV12 zero copy device on macOS.
  */
 #include <utility>
 

src/platform/macos/nv12_zero_device.h

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/macos/nv12_zero_device.h
- * @brief todo
+ * @brief Declarations for NV12 zero copy device on macOS.
  */
 #pragma once
 

src/platform/macos/publish.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/macos/publish.cpp
- * @brief todo
+ * @brief Definitions for publishing services on macOS.
  * @note Adapted from https://www.avahi.org/doxygen/html/client-publish-service_8c-example.html
  * @todo Use a common file for this and src/platform/linux/publish.cpp
  */
@@ -21,122 +21,118 @@ namespace avahi {
    * @brief Error codes used by avahi.
    */
   enum err_e {
-    OK = 0, /**< OK */
+    OK = 0,  ///< OK
-    ERR_FAILURE = -1, /**< Generic error code */
+    ERR_FAILURE = -1,  ///< Generic error code
-    ERR_BAD_STATE = -2, /**< Object was in a bad state */
+    ERR_BAD_STATE = -2,  ///< Object was in a bad state
-    ERR_INVALID_HOST_NAME = -3, /**< Invalid host name */
+    ERR_INVALID_HOST_NAME = -3,  ///< Invalid host name
-    ERR_INVALID_DOMAIN_NAME = -4, /**< Invalid domain name */
+    ERR_INVALID_DOMAIN_NAME = -4,  ///< Invalid domain name
-    ERR_NO_NETWORK = -5, /**< No suitable network protocol available */
+    ERR_NO_NETWORK = -5,  ///< No suitable network protocol available
-    ERR_INVALID_TTL = -6, /**< Invalid DNS TTL */
+    ERR_INVALID_TTL = -6,  ///< Invalid DNS TTL
-    ERR_IS_PATTERN = -7, /**< RR key is pattern */
+    ERR_IS_PATTERN = -7,  ///< RR key is pattern
-    ERR_COLLISION = -8, /**< Name collision */
+    ERR_COLLISION = -8,  ///< Name collision
-    ERR_INVALID_RECORD = -9, /**< Invalid RR */
+    ERR_INVALID_RECORD = -9,  ///< Invalid RR
 
-    ERR_INVALID_SERVICE_NAME = -10, /**< Invalid service name */
+    ERR_INVALID_SERVICE_NAME = -10,  ///< Invalid service name
-    ERR_INVALID_SERVICE_TYPE = -11, /**< Invalid service type */
+    ERR_INVALID_SERVICE_TYPE = -11,  ///< Invalid service type
-    ERR_INVALID_PORT = -12, /**< Invalid port number */
+    ERR_INVALID_PORT = -12,  ///< Invalid port number
-    ERR_INVALID_KEY = -13, /**< Invalid key */
+    ERR_INVALID_KEY = -13,  ///< Invalid key
-    ERR_INVALID_ADDRESS = -14, /**< Invalid address */
+    ERR_INVALID_ADDRESS = -14,  ///< Invalid address
-    ERR_TIMEOUT = -15, /**< Timeout reached */
+    ERR_TIMEOUT = -15,  ///< Timeout reached
-    ERR_TOO_MANY_CLIENTS = -16, /**< Too many clients */
+    ERR_TOO_MANY_CLIENTS = -16,  ///< Too many clients
-    ERR_TOO_MANY_OBJECTS = -17, /**< Too many objects */
+    ERR_TOO_MANY_OBJECTS = -17,  ///< Too many objects
-    ERR_TOO_MANY_ENTRIES = -18, /**< Too many entries */
+    ERR_TOO_MANY_ENTRIES = -18,  ///< Too many entries
-    ERR_OS = -19, /**< OS error */
+    ERR_OS = -19,  ///< OS error
 
-    ERR_ACCESS_DENIED = -20, /**< Access denied */
+    ERR_ACCESS_DENIED = -20,  ///< Access denied
-    ERR_INVALID_OPERATION = -21, /**< Invalid operation */
+    ERR_INVALID_OPERATION = -21,  ///< Invalid operation
-    ERR_DBUS_ERROR = -22, /**< An unexpected D-Bus error occurred */
+    ERR_DBUS_ERROR = -22,  ///< An unexpected D-Bus error occurred
-    ERR_DISCONNECTED = -23, /**< Daemon connection failed */
+    ERR_DISCONNECTED = -23,  ///< Daemon connection failed
-    ERR_NO_MEMORY = -24, /**< Memory exhausted */
+    ERR_NO_MEMORY = -24,  ///< Memory exhausted
-    ERR_INVALID_OBJECT = -25, /**< The object passed to this function was invalid */
+    ERR_INVALID_OBJECT = -25,  ///< The object passed to this function was invalid
-    ERR_NO_DAEMON = -26, /**< Daemon not running */
+    ERR_NO_DAEMON = -26,  ///< Daemon not running
-    ERR_INVALID_INTERFACE = -27, /**< Invalid interface */
+    ERR_INVALID_INTERFACE = -27,  ///< Invalid interface
-    ERR_INVALID_PROTOCOL = -28, /**< Invalid protocol */
+    ERR_INVALID_PROTOCOL = -28,  ///< Invalid protocol
-    ERR_INVALID_FLAGS = -29, /**< Invalid flags */
+    ERR_INVALID_FLAGS = -29,  ///< Invalid flags
 
-    ERR_NOT_FOUND = -30, /**< Not found */
+    ERR_NOT_FOUND = -30,  ///< Not found
-    ERR_INVALID_CONFIG = -31, /**< Configuration error */
+    ERR_INVALID_CONFIG = -31,  ///< Configuration error
-    ERR_VERSION_MISMATCH = -32, /**< Version mismatch */
+    ERR_VERSION_MISMATCH = -32,  ///< Version mismatch
-    ERR_INVALID_SERVICE_SUBTYPE = -33, /**< Invalid service subtype */
+    ERR_INVALID_SERVICE_SUBTYPE = -33,  ///< Invalid service subtype
-    ERR_INVALID_PACKET = -34, /**< Invalid packet */
+    ERR_INVALID_PACKET = -34,  ///< Invalid packet
-    ERR_INVALID_DNS_ERROR = -35, /**< Invalid DNS return code */
+    ERR_INVALID_DNS_ERROR = -35,  ///< Invalid DNS return code
-    ERR_DNS_FORMERR = -36, /**< DNS Error: Form error */
+    ERR_DNS_FORMERR = -36,  ///< DNS Error: Form error
-    ERR_DNS_SERVFAIL = -37, /**< DNS Error: Server Failure */
+    ERR_DNS_SERVFAIL = -37,  ///< DNS Error: Server Failure
-    ERR_DNS_NXDOMAIN = -38, /**< DNS Error: No such domain */
+    ERR_DNS_NXDOMAIN = -38,  ///< DNS Error: No such domain
-    ERR_DNS_NOTIMP = -39, /**< DNS Error: Not implemented */
+    ERR_DNS_NOTIMP = -39,  ///< DNS Error: Not implemented
 
-    ERR_DNS_REFUSED = -40, /**< DNS Error: Operation refused */
+    ERR_DNS_REFUSED = -40,  ///< DNS Error: Operation refused
-    ERR_DNS_YXDOMAIN = -41,
+    ERR_DNS_YXDOMAIN = -41,  ///< TODO
-    ERR_DNS_YXRRSET = -42,
+    ERR_DNS_YXRRSET = -42,  ///< TODO
-    ERR_DNS_NXRRSET = -43,
+    ERR_DNS_NXRRSET = -43,  ///< TODO
-    ERR_DNS_NOTAUTH = -44, /**< DNS Error: Not authorized */
+    ERR_DNS_NOTAUTH = -44,  ///< DNS Error: Not authorized
-    ERR_DNS_NOTZONE = -45,
+    ERR_DNS_NOTZONE = -45,  ///< TODO
-    ERR_INVALID_RDATA = -46, /**< Invalid RDATA */
+    ERR_INVALID_RDATA = -46,  ///< Invalid RDATA
-    ERR_INVALID_DNS_CLASS = -47, /**< Invalid DNS class */
+    ERR_INVALID_DNS_CLASS = -47,  ///< Invalid DNS class
-    ERR_INVALID_DNS_TYPE = -48, /**< Invalid DNS type */
+    ERR_INVALID_DNS_TYPE = -48,  ///< Invalid DNS type
-    ERR_NOT_SUPPORTED = -49, /**< Not supported */
+    ERR_NOT_SUPPORTED = -49,  ///< Not supported
 
-    ERR_NOT_PERMITTED = -50, /**< Operation not permitted */
+    ERR_NOT_PERMITTED = -50,  ///< Operation not permitted
-    ERR_INVALID_ARGUMENT = -51, /**< Invalid argument */
+    ERR_INVALID_ARGUMENT = -51,  ///< Invalid argument
-    ERR_IS_EMPTY = -52, /**< Is empty */
+    ERR_IS_EMPTY = -52,  ///< Is empty
-    ERR_NO_CHANGE = -53, /**< The requested operation is invalid because it is redundant */
+    ERR_NO_CHANGE = -53,  ///< The requested operation is invalid because it is redundant
 
-    ERR_MAX = -54
+    ERR_MAX = -54  ///< TODO
   };
 
   constexpr auto IF_UNSPEC = -1;
   enum proto {
-    PROTO_INET = 0, /**< IPv4 */
+    PROTO_INET = 0,  ///< IPv4
-    PROTO_INET6 = 1, /**< IPv6 */
+    PROTO_INET6 = 1,  ///< IPv6
-    PROTO_UNSPEC = -1 /**< Unspecified/all protocol(s) */
+    PROTO_UNSPEC = -1  ///< Unspecified/all protocol(s)
   };
 
   enum ServerState {
-    SERVER_INVALID, /**< Invalid state (initial) */
+    SERVER_INVALID,  ///< Invalid state (initial)
-    SERVER_REGISTERING, /**< Host RRs are being registered */
+    SERVER_REGISTERING,  ///< Host RRs are being registered
-    SERVER_RUNNING, /**< All host RRs have been established */
+    SERVER_RUNNING,  ///< All host RRs have been established
-    SERVER_COLLISION, /**< There is a collision with a host RR. All host RRs have been withdrawn, the user should set a new host name via avahi_server_set_host_name() */
+    SERVER_COLLISION,  ///< There is a collision with a host RR. All host RRs have been withdrawn, the user should set a new host name via avahi_server_set_host_name()
-    SERVER_FAILURE /**< Some fatal failure happened, the server is unable to proceed */
+    SERVER_FAILURE  ///< Some fatal failure happened, the server is unable to proceed
   };
 
   enum ClientState {
-    CLIENT_S_REGISTERING = SERVER_REGISTERING, /**< Server state: REGISTERING */
+    CLIENT_S_REGISTERING = SERVER_REGISTERING,  ///< Server state: REGISTERING
-    CLIENT_S_RUNNING = SERVER_RUNNING, /**< Server state: RUNNING */
+    CLIENT_S_RUNNING = SERVER_RUNNING,  ///< Server state: RUNNING
-    CLIENT_S_COLLISION = SERVER_COLLISION, /**< Server state: COLLISION */
+    CLIENT_S_COLLISION = SERVER_COLLISION,  ///< Server state: COLLISION
-    CLIENT_FAILURE = 100, /**< Some kind of error happened on the client side */
+    CLIENT_FAILURE = 100,  ///< Some kind of error happened on the client side
-    CLIENT_CONNECTING = 101 /**< We're still connecting. This state is only entered when AVAHI_CLIENT_NO_FAIL has been passed to avahi_client_new() and the daemon is not yet available. */
+    CLIENT_CONNECTING = 101  ///< We're still connecting. This state is only entered when AVAHI_CLIENT_NO_FAIL has been passed to avahi_client_new() and the daemon is not yet available.
   };
 
   enum EntryGroupState {
-    ENTRY_GROUP_UNCOMMITED, /**< The group has not yet been committed, the user must still call avahi_entry_group_commit() */
+    ENTRY_GROUP_UNCOMMITED,  ///< The group has not yet been committed, the user must still call avahi_entry_group_commit()
-    ENTRY_GROUP_REGISTERING, /**< The entries of the group are currently being registered */
+    ENTRY_GROUP_REGISTERING,  ///< The entries of the group are currently being registered
-    ENTRY_GROUP_ESTABLISHED, /**< The entries have successfully been established */
+    ENTRY_GROUP_ESTABLISHED,  ///< The entries have successfully been established
-    ENTRY_GROUP_COLLISION, /**< A name collision for one of the entries in the group has been detected, the entries have been withdrawn */
+    ENTRY_GROUP_COLLISION,  ///< A name collision for one of the entries in the group has been detected, the entries have been withdrawn
-    ENTRY_GROUP_FAILURE /**< Some kind of failure happened, the entries have been withdrawn */
+    ENTRY_GROUP_FAILURE  ///< Some kind of failure happened, the entries have been withdrawn
   };
 
   enum ClientFlags {
-    CLIENT_IGNORE_USER_CONFIG = 1, /**< Don't read user configuration */
+    CLIENT_IGNORE_USER_CONFIG = 1,  ///< Don't read user configuration
-    CLIENT_NO_FAIL = 2 /**< Don't fail if the daemon is not available when avahi_client_new() is called, instead enter CLIENT_CONNECTING state and wait for the daemon to appear */
+    CLIENT_NO_FAIL = 2  ///< Don't fail if the daemon is not available when avahi_client_new() is called, instead enter CLIENT_CONNECTING state and wait for the daemon to appear
   };
 
   /**
    * @brief Flags for publishing functions.
    */
   enum PublishFlags {
-    PUBLISH_UNIQUE = 1, /**< For raw records: The RRset is intended to be unique */
+    PUBLISH_UNIQUE = 1,  ///< For raw records: The RRset is intended to be unique
-    PUBLISH_NO_PROBE = 2, /**< For raw records: Though the RRset is intended to be unique no probes shall be sent */
+    PUBLISH_NO_PROBE = 2,  ///< For raw records: Though the RRset is intended to be unique no probes shall be sent
-    PUBLISH_NO_ANNOUNCE = 4, /**< For raw records: Do not announce this RR to other hosts */
+    PUBLISH_NO_ANNOUNCE = 4,  ///< For raw records: Do not announce this RR to other hosts
-    PUBLISH_ALLOW_MULTIPLE = 8, /**< For raw records: Allow multiple local records of this type, even if they are intended to be unique */
+    PUBLISH_ALLOW_MULTIPLE = 8,  ///< For raw records: Allow multiple local records of this type, even if they are intended to be unique
-    /** \cond fulldocs */
+    PUBLISH_NO_REVERSE = 16,  ///< For address records: don't create a reverse (PTR) entry
-    PUBLISH_NO_REVERSE = 16, /**< For address records: don't create a reverse (PTR) entry */
+    PUBLISH_NO_COOKIE = 32,  ///< For service records: do not implicitly add the local service cookie to TXT data
-    PUBLISH_NO_COOKIE = 32, /**< For service records: do not implicitly add the local service cookie to TXT data */
+    PUBLISH_UPDATE = 64,  ///< Update existing records instead of adding new ones
-    /** \endcond */
+    PUBLISH_USE_WIDE_AREA = 128,  ///< Register the record using wide area DNS (i.e. unicast DNS update)
-    PUBLISH_UPDATE = 64, /**< Update existing records instead of adding new ones */
+    PUBLISH_USE_MULTICAST = 256  ///< Register the record using multicast DNS
-    /** \cond fulldocs */
-    PUBLISH_USE_WIDE_AREA = 128, /**< Register the record using wide area DNS (i.e. unicast DNS update) */
-    PUBLISH_USE_MULTICAST = 256 /**< Register the record using multicast DNS */
-    /** \endcond */
   };
 
   using IfIndex = int;

src/platform/windows/audio.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/windows/audio.cpp
- * @brief todo
+ * @brief Definitions for Windows audio capture.
  */
 #define INITGUID
 #include <audioclient.h>
@@ -91,10 +91,10 @@ namespace platf::audio {
 
   struct format_t {
     enum type_e : int {
-      none,
+      none,  ///< No format
-      stereo,
+      stereo,  ///< Stereo
-      surr51,
+      surr51,  ///< Surround 5.1
-      surr71,
+      surr71,  ///< Surround 7.1
     } type;
 
     std::string_view name;
@@ -327,8 +327,7 @@ namespace platf::audio {
 
     /**
      * @brief Checks if the default rendering device changed and resets the change flag
-     *
+     * @return `true` if the device changed since last call
-     * @return true if the device changed since last call
      */
     bool
     check_default_render_device_changed() {
@@ -689,9 +688,7 @@ namespace platf::audio {
 
     /**
      * @brief Gets information encoded in the raw sink name
-     *
      * @param sink The raw sink name
-     *
      * @return A pair of type and the real sink name
      */
     std::pair<format_t::type_e, std::string_view>

src/platform/windows/display.h

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/windows/display.h
- * @brief todo
+ * @brief Declarations for the Windows display backend.
  */
 #pragma once
 
@@ -187,12 +187,12 @@ namespace platf::dxgi {
     util::safe_ptr_v2<std::remove_pointer_t<HANDLE>, BOOL, CloseHandle> timer;
 
     typedef enum _D3DKMT_SCHEDULINGPRIORITYCLASS {
-      D3DKMT_SCHEDULINGPRIORITYCLASS_IDLE,
+      D3DKMT_SCHEDULINGPRIORITYCLASS_IDLE,  ///< Idle priority class
-      D3DKMT_SCHEDULINGPRIORITYCLASS_BELOW_NORMAL,
+      D3DKMT_SCHEDULINGPRIORITYCLASS_BELOW_NORMAL,  ///< Below normal priority class
-      D3DKMT_SCHEDULINGPRIORITYCLASS_NORMAL,
+      D3DKMT_SCHEDULINGPRIORITYCLASS_NORMAL,  ///< Normal priority class
-      D3DKMT_SCHEDULINGPRIORITYCLASS_ABOVE_NORMAL,
+      D3DKMT_SCHEDULINGPRIORITYCLASS_ABOVE_NORMAL,  ///< Above normal priority class
-      D3DKMT_SCHEDULINGPRIORITYCLASS_HIGH,
+      D3DKMT_SCHEDULINGPRIORITYCLASS_HIGH,  ///< High priority class
-      D3DKMT_SCHEDULINGPRIORITYCLASS_REALTIME
+      D3DKMT_SCHEDULINGPRIORITYCLASS_REALTIME  ///< Realtime priority class
     } D3DKMT_SCHEDULINGPRIORITYCLASS;
 
     typedef UINT D3DKMT_HANDLE;

src/platform/windows/display_base.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/windows/display_base.cpp
- * @brief todo
+ * @brief Definitions for the Windows display base code.
  */
 #include <cmath>
 #include <initguid.h>

src/platform/windows/display_ram.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/windows/display_ram.cpp
- * @brief todo
+ * @brief Definitions for handling ram.
  */
 #include "display.h"
 

src/platform/windows/display_vram.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/windows/display_vram.cpp
- * @brief todo
+ * @brief Definitions for handling video ram.
  */
 #include <cmath>
 
@@ -1617,10 +1617,10 @@ namespace platf::dxgi {
   }
 
   /**
-   * @brief Checks that a given codec is supported by the display device.
+   * @brief Check that a given codec is supported by the display device.
    * @param name The FFmpeg codec name (or similar for non-FFmpeg codecs).
    * @param config The codec configuration.
-   * @return true if supported, false otherwise.
+   * @return `true` if supported, `false` otherwise.
    */
   bool
   display_vram_t::is_codec_supported(std::string_view name, const ::video::config_t &config) {

src/platform/windows/display_wgc.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/windows/display_wgc.cpp
- * @brief WinRT Windows.Graphics.Capture API
+ * @brief Definitions for WinRT Windows.Graphics.Capture API
  */
 #include <dxgi1_2.h>
 
@@ -26,7 +26,8 @@ namespace winrt {
   HRESULT __stdcall CreateDirect3D11DeviceFromDXGIDevice(::IDXGIDevice *dxgiDevice, ::IInspectable **graphicsDevice);
   }
 
-  /* Windows structures sometimes have compile-time GUIDs. GCC supports this, but in a roundabout way.
+  /**
+   * Windows structures sometimes have compile-time GUIDs. GCC supports this, but in a roundabout way.
    * If WINRT_IMPL_HAS_DECLSPEC_UUID is true, then the compiler supports adding this attribute to a struct. For example, Visual Studio.
    * If not, then MinGW GCC has a workaround to assign a GUID to a structure.
    */
@@ -66,8 +67,8 @@ namespace platf::dxgi {
   }
 
   /**
-   * Initialize the Windows.Graphics.Capture backend.
+   * @brief Initialize the Windows.Graphics.Capture backend.
-   * @return 0 on success
+   * @return 0 on success, -1 on failure.
    */
   int
   wgc_capture_t::init(display_base_t *display, const ::video::config_t &config) {
@@ -161,7 +162,7 @@ namespace platf::dxgi {
   }
 
   /**
-   * Get the next frame from the producer thread.
+   * @brief Get the next frame from the producer thread.
    * If not available, the capture thread blocks until one is, or the wait times out.
    * @param timeout how long to wait for the next frame
    * @param out a texture containing the frame just captured
@@ -227,11 +228,11 @@ namespace platf::dxgi {
   }
 
   /**
-   * Get the next frame from the Windows.Graphics.Capture API and copy it into a new snapshot texture.
+   * @brief Get the next frame from the Windows.Graphics.Capture API and copy it into a new snapshot texture.
    * @param pull_free_image_cb call this to get a new free image from the video subsystem.
    * @param img_out the captured frame is returned here
    * @param timeout how long to wait for the next frame
-   * @param cursor_visible
+   * @param cursor_visible whether to capture the cursor
    */
   capture_e
   display_wgc_ram_t::snapshot(const pull_free_image_cb_t &pull_free_image_cb, std::shared_ptr<platf::img_t> &img_out, std::chrono::milliseconds timeout, bool cursor_visible) {

src/platform/windows/input.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/windows/input.cpp
- * @brief todo
+ * @brief Definitions for input handling on Windows.
  */
 #define WINVER 0x0A00
 #include <windows.h>

src/platform/windows/misc.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/windows/misc.cpp
- * @brief todo
+ * @brief Miscellaneous definitions for Windows.
  */
 #include <csignal>
 #include <filesystem>
@@ -462,7 +462,7 @@ namespace platf {
    * @brief Impersonate the current user and invoke the callback function.
    * @param user_token A handle to the user's token that was obtained from the shell.
    * @param callback A function that will be executed while impersonating the user.
-   * @return An `std::error_code` object that will store any error that occurred during the impersonation
+   * @return Object that will store any error that occurred during the impersonation
    */
   std::error_code
   impersonate_current_user(HANDLE user_token, std::function<void()> callback) {
@@ -496,11 +496,11 @@ namespace platf {
   }
 
   /**
-   * @brief A function to create a `STARTUPINFOEXW` structure for launching a process.
+   * @brief Create a `STARTUPINFOEXW` structure for launching a process.
    * @param file A pointer to a `FILE` object that will be used as the standard output and error for the new process, or null if not needed.
    * @param job A job object handle to insert the new process into. This pointer must remain valid for the life of this startup info!
    * @param ec A reference to a `std::error_code` object that will store any error that occurred during the creation of the structure.
-   * @return A `STARTUPINFOEXW` structure that contains information about how to launch the new process.
+   * @return A structure that contains information about how to launch the new process.
    */
   STARTUPINFOEXW
   create_startup_info(FILE *file, HANDLE *job, std::error_code &ec) {
@@ -615,7 +615,7 @@ namespace platf {
   }
 
   /**
-   * @brief This function quotes/escapes an argument according to the Windows parsing convention.
+   * @brief Quote/escape an argument according to the Windows parsing convention.
    * @param argument The raw argument to process.
    * @return An argument string suitable for use by CreateProcess().
    */
@@ -655,7 +655,7 @@ namespace platf {
   }
 
   /**
-   * @brief This function escapes an argument according to cmd's parsing convention.
+   * @brief Escape an argument according to cmd's parsing convention.
    * @param argument An argument already escaped by `escape_argument()`.
    * @return An argument string suitable for use by cmd.exe.
    */
@@ -676,7 +676,7 @@ namespace platf {
   }
 
   /**
-   * @brief This function resolves the given raw command into a proper command string for CreateProcess().
+   * @brief Resolve the given raw command into a proper command string for CreateProcess().
    * @details This converts URLs and non-executable file paths into a runnable command like ShellExecute().
    * @param raw_cmd The raw command provided by the user.
    * @param working_dir The working directory for the new process.
@@ -1701,11 +1701,6 @@ namespace platf {
     return {};
   }
 
-  /**
-   * @brief Converts a UTF-8 string into a UTF-16 wide string.
-   * @param string The UTF-8 string.
-   * @return The converted UTF-16 wide string.
-   */
   std::wstring
   from_utf8(const std::string &string) {
     // No conversion needed if the string is empty
@@ -1733,11 +1728,6 @@ namespace platf {
     return output;
   }
 
-  /**
-   * @brief Converts a UTF-16 wide string into a UTF-8 string.
-   * @param string The UTF-16 wide string.
-   * @return The converted UTF-8 string.
-   */
   std::string
   to_utf8(const std::wstring &string) {
     // No conversion needed if the string is empty

src/platform/windows/misc.h

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/windows/misc.h
- * @brief todo
+ * @brief Miscellaneous declarations for Windows.
  */
 #pragma once
 
@@ -22,7 +22,7 @@ namespace platf {
   qpc_time_difference(int64_t performance_counter1, int64_t performance_counter2);
 
   /**
-   * @brief Converts a UTF-8 string into a UTF-16 wide string.
+   * @brief Convert a UTF-8 string into a UTF-16 wide string.
    * @param string The UTF-8 string.
    * @return The converted UTF-16 wide string.
    */
@@ -30,7 +30,7 @@ namespace platf {
   from_utf8(const std::string &string);
 
   /**
-   * @brief Converts a UTF-16 wide string into a UTF-8 string.
+   * @brief Convert a UTF-16 wide string into a UTF-8 string.
    * @param string The UTF-16 wide string.
    * @return The converted UTF-8 string.
    */

src/platform/windows/nvprefs/driver_settings.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/nvprefs/driver_settings.cpp
+ * @brief Definitions for nvidia driver settings.
+ */
 // local includes
 #include "driver_settings.h"
 #include "nvprefs_common.h"

src/platform/windows/nvprefs/driver_settings.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/nvprefs/driver_settings.h
+ * @brief Declarations for nvidia driver settings.
+ */
 #pragma once
 
 // nvapi headers

src/platform/windows/nvprefs/nvapi_opensource_wrapper.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/nvprefs/nvapi_opensource_wrapper.cpp
+ * @brief Definitions for the NVAPI wrapper.
+ */
 // standard library headers
 #include <map>
 

src/platform/windows/nvprefs/nvprefs_common.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/nvprefs/nvprefs_common.cpp
+ * @brief Definitions for common nvidia preferences.
+ */
 // local includes
 #include "nvprefs_common.h"
 #include "src/logging.h"

src/platform/windows/nvprefs/nvprefs_common.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/nvprefs/nvprefs_common.h
+ * @brief Declarations for common nvidia preferences.
+ */
 #pragma once
 
 // sunshine utility header for generic smart pointers