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

src/platform/windows/audio.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/windows/audio.cpp
- * @brief todo
+ * @brief Definitions for Windows audio capture.
  */
 #define INITGUID
 #include <audioclient.h>
@@ -91,10 +91,10 @@ namespace platf::audio {
 
   struct format_t {
     enum type_e : int {
-      none,
-      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<format_t::type_e, std::string_view>

src/platform/windows/display.h

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/windows/display.h
- * @brief todo
+ * @brief Declarations for the Windows display backend.
  */
 #pragma once
 
@@ -187,12 +187,12 @@ namespace platf::dxgi {
     util::safe_ptr_v2<std::remove_pointer_t<HANDLE>, BOOL, CloseHandle> timer;
 
     typedef enum _D3DKMT_SCHEDULINGPRIORITYCLASS {
-      D3DKMT_SCHEDULINGPRIORITYCLASS_IDLE,
-      D3DKMT_SCHEDULINGPRIORITYCLASS_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;

src/platform/windows/display_base.cpp

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

src/platform/windows/display_ram.cpp

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

src/platform/windows/display_vram.cpp

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

src/platform/windows/display_wgc.cpp

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

src/platform/windows/input.cpp

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

src/platform/windows/misc.cpp

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

src/platform/windows/misc.h

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

src/platform/windows/nvprefs/driver_settings.cpp

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

src/platform/windows/nvprefs/driver_settings.h

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

src/platform/windows/nvprefs/nvapi_opensource_wrapper.cpp

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

src/platform/windows/nvprefs/nvprefs_common.cpp

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

src/platform/windows/nvprefs/nvprefs_common.h

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

src/platform/windows/nvprefs/nvprefs_interface.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/nvprefs/nvprefs_interface.cpp
+ * @brief Definitions for nvidia preferences interface.
+ */
 // standard includes
 #include <cassert>
 

src/platform/windows/nvprefs/nvprefs_interface.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/nvprefs/nvprefs_interface.h
+ * @brief Declarations for nvidia preferences interface.
+ */
 #pragma once
 
 // standard library headers

src/platform/windows/nvprefs/undo_data.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/nvprefs/undo_data.cpp
+ * @brief Definitions for undoing changes to nvidia preferences.
+ */
 // external includes
 #include <nlohmann/json.hpp>
 

src/platform/windows/nvprefs/undo_data.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/nvprefs/undo_data.h
+ * @brief Declarations for undoing changes to nvidia preferences.
+ */
 #pragma once
 
 // standard library headers

src/platform/windows/nvprefs/undo_file.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/nvprefs/undo_file.cpp
+ * @brief Definitions for the nvidia undo file.
+ */
 // local includes
 #include "undo_file.h"
 

src/platform/windows/nvprefs/undo_file.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/nvprefs/undo_file.h
+ * @brief Declarations for the nvidia undo file.
+ */
 #pragma once
 
 // standard library headers

src/platform/windows/publish.cpp

@@ -1,6 +1,6 @@
 /**
  * @file src/platform/windows/publish.cpp
- * @brief todo
+ * @brief Definitions for Windows mDNS service registration.
  */
 #include <winsock2.h>
 

src/platform/windows/windows.rs.in

@@ -1,3 +1,9 @@
+/**
+ * @file src/platform/windows/windows.rs.in
+ * @brief Windows resource file template.
+ * @note The final `windows.rs` is generated from this file during the CMake build.
+ * @todo Use CMake definitions directly, instead of configuring this file.
+ */
 #include "winver.h"
 VS_VERSION_INFO VERSIONINFO
 FILEVERSION     @PROJECT_VERSION_MAJOR@,@PROJECT_VERSION_MINOR@,@PROJECT_VERSION_PATCH@,0