From 99d315f712ef40217ac6b2f596d7d5890b8ffbfd Mon Sep 17 00:00:00 2001 From: ReenigneArcher <42013603+ReenigneArcher@users.noreply.github.com> Date: Wed, 26 Jun 2024 15:44:47 -0400 Subject: [PATCH] docs(src): add examples alias and general cleanup --- docs/Doxyfile | 14 +- docs/source/conf.py | 7 + docs/source/source_code/source_code.rst | 59 +++---- src/audio.h | 22 +-- src/config.cpp | 104 ++++++------ src/config.h | 12 +- src/confighttp.cpp | 4 +- src/entry_handler.cpp | 115 +------------- src/entry_handler.h | 125 +++++++++++++-- src/file_handler.cpp | 33 +--- src/file_handler.h | 38 ++++- src/input.cpp | 65 ++++---- src/logging.cpp | 23 ++- src/main.cpp | 14 +- src/network.cpp | 41 +---- src/network.h | 24 +-- src/nvhttp.cpp | 28 ++-- src/nvhttp.h | 2 +- src/platform/common.h | 114 +++++++------- src/platform/linux/graphics.cpp | 6 +- src/platform/linux/input/legacy_input.cpp | 90 +++++------ src/platform/linux/misc.cpp | 10 +- src/platform/linux/misc.h | 6 +- src/platform/linux/publish.cpp | 184 +++++++++++----------- src/platform/linux/wayland.cpp | 2 +- src/platform/linux/wayland.h | 12 +- src/platform/windows/audio.cpp | 13 +- src/platform/windows/display.h | 12 +- src/platform/windows/display_vram.cpp | 4 +- src/platform/windows/display_wgc.cpp | 2 +- src/platform/windows/misc.cpp | 16 +- src/platform/windows/misc.h | 4 +- src/process.cpp | 2 +- src/process.h | 6 +- src/rtsp.cpp | 18 +-- src/stream.cpp | 8 +- src/stream.h | 8 +- src/system_tray.cpp | 2 +- src/task_pool.h | 2 +- src/upnp.cpp | 2 +- src/utility.h | 2 +- src/video.cpp | 48 +++--- src/video.h | 12 +- 43 files changed, 614 insertions(+), 701 deletions(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index 281b84291d6..2b07d93dc3e 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -24,9 +24,11 @@ # must be first DOXYFILE_ENCODING = UTF-8 -# https://breathe.readthedocs.io/en/latest/markups.html#aliases -ALIASES = "rst=^^\verbatim embed:rst:leading-asterisk^^" -ALIASES += "endrst=\endverbatim" +ALIASES = "" +ALIASES += "examples=^^**Examples**^^@code{.cpp}" +ALIASES += "end_examples=@endcode^^" +ALIASES += "rst=^^\verbatim embed:rst:leading-asterisk^^" +ALIASES += "end_rst=\endverbatim" DISABLE_INDEX = NO DOCBOOK_OUTPUT = doxydocbook @@ -79,4 +81,10 @@ WARN_AS_ERROR = FAIL_ON_WARNINGS # TODO: Enable this when we have complete documentation WARN_IF_UNDOCUMENTED = NO +WARN_IF_DOC_ERROR = YES +WARN_IF_INCOMPLETE_DOC = YES +WARN_IF_UNDOC_ENUM_VAL = YES +WARN_NO_PARAMDOC = YES +WARNINGS = YES + XML_OUTPUT = doxyxml diff --git a/docs/source/conf.py b/docs/source/conf.py index eb3845e65a5..8307055c0a0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -7,6 +7,7 @@ # standard imports from datetime import datetime import os +import shutil import subprocess from typing import Mapping, Optional @@ -148,6 +149,12 @@ def _run_subprocess( exist_ok=True, ) +# remove existing html files +# doxygen builds will not re-generated if the html directory already exists +html_dir = os.path.join(source_dir, 'build', 'html') +if os.path.exists(html_dir): + shutil.rmtree(html_dir) + # run doxygen doxy_proc = _run_subprocess( args_list=[doxygen_cmd, 'Doxyfile'], diff --git a/docs/source/source_code/source_code.rst b/docs/source/source_code/source_code.rst index 467f331c768..a5a45cd1227 100644 --- a/docs/source/source_code/source_code.rst +++ b/docs/source/source_code/source_code.rst @@ -1,56 +1,37 @@ Source Code =========== We are in process of improving the source code documentation. Code should be documented using Doxygen syntax. -Some examples exist in `main.h` and `main.cpp`. In order for documentation within the code to appear in the -rendered docs, the definition of the object must be in a header file, although the documentation itself can (and -should) be in the source file. +Many examples exist throughout the codebase. Example Documentation Blocks ---------------------------- **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 - } + /** + * @brief Main application entry point. + * @param argc The number of arguments. + * @param argv The arguments. + * + * @examples + * main(1, const char* args[] = {"hello", "markdown", nullptr}); + * @end_examples + */ + int main(int argc, char *argv[]); -**file.cpp** (with ReStructuredText) +.. 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. -.. code-block:: cpp +Doxygen Aliases +--------------- +We have defined some custom aliases to simplify documenting examples. - /** - * @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 - } +- ``@examples`` - Start of an example block. This will format the following text as ``cpp``. +- ``@end_examples`` - End of an example block. +- ``@rst`` - Start of a reStructuredText block. This will format the following text as reStructuredText. +- ``@end_rst`` - End of a reStructuredText block. Source ------ diff --git a/src/audio.h b/src/audio.h index cbe4ae98b1c..9d096f122b7 100644 --- a/src/audio.h +++ b/src/audio.h @@ -8,13 +8,13 @@ #include "utility.h" namespace audio { enum stream_config_e : int { - STEREO, - HIGH_STEREO, - SURROUND51, - HIGH_SURROUND51, - SURROUND71, - HIGH_SURROUND71, - MAX_STREAM_CONFIG + STEREO, ///< Stereo + HIGH_STEREO, ///< High stereo + SURROUND51, ///< Surround 5.1 + HIGH_SURROUND51, ///< High surround 5.1 + SURROUND71, ///< Surround 7.1 + HIGH_SURROUND71, ///< High surround 7.1 + MAX_STREAM_CONFIG ///< Maximum audio stream configuration }; struct opus_stream_config_t { @@ -37,10 +37,10 @@ namespace audio { struct config_t { enum flags_e : int { - HIGH_QUALITY, - HOST_AUDIO, - CUSTOM_SURROUND_PARAMS, - MAX_FLAGS + HIGH_QUALITY, ///< High quality audio + HOST_AUDIO, ///< Host audio + CUSTOM_SURROUND_PARAMS, ///< Custom surround parameters + MAX_FLAGS ///< Maximum number of flags }; int packetDuration; diff --git a/src/config.cpp b/src/config.cpp index a466eb12a62..c5452354e3c 100644 --- a/src/config.cpp +++ b/src/config.cpp @@ -107,72 +107,72 @@ namespace config { #endif enum class quality_av1_e : int { - speed = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_SPEED, - quality = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_QUALITY, - balanced = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_BALANCED + speed = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_SPEED, ///< Speed preset + quality = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_QUALITY, ///< Quality preset + balanced = AMF_VIDEO_ENCODER_AV1_QUALITY_PRESET_BALANCED ///< Balanced preset }; enum class quality_hevc_e : int { - speed = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_SPEED, - quality = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_QUALITY, - balanced = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_BALANCED + speed = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_SPEED, ///< Speed preset + quality = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_QUALITY, ///< Quality preset + balanced = AMF_VIDEO_ENCODER_HEVC_QUALITY_PRESET_BALANCED ///< Balanced preset }; enum class quality_h264_e : int { - speed = AMF_VIDEO_ENCODER_QUALITY_PRESET_SPEED, - quality = AMF_VIDEO_ENCODER_QUALITY_PRESET_QUALITY, - balanced = AMF_VIDEO_ENCODER_QUALITY_PRESET_BALANCED + speed = AMF_VIDEO_ENCODER_QUALITY_PRESET_SPEED, ///< Speed preset + quality = AMF_VIDEO_ENCODER_QUALITY_PRESET_QUALITY, ///< Quality preset + balanced = AMF_VIDEO_ENCODER_QUALITY_PRESET_BALANCED ///< Balanced preset }; enum class rc_av1_e : int { - cbr = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_CBR, - cqp = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_CONSTANT_QP, - vbr_latency = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_LATENCY_CONSTRAINED_VBR, - vbr_peak = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_PEAK_CONSTRAINED_VBR + cbr = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_CBR, ///< CBR + cqp = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_CONSTANT_QP, ///< CQP + vbr_latency = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_LATENCY_CONSTRAINED_VBR, ///< VBR with latency constraints + vbr_peak = AMF_VIDEO_ENCODER_AV1_RATE_CONTROL_METHOD_PEAK_CONSTRAINED_VBR ///< VBR with peak constraints }; enum class rc_hevc_e : int { - cbr = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_CBR, - cqp = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_CONSTANT_QP, - vbr_latency = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_LATENCY_CONSTRAINED_VBR, - vbr_peak = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_PEAK_CONSTRAINED_VBR + cbr = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_CBR, ///< CBR + cqp = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_CONSTANT_QP, ///< CQP + vbr_latency = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_LATENCY_CONSTRAINED_VBR, ///< VBR with latency constraints + vbr_peak = AMF_VIDEO_ENCODER_HEVC_RATE_CONTROL_METHOD_PEAK_CONSTRAINED_VBR ///< VBR with peak constraints }; enum class rc_h264_e : int { - cbr = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_CBR, - cqp = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_CONSTANT_QP, - vbr_latency = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_LATENCY_CONSTRAINED_VBR, - vbr_peak = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_PEAK_CONSTRAINED_VBR + cbr = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_CBR, ///< CBR + cqp = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_CONSTANT_QP, ///< CQP + vbr_latency = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_LATENCY_CONSTRAINED_VBR, ///< VBR with latency constraints + vbr_peak = AMF_VIDEO_ENCODER_RATE_CONTROL_METHOD_PEAK_CONSTRAINED_VBR ///< VBR with peak constraints }; enum class usage_av1_e : int { - transcoding = AMF_VIDEO_ENCODER_AV1_USAGE_TRANSCODING, - webcam = AMF_VIDEO_ENCODER_AV1_USAGE_WEBCAM, - lowlatency_high_quality = AMF_VIDEO_ENCODER_AV1_USAGE_LOW_LATENCY_HIGH_QUALITY, - lowlatency = AMF_VIDEO_ENCODER_AV1_USAGE_LOW_LATENCY, - ultralowlatency = AMF_VIDEO_ENCODER_AV1_USAGE_ULTRA_LOW_LATENCY + transcoding = AMF_VIDEO_ENCODER_AV1_USAGE_TRANSCODING, ///< Transcoding preset + webcam = AMF_VIDEO_ENCODER_AV1_USAGE_WEBCAM, ///< Webcam preset + lowlatency_high_quality = AMF_VIDEO_ENCODER_AV1_USAGE_LOW_LATENCY_HIGH_QUALITY, ///< Low latency high quality preset + lowlatency = AMF_VIDEO_ENCODER_AV1_USAGE_LOW_LATENCY, ///< Low latency preset + ultralowlatency = AMF_VIDEO_ENCODER_AV1_USAGE_ULTRA_LOW_LATENCY ///< Ultra low latency preset }; enum class usage_hevc_e : int { - transcoding = AMF_VIDEO_ENCODER_HEVC_USAGE_TRANSCODING, - webcam = AMF_VIDEO_ENCODER_HEVC_USAGE_WEBCAM, - lowlatency_high_quality = AMF_VIDEO_ENCODER_HEVC_USAGE_LOW_LATENCY_HIGH_QUALITY, - lowlatency = AMF_VIDEO_ENCODER_HEVC_USAGE_LOW_LATENCY, - ultralowlatency = AMF_VIDEO_ENCODER_HEVC_USAGE_ULTRA_LOW_LATENCY + transcoding = AMF_VIDEO_ENCODER_HEVC_USAGE_TRANSCODING, ///< Transcoding preset + webcam = AMF_VIDEO_ENCODER_HEVC_USAGE_WEBCAM, ///< Webcam preset + lowlatency_high_quality = AMF_VIDEO_ENCODER_HEVC_USAGE_LOW_LATENCY_HIGH_QUALITY, ///< Low latency high quality preset + lowlatency = AMF_VIDEO_ENCODER_HEVC_USAGE_LOW_LATENCY, ///< Low latency preset + ultralowlatency = AMF_VIDEO_ENCODER_HEVC_USAGE_ULTRA_LOW_LATENCY ///< Ultra low latency preset }; enum class usage_h264_e : int { - transcoding = AMF_VIDEO_ENCODER_USAGE_TRANSCODING, - webcam = AMF_VIDEO_ENCODER_USAGE_WEBCAM, - lowlatency_high_quality = AMF_VIDEO_ENCODER_USAGE_LOW_LATENCY_HIGH_QUALITY, - lowlatency = AMF_VIDEO_ENCODER_USAGE_LOW_LATENCY, - ultralowlatency = AMF_VIDEO_ENCODER_USAGE_ULTRA_LOW_LATENCY + transcoding = AMF_VIDEO_ENCODER_USAGE_TRANSCODING, ///< Transcoding preset + webcam = AMF_VIDEO_ENCODER_USAGE_WEBCAM, ///< Webcam preset + lowlatency_high_quality = AMF_VIDEO_ENCODER_USAGE_LOW_LATENCY_HIGH_QUALITY, ///< Low latency high quality preset + lowlatency = AMF_VIDEO_ENCODER_USAGE_LOW_LATENCY, ///< Low latency preset + ultralowlatency = AMF_VIDEO_ENCODER_USAGE_ULTRA_LOW_LATENCY ///< Ultra low latency preset }; enum coder_e : int { - _auto = AMF_VIDEO_ENCODER_UNDEFINED, - cabac = AMF_VIDEO_ENCODER_CABAC, - cavlc = AMF_VIDEO_ENCODER_CALV + _auto = AMF_VIDEO_ENCODER_UNDEFINED, ///< Auto + cabac = AMF_VIDEO_ENCODER_CABAC, ///< CABAC + cavlc = AMF_VIDEO_ENCODER_CALV ///< CAVLC }; template @@ -226,19 +226,19 @@ namespace config { namespace qsv { enum preset_e : int { - veryslow = 1, - slower = 2, - slow = 3, - medium = 4, - fast = 5, - faster = 6, - veryfast = 7 + veryslow = 1, ///< veryslow preset + slower = 2, ///< slower preset + slow = 3, ///< slow preset + medium = 4, ///< medium preset + fast = 5, ///< fast preset + faster = 6, ///< faster preset + veryfast = 7 ///< veryfast preset }; enum cavlc_e : int { - _auto = false, - enabled = true, - disabled = false + _auto = false, ///< Auto + enabled = true, ///< Enabled + disabled = false ///< Disabled }; std::optional @@ -269,9 +269,9 @@ namespace config { namespace vt { enum coder_e : int { - _auto = 0, - cabac, - cavlc + _auto = 0, ///< Auto + cabac, ///< CABAC + cavlc ///< CAVLC }; int diff --git a/src/config.h b/src/config.h index 308c774eadb..60f57c35909 100644 --- a/src/config.h +++ b/src/config.h @@ -143,12 +143,12 @@ namespace config { namespace flag { enum flag_e : std::size_t { - PIN_STDIN = 0, // Read PIN from stdin instead of http - FRESH_STATE, // Do not load or save state - FORCE_VIDEO_HEADER_REPLACE, // force replacing headers inside video data - UPNP, // Try Universal Plug 'n Play - CONST_PIN, // Use "universal" pin - FLAG_SIZE + PIN_STDIN = 0, ///< Read PIN from stdin instead of http + FRESH_STATE, ///< Do not load or save state + FORCE_VIDEO_HEADER_REPLACE, ///< force replacing headers inside video data + UPNP, ///< Try Universal Plug 'n Play + CONST_PIN, ///< Use "universal" pin + FLAG_SIZE ///< Number of flags }; } diff --git a/src/confighttp.cpp b/src/confighttp.cpp index 9b2c0d95f49..f43f8962c71 100644 --- a/src/confighttp.cpp +++ b/src/confighttp.cpp @@ -54,8 +54,8 @@ namespace confighttp { using req_https_t = std::shared_ptr::Request>; enum class op_e { - ADD, - REMOVE + ADD, ///< ADD + REMOVE ///< REMOVE }; void diff --git a/src/entry_handler.cpp b/src/entry_handler.cpp index 8d17b7d270a..ada85265796 100644 --- a/src/entry_handler.cpp +++ b/src/entry_handler.cpp @@ -1,6 +1,6 @@ /** * @file entry_handler.cpp - * @brief Entry point related functions. + * @brief Definitions for entry handling functions. */ // standard includes @@ -27,28 +27,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 +40,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 +51,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 +79,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 +95,6 @@ namespace lifetime { } } - /** - * @brief Breaks into the debugger or terminates Sunshine if no debugger is attached. - */ void debug_trap() { #ifdef _WIN32 @@ -178,9 +104,6 @@ namespace lifetime { #endif } - /** - * @brief Gets the argv array passed to main(). - */ char ** get_argv() { return argv; @@ -188,10 +111,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 +203,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 +215,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 +241,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..."; diff --git a/src/entry_handler.h b/src/entry_handler.h index bdab361cf0c..1c23e27d4e9 100644 --- a/src/entry_handler.h +++ b/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,149 @@ #include "thread_pool.h" #include "thread_safe.h" -// functions +/** + * @brief Launch the Web UI. + * + * @examples + * launch_ui(); + * @end_examples + */ void launch_ui(); + +/** + * @brief Launch the Web UI at a specific endpoint. + * + * @examples + * launch_ui_with_path("/pin"); + * @end_examples + */ void launch_ui_with_path(std::string path); -#ifdef _WIN32 -// windows only functions -bool -is_gamestream_enabled(); -#endif - +/** + * @brief Functions for handling command line arguments. + */ 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"}); + * @end_examples + */ 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"); + * @end_examples + */ int - help(const char *name, int argc, char *argv[]); + help(const char *name); + + /** + * @brief Print the version to stdout, then exit. + * + * @examples + * version(); + * @end_examples + */ int - version(const char *name, int argc, char *argv[]); -#ifdef _WIN32 + version(); + +#if defined(_WIN32) || defined(DOXYGEN) + /** + * @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(); + * @end_examples + */ 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 +#if defined(_WIN32) || defined(DOXYGEN) +/** + * @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(); + * @end_examples + */ bool is_service_running(); + /** + * @brief Start the service and wait for startup to complete. + * + * @examples + * start_service(); + * @end_examples + */ bool start_service(); + /** + * @brief Wait for the UI to be ready after Sunshine startup. + * + * @examples + * wait_for_ui_ready(); + * @end_examples + */ bool wait_for_ui_ready(); } // namespace service_ctrl diff --git a/src/file_handler.cpp b/src/file_handler.cpp index 6f11bb709de..b5c9638a1b8 100644 --- a/src/file_handler.cpp +++ b/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(in)), std::istreambuf_iterator() }; } - /** - * @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); diff --git a/src/file_handler.h b/src/file_handler.h index 5ff8015c635..96f66d7b2cf 100644 --- a/src/file_handler.h +++ b/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 +/** + * @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"); + * @end_examples + */ 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"); + * @end_examples + */ 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"); + * @end_examples + */ 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"); + * @end_examples + */ int write_file(const char *path, const std::string_view &contents); } // namespace file_handler diff --git a/src/input.cpp b/src/input.cpp index c9efc343bfa..e3e4f9f76c2 100644 --- a/src/input.cpp +++ b/src/input.cpp @@ -49,9 +49,9 @@ namespace input { constexpr auto VKEY_RMENU = 0xA5; enum class button_state_e { - NONE, - DOWN, - UP + NONE, ///< No button state + DOWN, ///< Button is down + UP ///< Button is up }; template @@ -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, - ALT = 0x2, - SHIFT = 0x4, - - SHORTCUT = CTRL | ALT | SHIFT + CTRL = 0x1, ///< Control key + ALT = 0x2, ///< Alt key + SHIFT = 0x4, ///< Shift key + SHORTCUT = CTRL | ALT | SHIFT ///< Shortcut combination }; input_t( @@ -191,11 +190,9 @@ namespace input { }; /** - * Apply shortcut based on VKEY - * On success - * return > 0 - * On nothing - * return 0 + * @brief Apply shortcut based on VKEY + * @param keyCode The VKEY code + * @return 0 if no shortcut applied, > 0 if shortcut applied. */ 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. @@ -520,7 +517,7 @@ namespace input { } /** - * @brief Scales the ellipse axes according to the provided size. + * @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. @@ -529,7 +526,7 @@ namespace input { std::pair scale_client_contact_area(const std::pair &val, uint16_t rotation, const std::pair &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 +647,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 +1239,16 @@ namespace input { } enum class batch_result_e { - batched, // This entry was batched with the source entry - not_batchable, // Not eligible to batch but continue attempts to batch - terminate_batch, // Stop trying to batch with this entry + batched, ///< This entry was batched with the source entry + not_batchable, ///< Not eligible to batch but continue attempts to batch + 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 +1272,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 +1290,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 +1311,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 +1331,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 +1360,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 +1395,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 +1429,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 +1470,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 +1494,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) { diff --git a/src/logging.cpp b/src/logging.cpp index e03bcbf5134..6670a0d7dfc 100644 --- a/src/logging.cpp +++ b/src/logging.cpp @@ -48,10 +48,9 @@ namespace logging { /** * @brief Deinitialize the logging system. * - * EXAMPLES: - * ```cpp + * @examples * deinit(); - * ``` + * @end_examples */ void deinit() { @@ -64,12 +63,10 @@ namespace logging { * @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 + * @return An object that will deinitialize the logging system when it goes out of scope. + * @examples * log_init(2, "sunshine.log"); - * ``` + * @end_examples */ [[nodiscard]] std::unique_ptr init(int min_log_level, const std::string &log_file) { @@ -172,10 +169,9 @@ namespace logging { /** * @brief Flush the log. * - * EXAMPLES: - * ```cpp + * @examples * log_flush(); - * ``` + * @end_examples */ void log_flush() { @@ -188,10 +184,9 @@ namespace logging { * @brief Print help to stdout. * @param name The name of the program. * - * EXAMPLES: - * ```cpp + * @examples * print_help("sunshine"); - * ``` + * @end_examples */ void print_help(const char *name) { diff --git a/src/main.cpp b/src/main.cpp index ec3aa9b56a1..6d864b2db50 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -44,11 +44,11 @@ on_signal(int sig, FN &&fn) { } std::map> cmd_to_func { - { "creds"sv, args::creds }, - { "help"sv, args::help }, - { "version"sv, args::version }, + { "creds"sv, [](const char *name, int argc, char **argv) { return args::creds(name, argc, argv); } }, + { "help"sv, [](const char *name, int argc, char **argv) { return args::help(name); } }, + { "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 }; @@ -78,11 +78,9 @@ SessionMonitorWindowProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam) { * @brief Main application entry point. * @param argc The number of arguments. * @param argv The arguments. - * - * EXAMPLES: - * ```cpp + * @examples * main(1, const char* args[] = {"sunshine", nullptr}); - * ``` + * @end_examples */ int main(int argc, char *argv[]) { diff --git a/src/network.cpp b/src/network.cpp index 2784afebc39..0490beb2a60 100644 --- a/src/network.cpp +++ b/src/network.cpp @@ -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()); @@ -230,12 +197,10 @@ namespace net { /** * @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 + * @return The mapped port number. + * @examples * std::uint16_t mapped_port = net::map_port(1); - * ``` + * @end_examples */ std::uint16_t map_port(int port) { diff --git a/src/network.h b/src/network.h index 5fe842e7c8b..b611f25a89b 100644 --- a/src/network.h +++ b/src/network.h @@ -25,14 +25,14 @@ namespace net { using packet_t = util::safe_ptr; enum net_e : int { - PC, - LAN, - WAN + PC, ///< PC + LAN, ///< LAN + WAN ///< WAN }; enum af_e : int { - IPV4, - BOTH + IPV4, ///< IPv4 only + BOTH ///< IPv4 and IPv6 }; net_e @@ -47,15 +47,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 +63,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 +72,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 +81,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 +90,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. */ diff --git a/src/nvhttp.cpp b/src/nvhttp.cpp index bd8434e5534..e2870155d84 100644 --- a/src/nvhttp.cpp +++ b/src/nvhttp.cpp @@ -161,8 +161,8 @@ namespace nvhttp { using req_http_t = std::shared_ptr::Request>; enum class op_e { - ADD, - REMOVE + ADD, ///< ADD + REMOVE ///< REMOVE }; std::string @@ -615,11 +615,9 @@ namespace nvhttp { * @param pin The user supplied pin. * @param name The user supplied name. * @return `true` if the pin is correct, `false` otherwise. - * - * EXAMPLES: - * ```cpp + * @examples * bool pin_status = nvhttp::pin("1234", "laptop"); - * ``` + * @end_examples */ bool pin(std::string pin, std::string name) { @@ -1052,11 +1050,9 @@ namespace nvhttp { /** * @brief Start the nvhttp server. - * - * EXAMPLES: - * ```cpp + * @examples * nvhttp::start(); - * ``` + * @end_examples */ void start() { @@ -1190,11 +1186,9 @@ namespace nvhttp { /** * @brief Remove all paired clients. - * - * EXAMPLES: - * ```cpp + * @examples * nvhttp::erase_all_clients(); - * ``` + * @end_examples */ void erase_all_clients() { @@ -1206,11 +1200,9 @@ namespace nvhttp { /** * @brief Remove single client. - * - * EXAMPLES: - * ```cpp + * @examples * nvhttp::unpair_client("4D7BB2DD-5704-A405-B41C-891A022932E1"); - * ``` + * @end_examples */ int unpair_client(std::string uuid) { diff --git a/src/nvhttp.h b/src/nvhttp.h index 6fdf202ac29..16db14f8655 100644 --- a/src/nvhttp.h +++ b/src/nvhttp.h @@ -16,7 +16,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 { diff --git a/src/platform/common.h b/src/platform/common.h index e7e72334703..c21c7d93659 100644 --- a/src/platform/common.h +++ b/src/platform/common.h @@ -87,10 +87,10 @@ namespace platf { }; enum class gamepad_feedback_e { - rumble, - rumble_triggers, - set_motion_event_state, - set_rgb_led, + rumble, ///< Rumble + rumble_triggers, ///< Rumble triggers + set_motion_event_state, ///< Set motion event state + 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_RIGHT, - FRONT_CENTER, - LOW_FREQUENCY, - BACK_LEFT, - BACK_RIGHT, - SIDE_LEFT, - SIDE_RIGHT, - MAX_SPEAKERS, + FRONT_LEFT, ///< Front left + FRONT_RIGHT, ///< Front right + FRONT_CENTER, ///< Front center + LOW_FREQUENCY, ///< Low frequency + BACK_LEFT, ///< Back left + BACK_RIGHT, ///< Back right + SIDE_LEFT, ///< Side left + SIDE_RIGHT, ///< Side right + 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, - vaapi, - dxgi, - cuda, - videotoolbox, - unknown + system, ///< System memory + vaapi, ///< VAAPI + dxgi, ///< DXGI + cuda, ///< CUDA + videotoolbox, ///< VideoToolbox + unknown ///< Unknown }; enum class pix_fmt_e { - yuv420p, - yuv420p10, - nv12, - p010, - unknown + yuv420p, ///< YUV 4:2:0 + yuv420p10, ///< YUV 4:2:0 10-bit + nv12, ///< NV12 + p010, ///< P010 + unknown ///< Unknown }; inline std::string_view @@ -413,11 +413,11 @@ namespace platf { }; enum class capture_e : int { - ok, - reinit, - timeout, - interrupted, - error + ok, ///< Success + reinit, ///< Need to reinitialize + timeout, ///< Timeout + interrupted, ///< Capture was interrupted + error ///< Error }; class display_t { @@ -492,10 +492,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 +570,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(mem_type_e hwdevice_type, const std::string &display_name, const video::config_t &config); @@ -584,7 +584,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 +594,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, - normal, - high, - critical + low, ///< Low priority + normal, ///< Normal priority + high, ///< High priority + critical ///< Critical priority }; void adjust_thread_priority(thread_priority_e priority); @@ -637,12 +637,12 @@ namespace platf { send(send_info_t &send_info); enum class qos_data_type_e : int { - audio, - video + audio, ///< Audio + 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 +662,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 +678,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) - * - * EXAMPLES: - * ```cpp + * @return Screen coordinates of the mouse. + * @examples * auto [x, y] = get_mouse_loc(input); - * ``` + * @end_examples */ util::point_t get_mouse_loc(input_t &input); @@ -709,7 +707,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 +715,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 +724,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 +733,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 +741,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 +749,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 +757,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 +770,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 diff --git a/src/platform/linux/graphics.cpp b/src/platform/linux/graphics.cpp index b085ef0664b..c421ee50323 100644 --- a/src/platform/linux/graphics.cpp +++ b/src/platform/linux/graphics.cpp @@ -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. diff --git a/src/platform/linux/input/legacy_input.cpp b/src/platform/linux/input/legacy_input.cpp index 35534ec445a..d82d98d87f9 100644 --- a/src/platform/linux/input/legacy_input.cpp +++ b/src/platform/linux/input/legacy_input.cpp @@ -1075,10 +1075,9 @@ namespace platf { * @param x Absolute x position. * @param y Absolute y position. * - * EXAMPLES: - * ```cpp + * @examples * x_abs_mouse(input, 0, 0); - * ``` + * @end_examples */ static void x_abs_mouse(input_t &input, float x, float y) { @@ -1129,10 +1128,9 @@ namespace platf { * @param x Absolute x position. * @param y Absolute y position. * - * EXAMPLES: - * ```cpp + * @examples * abs_mouse(input, touch_port, 0, 0); - * ``` + * @end_examples */ void abs_mouse(input_t &input, const touch_port_t &touch_port, float x, float y) { @@ -1161,10 +1159,9 @@ namespace platf { * @param deltaX Relative x position. * @param deltaY Relative y position. * - * EXAMPLES: - * ```cpp + * @examples * x_move_mouse(input, 10, 10); // Move mouse 10 pixels down and right - * ``` + * @end_examples */ static void x_move_mouse(input_t &input, int deltaX, int deltaY) { @@ -1184,10 +1181,9 @@ namespace platf { * @param deltaX Relative x position. * @param deltaY Relative y position. * - * EXAMPLES: - * ```cpp + * @examples * move_mouse(input, 10, 10); // Move mouse 10 pixels down and right - * ``` + * @end_examples */ void move_mouse(input_t &input, int deltaX, int deltaY) { @@ -1219,10 +1215,9 @@ namespace platf { * @param button Which mouse button to emulate. * @param release Whether the event was a press (false) or a release (true) * - * EXAMPLES: - * ```cpp + * @examples * x_button_mouse(input, 1, false); // Press left mouse button - * ``` + * @end_examples */ static void x_button_mouse(input_t &input, int button, bool release) { @@ -1262,10 +1257,9 @@ namespace platf { * @param button Which mouse button to emulate. * @param release Whether the event was a press (false) or a release (true) * - * EXAMPLES: - * ```cpp + * @examples * button_mouse(input, 1, false); // Press left mouse button - * ``` + * @end_examples */ void button_mouse(input_t &input, int button, bool release) { @@ -1349,10 +1343,9 @@ namespace platf { * @param button_pos Which mouse button to emulate for positive scroll. * @param button_neg Which mouse button to emulate for negative scroll. * - * EXAMPLES: - * ```cpp + * @examples * x_scroll(input, 10, 4, 5); - * ``` + * @end_examples */ static void x_scroll(input_t &input, int distance, int button_pos, int button_neg) { @@ -1376,10 +1369,9 @@ namespace platf { * @param input The input_t instance to use. * @param high_res_distance How far to scroll. * - * EXAMPLES: - * ```cpp + * @examples * scroll(input, 1200); - * ``` + * @end_examples */ void scroll(input_t &input, int high_res_distance) { @@ -1410,10 +1402,9 @@ namespace platf { * @param input The input_t instance to use. * @param high_res_distance How far to scroll. * - * EXAMPLES: - * ```cpp + * @examples * hscroll(input, 1200); - * ``` + * @end_examples */ void hscroll(input_t &input, int high_res_distance) { @@ -1455,10 +1446,9 @@ namespace platf { * @param release Whether the event was a press (false) or a release (true). * @param flags SS_KBE_FLAG_* values. * - * EXAMPLES: - * ```cpp + * @examples * x_keyboard(input, 0x5A, false, 0); // Press Z - * ``` + * @end_examples */ static void x_keyboard(input_t &input, uint16_t modcode, bool release, uint8_t flags) { @@ -1490,10 +1480,9 @@ namespace platf { * @param release Whether the event was a press (false) or a release (true). * @param flags SS_KBE_FLAG_* values. * - * EXAMPLES: - * ```cpp + * @examples * keyboard(input, 0x5A, false, 0); // Press Z - * ``` + * @end_examples */ void keyboard_update(input_t &input, uint16_t modcode, bool release, uint8_t flags) { @@ -2107,10 +2096,9 @@ namespace platf { /** * @brief Initialize a new keyboard and return it. * - * EXAMPLES: - * ```cpp + * @examples * auto my_keyboard = keyboard(); - * ``` + * @end_examples */ evdev_t keyboard() { @@ -2136,10 +2124,9 @@ namespace platf { /** * @brief Initialize a new `uinput` virtual relative mouse and return it. * - * EXAMPLES: - * ```cpp + * @examples * auto my_mouse = mouse_rel(); - * ``` + * @end_examples */ evdev_t mouse_rel() { @@ -2187,10 +2174,9 @@ namespace platf { /** * @brief Initialize a new `uinput` virtual absolute mouse and return it. * - * EXAMPLES: - * ```cpp + * @examples * auto my_mouse = mouse_abs(); - * ``` + * @end_examples */ evdev_t mouse_abs() { @@ -2242,10 +2228,9 @@ namespace platf { /** * @brief Initialize a new `uinput` virtual touchscreen and return it. * - * EXAMPLES: - * ```cpp + * @examples * auto my_touchscreen = touchscreen(); - * ``` + * @end_examples */ evdev_t touchscreen() { @@ -2349,10 +2334,9 @@ namespace platf { /** * @brief Initialize a new `uinput` virtual pen pad and return it. * - * EXAMPLES: - * ```cpp + * @examples * auto my_penpad = penpad(); - * ``` + * @end_examples */ evdev_t penpad() { @@ -2448,10 +2432,9 @@ namespace platf { /** * @brief Initialize a new `uinput` virtual X360 gamepad and return it. * - * EXAMPLES: - * ```cpp + * @examples * auto my_x360 = x360(); - * ``` + * @end_examples */ evdev_t x360() { @@ -2525,10 +2508,9 @@ namespace platf { /** * @brief Initialize the input system and return it. * - * EXAMPLES: - * ```cpp + * @examples * auto my_input = input(); - * ``` + * @end_examples */ input_t input() { diff --git a/src/platform/linux/misc.cpp b/src/platform/linux/misc.cpp index 0e081c9be6d..0cb1f1c2465 100644 --- a/src/platform/linux/misc.cpp +++ b/src/platform/linux/misc.cpp @@ -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 diff --git a/src/platform/linux/misc.h b/src/platform/linux/misc.h index 8541bf1650e..709f8e46ad0 100644 --- a/src/platform/linux/misc.h +++ b/src/platform/linux/misc.h @@ -16,9 +16,9 @@ KITTY_USING_MOVE_T(file_t, int, -1, { }); enum class window_system_e { - NONE, - X11, - WAYLAND, + NONE, ///< No window system + X11, ///< X11 + WAYLAND, ///< Wayland }; extern window_system_e window_system; diff --git a/src/platform/linux/publish.cpp b/src/platform/linux/publish.cpp index bc876e7728b..1c37d607c54 100644 --- a/src/platform/linux/publish.cpp +++ b/src/platform/linux/publish.cpp @@ -21,122 +21,118 @@ namespace avahi { * @brief Error codes used by avahi. */ enum err_e { - OK = 0, /**< OK */ - ERR_FAILURE = -1, /**< Generic error code */ - ERR_BAD_STATE = -2, /**< Object was in a bad state */ - ERR_INVALID_HOST_NAME = -3, /**< Invalid host name */ - ERR_INVALID_DOMAIN_NAME = -4, /**< Invalid domain name */ - ERR_NO_NETWORK = -5, /**< No suitable network protocol available */ - ERR_INVALID_TTL = -6, /**< Invalid DNS TTL */ - ERR_IS_PATTERN = -7, /**< RR key is pattern */ - ERR_COLLISION = -8, /**< Name collision */ - ERR_INVALID_RECORD = -9, /**< Invalid RR */ - - ERR_INVALID_SERVICE_NAME = -10, /**< Invalid service name */ - ERR_INVALID_SERVICE_TYPE = -11, /**< Invalid service type */ - ERR_INVALID_PORT = -12, /**< Invalid port number */ - ERR_INVALID_KEY = -13, /**< Invalid key */ - ERR_INVALID_ADDRESS = -14, /**< Invalid address */ - ERR_TIMEOUT = -15, /**< Timeout reached */ - ERR_TOO_MANY_CLIENTS = -16, /**< Too many clients */ - ERR_TOO_MANY_OBJECTS = -17, /**< Too many objects */ - ERR_TOO_MANY_ENTRIES = -18, /**< Too many entries */ - ERR_OS = -19, /**< OS error */ - - ERR_ACCESS_DENIED = -20, /**< Access denied */ - ERR_INVALID_OPERATION = -21, /**< Invalid operation */ - ERR_DBUS_ERROR = -22, /**< An unexpected D-Bus error occurred */ - ERR_DISCONNECTED = -23, /**< Daemon connection failed */ - ERR_NO_MEMORY = -24, /**< Memory exhausted */ - ERR_INVALID_OBJECT = -25, /**< The object passed to this function was invalid */ - ERR_NO_DAEMON = -26, /**< Daemon not running */ - ERR_INVALID_INTERFACE = -27, /**< Invalid interface */ - ERR_INVALID_PROTOCOL = -28, /**< Invalid protocol */ - ERR_INVALID_FLAGS = -29, /**< Invalid flags */ - - ERR_NOT_FOUND = -30, /**< Not found */ - ERR_INVALID_CONFIG = -31, /**< Configuration error */ - ERR_VERSION_MISMATCH = -32, /**< Version mismatch */ - ERR_INVALID_SERVICE_SUBTYPE = -33, /**< Invalid service subtype */ - ERR_INVALID_PACKET = -34, /**< Invalid packet */ - ERR_INVALID_DNS_ERROR = -35, /**< Invalid DNS return code */ - ERR_DNS_FORMERR = -36, /**< DNS Error: Form error */ - ERR_DNS_SERVFAIL = -37, /**< DNS Error: Server Failure */ - ERR_DNS_NXDOMAIN = -38, /**< DNS Error: No such domain */ - ERR_DNS_NOTIMP = -39, /**< DNS Error: Not implemented */ - - ERR_DNS_REFUSED = -40, /**< DNS Error: Operation refused */ - ERR_DNS_YXDOMAIN = -41, - ERR_DNS_YXRRSET = -42, - ERR_DNS_NXRRSET = -43, - ERR_DNS_NOTAUTH = -44, /**< DNS Error: Not authorized */ - ERR_DNS_NOTZONE = -45, - ERR_INVALID_RDATA = -46, /**< Invalid RDATA */ - ERR_INVALID_DNS_CLASS = -47, /**< Invalid DNS class */ - ERR_INVALID_DNS_TYPE = -48, /**< Invalid DNS type */ - ERR_NOT_SUPPORTED = -49, /**< Not supported */ - - ERR_NOT_PERMITTED = -50, /**< Operation not permitted */ - ERR_INVALID_ARGUMENT = -51, /**< Invalid argument */ - ERR_IS_EMPTY = -52, /**< Is empty */ - ERR_NO_CHANGE = -53, /**< The requested operation is invalid because it is redundant */ - - ERR_MAX = -54 + OK = 0, ///< OK + ERR_FAILURE = -1, ///< Generic error code + ERR_BAD_STATE = -2, ///< Object was in a bad state + ERR_INVALID_HOST_NAME = -3, ///< Invalid host name + ERR_INVALID_DOMAIN_NAME = -4, ///< Invalid domain name + ERR_NO_NETWORK = -5, ///< No suitable network protocol available + ERR_INVALID_TTL = -6, ///< Invalid DNS TTL + ERR_IS_PATTERN = -7, ///< RR key is pattern + ERR_COLLISION = -8, ///< Name collision + ERR_INVALID_RECORD = -9, ///< Invalid RR + + ERR_INVALID_SERVICE_NAME = -10, ///< Invalid service name + ERR_INVALID_SERVICE_TYPE = -11, ///< Invalid service type + ERR_INVALID_PORT = -12, ///< Invalid port number + ERR_INVALID_KEY = -13, ///< Invalid key + ERR_INVALID_ADDRESS = -14, ///< Invalid address + ERR_TIMEOUT = -15, ///< Timeout reached + ERR_TOO_MANY_CLIENTS = -16, ///< Too many clients + ERR_TOO_MANY_OBJECTS = -17, ///< Too many objects + ERR_TOO_MANY_ENTRIES = -18, ///< Too many entries + ERR_OS = -19, ///< OS error + + ERR_ACCESS_DENIED = -20, ///< Access denied + ERR_INVALID_OPERATION = -21, ///< Invalid operation + ERR_DBUS_ERROR = -22, ///< An unexpected D-Bus error occurred + ERR_DISCONNECTED = -23, ///< Daemon connection failed + ERR_NO_MEMORY = -24, ///< Memory exhausted + ERR_INVALID_OBJECT = -25, ///< The object passed to this function was invalid + ERR_NO_DAEMON = -26, ///< Daemon not running + ERR_INVALID_INTERFACE = -27, ///< Invalid interface + ERR_INVALID_PROTOCOL = -28, ///< Invalid protocol + ERR_INVALID_FLAGS = -29, ///< Invalid flags + + ERR_NOT_FOUND = -30, ///< Not found + ERR_INVALID_CONFIG = -31, ///< Configuration error + ERR_VERSION_MISMATCH = -32, ///< Version mismatch + ERR_INVALID_SERVICE_SUBTYPE = -33, ///< Invalid service subtype + ERR_INVALID_PACKET = -34, ///< Invalid packet + ERR_INVALID_DNS_ERROR = -35, ///< Invalid DNS return code + ERR_DNS_FORMERR = -36, ///< DNS Error: Form error + ERR_DNS_SERVFAIL = -37, ///< DNS Error: Server Failure + ERR_DNS_NXDOMAIN = -38, ///< DNS Error: No such domain + ERR_DNS_NOTIMP = -39, ///< DNS Error: Not implemented + + ERR_DNS_REFUSED = -40, ///< DNS Error: Operation refused + ERR_DNS_YXDOMAIN = -41, ///< TODO + ERR_DNS_YXRRSET = -42, ///< TODO + ERR_DNS_NXRRSET = -43, ///< TODO + ERR_DNS_NOTAUTH = -44, ///< DNS Error: Not authorized + ERR_DNS_NOTZONE = -45, ///< TODO + ERR_INVALID_RDATA = -46, ///< Invalid RDATA + ERR_INVALID_DNS_CLASS = -47, ///< Invalid DNS class + ERR_INVALID_DNS_TYPE = -48, ///< Invalid DNS type + ERR_NOT_SUPPORTED = -49, ///< Not supported + + ERR_NOT_PERMITTED = -50, ///< Operation not permitted + ERR_INVALID_ARGUMENT = -51, ///< Invalid argument + ERR_IS_EMPTY = -52, ///< Is empty + ERR_NO_CHANGE = -53, ///< The requested operation is invalid because it is redundant + + ERR_MAX = -54 ///< TODO }; constexpr auto IF_UNSPEC = -1; enum proto { - PROTO_INET = 0, /**< IPv4 */ - PROTO_INET6 = 1, /**< IPv6 */ - PROTO_UNSPEC = -1 /**< Unspecified/all protocol(s) */ + PROTO_INET = 0, ///< IPv4 + PROTO_INET6 = 1, ///< IPv6 + PROTO_UNSPEC = -1 ///< Unspecified/all protocol(s) }; enum ServerState { - SERVER_INVALID, /**< Invalid state (initial) */ - SERVER_REGISTERING, /**< Host RRs are being registered */ - 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_FAILURE /**< Some fatal failure happened, the server is unable to proceed */ + SERVER_INVALID, ///< Invalid state (initial) + SERVER_REGISTERING, ///< Host RRs are being registered + 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_FAILURE ///< Some fatal failure happened, the server is unable to proceed }; enum ClientState { - CLIENT_S_REGISTERING = SERVER_REGISTERING, /**< Server state: REGISTERING */ - CLIENT_S_RUNNING = SERVER_RUNNING, /**< Server state: RUNNING */ - CLIENT_S_COLLISION = SERVER_COLLISION, /**< Server state: COLLISION */ - 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_S_REGISTERING = SERVER_REGISTERING, ///< Server state: REGISTERING + CLIENT_S_RUNNING = SERVER_RUNNING, ///< Server state: RUNNING + CLIENT_S_COLLISION = SERVER_COLLISION, ///< Server state: COLLISION + 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. }; enum EntryGroupState { - 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_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_FAILURE /**< Some kind of failure happened, the entries have been withdrawn */ + 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_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_FAILURE ///< Some kind of failure happened, the entries have been withdrawn }; enum ClientFlags { - 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_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 }; /** * @brief Flags for publishing functions. */ enum PublishFlags { - 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_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 */ - /** \cond fulldocs */ - 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 */ - /** \endcond */ - PUBLISH_UPDATE = 64, /**< Update existing records instead of adding new ones */ - /** \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 */ + 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_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_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_UPDATE = 64, ///< Update existing records instead of adding new ones + 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 }; using IfIndex = int; diff --git a/src/platform/linux/wayland.cpp b/src/platform/linux/wayland.cpp index 8dcd22c3639..0a9e124cf77 100644 --- a/src/platform/linux/wayland.cpp +++ b/src/platform/linux/wayland.cpp @@ -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) { diff --git a/src/platform/linux/wayland.h b/src/platform/linux/wayland.h index cff16019252..c2d8d242d33 100644 --- a/src/platform/linux/wayland.h +++ b/src/platform/linux/wayland.h @@ -34,9 +34,9 @@ namespace wl { class dmabuf_t { public: enum status_e { - WAITING, - READY, - REINIT, + WAITING, ///< Waiting for a frame + READY, ///< Frame is ready + REINIT, ///< Reinitialize the frame }; dmabuf_t(dmabuf_t &&) = delete; @@ -154,9 +154,9 @@ namespace wl { public: enum interface_e { - XDG_OUTPUT, - WLR_EXPORT_DMABUF, - MAX_INTERFACES, + XDG_OUTPUT, ///< xdg-output + WLR_EXPORT_DMABUF, ///< Export dmabuf + MAX_INTERFACES, ///< Maximum number of interfaces }; interface_t(interface_t &&) = delete; diff --git a/src/platform/windows/audio.cpp b/src/platform/windows/audio.cpp index 3e9267b32aa..5dafebf4ca0 100644 --- a/src/platform/windows/audio.cpp +++ b/src/platform/windows/audio.cpp @@ -91,10 +91,10 @@ namespace platf::audio { struct format_t { enum type_e : int { - none, - stereo, - surr51, - surr71, + none, ///< No format + stereo, ///< Stereo + surr51, ///< Surround 5.1 + 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 diff --git a/src/platform/windows/display.h b/src/platform/windows/display.h index 1a3e7b5817f..6e18f57dff2 100644 --- a/src/platform/windows/display.h +++ b/src/platform/windows/display.h @@ -187,12 +187,12 @@ namespace platf::dxgi { util::safe_ptr_v2, BOOL, CloseHandle> timer; typedef enum _D3DKMT_SCHEDULINGPRIORITYCLASS { - D3DKMT_SCHEDULINGPRIORITYCLASS_IDLE, - D3DKMT_SCHEDULINGPRIORITYCLASS_BELOW_NORMAL, - D3DKMT_SCHEDULINGPRIORITYCLASS_NORMAL, - D3DKMT_SCHEDULINGPRIORITYCLASS_ABOVE_NORMAL, - D3DKMT_SCHEDULINGPRIORITYCLASS_HIGH, - D3DKMT_SCHEDULINGPRIORITYCLASS_REALTIME + D3DKMT_SCHEDULINGPRIORITYCLASS_IDLE, ///< Idle priority class + D3DKMT_SCHEDULINGPRIORITYCLASS_BELOW_NORMAL, ///< Below normal priority class + D3DKMT_SCHEDULINGPRIORITYCLASS_NORMAL, ///< Normal priority class + D3DKMT_SCHEDULINGPRIORITYCLASS_ABOVE_NORMAL, ///< Above normal priority class + D3DKMT_SCHEDULINGPRIORITYCLASS_HIGH, ///< High priority class + D3DKMT_SCHEDULINGPRIORITYCLASS_REALTIME ///< Realtime priority class } D3DKMT_SCHEDULINGPRIORITYCLASS; typedef UINT D3DKMT_HANDLE; diff --git a/src/platform/windows/display_vram.cpp b/src/platform/windows/display_vram.cpp index be144c9844f..ee17881c688 100644 --- a/src/platform/windows/display_vram.cpp +++ b/src/platform/windows/display_vram.cpp @@ -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) { diff --git a/src/platform/windows/display_wgc.cpp b/src/platform/windows/display_wgc.cpp index b77c600b8f4..a8f5f7db33f 100644 --- a/src/platform/windows/display_wgc.cpp +++ b/src/platform/windows/display_wgc.cpp @@ -66,7 +66,7 @@ namespace platf::dxgi { } /** - * Initialize the Windows.Graphics.Capture backend. + * @brief Initialize the Windows.Graphics.Capture backend. * @return 0 on success */ int diff --git a/src/platform/windows/misc.cpp b/src/platform/windows/misc.cpp index 624186715b4..8e011541254 100644 --- a/src/platform/windows/misc.cpp +++ b/src/platform/windows/misc.cpp @@ -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 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. @@ -1702,7 +1702,7 @@ namespace platf { } /** - * @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. */ @@ -1734,7 +1734,7 @@ namespace platf { } /** - * @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. */ diff --git a/src/platform/windows/misc.h b/src/platform/windows/misc.h index 5a3e29b0257..e97b3ea8931 100644 --- a/src/platform/windows/misc.h +++ b/src/platform/windows/misc.h @@ -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. */ diff --git a/src/process.cpp b/src/process.cpp index 32af14ebd9d..8ada25932d6 100644 --- a/src/process.cpp +++ b/src/process.cpp @@ -53,7 +53,7 @@ namespace proc { }; /** - * @brief Initializes proc functions + * @brief Initialize proc functions * @return Unique pointer to `deinit_t` to manage cleanup */ std::unique_ptr diff --git a/src/process.h b/src/process.h index c8754992652..42f91cabc72 100644 --- a/src/process.h +++ b/src/process.h @@ -78,7 +78,7 @@ namespace proc { execute(int app_id, std::shared_ptr launch_session); /** - * @return _app_id if a process is running, otherwise returns 0 + * @return `_app_id` if a process is running, otherwise returns `0` */ int running(); @@ -116,8 +116,8 @@ namespace proc { }; /** - * Calculate a stable id based on name and image data - * @return tuple of id calculated without index (for use if no collision) and one with + * @brief Calculate a stable id based on name and image data + * @return Tuple of id calculated without index (for use if no collision) and one with. */ std::tuple calculate_app_id(const std::string &app_name, std::string app_image_path, int index); diff --git a/src/rtsp.cpp b/src/rtsp.cpp index 044b8fbbe8c..344b280e0a4 100644 --- a/src/rtsp.cpp +++ b/src/rtsp.cpp @@ -95,7 +95,7 @@ namespace rtsp_stream { handle_data_fn { std::move(handle_data_fn) }, sock { ios } {} /** - * @brief Queues an asynchronous read to begin the next message. + * @brief Queue an asynchronous read to begin the next message. */ void read() { @@ -130,7 +130,7 @@ namespace rtsp_stream { } /** - * @brief Handles the initial read of the header of an encrypted message. + * @brief Handle the initial read of the header of an encrypted message. * @param socket The socket the message was received on. * @param ec The error code of the read operation. * @param bytes The number of bytes read. @@ -185,7 +185,7 @@ namespace rtsp_stream { } /** - * @brief Handles the final read of the content of an encrypted message. + * @brief Handle the final read of the content of an encrypted message. * @param socket The socket the message was received on. * @param ec The error code of the read operation. * @param bytes The number of bytes read. @@ -251,7 +251,7 @@ namespace rtsp_stream { } /** - * @brief Queues an asynchronous read of the payload portion of a plaintext message. + * @brief Queue an asynchronous read of the payload portion of a plaintext message. */ void read_plaintext_payload() { @@ -275,7 +275,7 @@ namespace rtsp_stream { } /** - * @brief Handles the read of the payload portion of a plaintext message. + * @brief Handle the read of the payload portion of a plaintext message. * @param socket The socket the message was received on. * @param ec The error code of the read operation. * @param bytes The number of bytes read. @@ -344,7 +344,7 @@ namespace rtsp_stream { } /** - * @brief Handles the read of the header portion of a plaintext message. + * @brief Handle the read of the header portion of a plaintext message. * @param socket The socket the message was received on. * @param ec The error code of the read operation. * @param bytes The number of bytes read. @@ -562,11 +562,9 @@ namespace rtsp_stream { /** * @brief Clear launch sessions. * @param all If true, clear all sessions. Otherwise, only clear timed out and stopped sessions. - * - * EXAMPLES: - * ```cpp + * @examples * clear(false); - * ``` + * @end_examples */ void clear(bool all = true) { diff --git a/src/stream.cpp b/src/stream.cpp index fe62f03e6ed..ec4fa014402 100644 --- a/src/stream.cpp +++ b/src/stream.cpp @@ -73,8 +73,8 @@ using namespace std::literals; namespace stream { enum class socket_e : int { - video, - audio + video, ///< Video + audio ///< Audio }; #pragma pack(push, 1) @@ -288,7 +288,7 @@ namespace stream { iterate(std::chrono::milliseconds timeout); /** - * @brief Calls the handler for a given control stream message. + * @brief Call the handler for a given control stream message. * @param type The message type. * @param session The session the message was received on. * @param payload The payload of the message. @@ -550,7 +550,7 @@ namespace stream { } /** - * @brief Calls the handler for a given control stream message. + * @brief Call the handler for a given control stream message. * @param type The message type. * @param session The session the message was received on. * @param payload The payload of the message. diff --git a/src/stream.h b/src/stream.h index 565ae4ed56e..23055f239fe 100644 --- a/src/stream.h +++ b/src/stream.h @@ -35,10 +35,10 @@ namespace stream { namespace session { enum class state_e : int { - STOPPED, - STOPPING, - STARTING, - RUNNING, + STOPPED, ///< The session is stopped + STOPPING, ///< The session is stopping + STARTING, ///< The session is starting + RUNNING, ///< The session is running }; std::shared_ptr diff --git a/src/system_tray.cpp b/src/system_tray.cpp index 06a147f2b3b..91799b2e59b 100644 --- a/src/system_tray.cpp +++ b/src/system_tray.cpp @@ -251,7 +251,7 @@ namespace system_tray { /** * @brief Run the system tray with platform specific options. - * @note macOS requires that UI elements be created on the main thread, so the system tray is not currently implemented for macOS. + * @todo macOS requires that UI elements be created on the main thread, so the system tray is not currently implemented for macOS. */ void run_tray() { diff --git a/src/task_pool.h b/src/task_pool.h index 8da85ed0ac9..2f679582c50 100644 --- a/src/task_pool.h +++ b/src/task_pool.h @@ -114,7 +114,7 @@ namespace task_pool_util { } /** - * @return an id to potentially delay the task. + * @return An id to potentially delay the task. */ template auto diff --git a/src/upnp.cpp b/src/upnp.cpp index 2743ebae649..5286384de0a 100644 --- a/src/upnp.cpp +++ b/src/upnp.cpp @@ -95,7 +95,7 @@ namespace upnp { /** * @brief Opens pinholes for IPv6 traffic if the IGD is capable. * @details Not many IGDs support this feature, so we perform error logging with debug level. - * @return true if the pinholes were opened successfully. + * @return `true` if the pinholes were opened successfully. */ bool create_ipv6_pinholes() { diff --git a/src/utility.h b/src/utility.h index 723986c24d8..e37f850b587 100644 --- a/src/utility.h +++ b/src/utility.h @@ -975,7 +975,7 @@ namespace util { #else #error "Unknown Endianness" #endif - big = !little + big = !little ///< big-endian }; }; diff --git a/src/video.cpp b/src/video.cpp index 95783dc725b..9d44d2f012e 100644 --- a/src/video.cpp +++ b/src/video.cpp @@ -53,30 +53,30 @@ namespace video { namespace nv { enum class profile_h264_e : int { - baseline, - main, - high, - high_444p, + baseline, ///< Baseline profile + main, ///< Main profile + high, ///< High profile + high_444p, ///< High 4:4:4 Predictive profile }; enum class profile_hevc_e : int { - main, - main_10, - rext, + main, ///< Main profile + main_10, ///< Main 10 profile + rext, ///< Rext profile }; } // namespace nv namespace qsv { enum class profile_h264_e : int { - baseline = 66, - main = 77, - high = 100, + baseline = 66, ///< Baseline profile + main = 77, ///< Main profile + high = 100, ///< High profile }; enum class profile_hevc_e : int { - main = 1, - main_10 = 2, + main = 1, ///< Main profile + main_10 = 2, ///< Main 10 profile }; } // namespace qsv @@ -264,16 +264,16 @@ namespace video { }; enum flag_e : uint32_t { - DEFAULT = 0, - PARALLEL_ENCODING = 1 << 1, // Capture and encoding can run concurrently on separate threads - H264_ONLY = 1 << 2, // When HEVC is too heavy - LIMITED_GOP_SIZE = 1 << 3, // Some encoders don't like it when you have an infinite GOP_SIZE. *cough* VAAPI *cough* - SINGLE_SLICE_ONLY = 1 << 4, // Never use multiple slices <-- Older intel iGPU's ruin it for everyone else :P - CBR_WITH_VBR = 1 << 5, // Use a VBR rate control mode to simulate CBR - RELAXED_COMPLIANCE = 1 << 6, // Use FF_COMPLIANCE_UNOFFICIAL compliance mode - NO_RC_BUF_LIMIT = 1 << 7, // Don't set rc_buffer_size - REF_FRAMES_INVALIDATION = 1 << 8, // Support reference frames invalidation - ALWAYS_REPROBE = 1 << 9, // This is an encoder of last resort and we want to aggressively probe for a better one + DEFAULT = 0, ///< Default flags + PARALLEL_ENCODING = 1 << 1, ///< Capture and encoding can run concurrently on separate threads + H264_ONLY = 1 << 2, ///< When HEVC is too heavy + LIMITED_GOP_SIZE = 1 << 3, ///< Some encoders don't like it when you have an infinite GOP_SIZE. e.g. VAAPI + SINGLE_SLICE_ONLY = 1 << 4, ///< Never use multiple slices. Older intel iGPU's ruin it for everyone else + CBR_WITH_VBR = 1 << 5, ///< Use a VBR rate control mode to simulate CBR + RELAXED_COMPLIANCE = 1 << 6, ///< Use FF_COMPLIANCE_UNOFFICIAL compliance mode + NO_RC_BUF_LIMIT = 1 << 7, ///< Don't set rc_buffer_size + REF_FRAMES_INVALIDATION = 1 << 8, ///< Support reference frames invalidation + ALWAYS_REPROBE = 1 << 9, ///< This is an encoder of last resort and we want to aggressively probe for a better one }; class avcodec_encode_session_t: public encode_session_t { @@ -957,7 +957,7 @@ namespace video { } /** - * @brief Updates the list of display names before or during a stream. + * @brief Update the list of display names before or during a stream. * @details This will attempt to keep `current_display_index` pointing at the same display. * @param dev_type The encoder device type used for display lookup. * @param display_names The list of display names to repopulate. @@ -2225,7 +2225,7 @@ namespace video { } enum validate_flag_e { - VUI_PARAMS = 0x01, + VUI_PARAMS = 0x01, ///< VUI parameters }; int diff --git a/src/video.h b/src/video.h index ba80474669f..bdc1c360f35 100644 --- a/src/video.h +++ b/src/video.h @@ -83,12 +83,12 @@ namespace video { struct encoder_t { std::string_view name; enum flag_e { - PASSED, // Is supported - REF_FRAMES_RESTRICT, // Set maximum reference frames - CBR, // Some encoders don't support CBR, if not supported --> attempt constant quantatication parameter instead - DYNAMIC_RANGE, // hdr - VUI_PARAMETERS, // AMD encoder with VAAPI doesn't add VUI parameters to SPS - MAX_FLAGS + PASSED, ///< Indicates the encoder is supported. + REF_FRAMES_RESTRICT, ///< Set maximum reference frames. + CBR, ///< Some encoders don't support CBR, if not supported attempt constant quantization parameter instead. + DYNAMIC_RANGE, ///< HDR support. + VUI_PARAMETERS, ///< AMD encoder with VAAPI doesn't add VUI parameters to SPS. + MAX_FLAGS ///< Maximum number of flags. }; static std::string_view