docs(src): add examples alias and general cleanup

docs/Doxyfile

@@ -27,6 +27,8 @@ DOXYFILE_ENCODING = UTF-8
 # https://breathe.readthedocs.io/en/latest/markups.html#aliases
 ALIASES = "rst=^^\verbatim embed:rst:leading-asterisk^^"
 ALIASES += "endrst=\endverbatim"
+ALIASES += "examples=**Examples**\n@code{.cpp}"
+ALIASES += "end_examples=@endcode"
 
 DISABLE_INDEX = NO
 DOCBOOK_OUTPUT = doxydocbook

docs/source/source_code/source_code.rst

@@ -1,56 +1,28 @@
 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
-   }
-
-**file.cpp** (with ReStructuredText)
-
-.. code-block:: cpp
+    /**
+     * @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[]);
 
-   /**
-    * @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
-   }
+.. 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.
 
 Source
 ------

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,111 +27,45 @@ 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;
   platf::open_url(url);
 }
 
 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]);
 
     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,20 +104,13 @@ namespace lifetime {
 #endif
   }
 
-  /**
-   * @brief Gets the argv array passed to main().
-   */
   char **
   get_argv() {
     return 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() {
   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...";