docs: update file level doxygen blocks (#1258)

src/platform/common.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/common.h
+ * @brief todo
+ */
 #pragma once
 
 #include <bitset>

src/platform/linux/audio.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/audio.cpp
+ * @brief todo
+ */
 #include <bitset>
 #include <sstream>
 

src/platform/linux/cuda.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/cuda.cpp
+ * @brief todo
+ */
 #include <bitset>
 
 #include <NvFBC.h>

src/platform/linux/cuda.cu

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/cuda.cu
+ * @brief todo
+ */
 // #include <algorithm>
 #include <helper_math.h>
 #include <chrono>

src/platform/linux/cuda.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/cuda.h
+ * @brief todo
+ */
 #pragma once
 
 #if defined(SUNSHINE_BUILD_CUDA)

src/platform/linux/graphics.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/graphics.cpp
+ * @brief todo
+ */
 #include "graphics.h"
 #include "src/video.h"
 

src/platform/linux/graphics.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/graphics.h
+ * @brief todo
+ */
 #pragma once
 
 #include <optional>

src/platform/linux/input.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/input.cpp
+ * @brief todo
+ */
 #include <fcntl.h>
 #include <linux/uinput.h>
 #include <poll.h>
@@ -1108,7 +1112,7 @@ namespace platf {
    *
    * EXAMPLES:
    * ```cpp
-   * x_move_mouse(input, 10, 10); // Move mouse 10 pixels down and right
+   * x_move_mouse(input, 10, 10);  // Move mouse 10 pixels down and right
    * ```
    */
   static void
@@ -1204,7 +1208,7 @@ namespace platf {
    *
    * EXAMPLES:
    * ```cpp
-   * button_mouse(input, 1, false); // Press left mouse button
+   * button_mouse(input, 1, false);  // Press left mouse button
    * ```
    */
   void
@@ -1336,12 +1340,12 @@ namespace platf {
    * @brief XTest keyboard emulation.
    * @param input The input_t instance to use.
    * @param modcode The moonlight key code.
-   * @param release Whether the event was a press (false) or a release (true)
-   * @param flags SS_KBE_FLAG_* values
+   * @param release Whether the event was a press (false) or a release (true).
+   * @param flags SS_KBE_FLAG_* values.
    *
    * EXAMPLES:
    * ```cpp
-   * x_keyboard(input, 0x5A, false, 0); // Press Z
+   * x_keyboard(input, 0x5A, false, 0);  // Press Z
    * ```
    */
   static void
@@ -1371,12 +1375,12 @@ namespace platf {
    * @brief Keyboard emulation.
    * @param input The input_t instance to use.
    * @param modcode The moonlight key code.
-   * @param release Whether the event was a press (false) or a release (true)
-   * @param flags SS_KBE_FLAG_* values
+   * @param release Whether the event was a press (false) or a release (true).
+   * @param flags SS_KBE_FLAG_* values.
    *
    * EXAMPLES:
    * ```cpp
-   * keyboard(input, 0x5A, false, 0); // Press Z
+   * keyboard(input, 0x5A, false, 0);  // Press Z
    * ```
    */
   void

src/platform/linux/kmsgrab.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/kmsgrab.cpp
+ * @brief todo
+ */
 #include <drm_fourcc.h>
 #include <errno.h>
 #include <fcntl.h>

src/platform/linux/misc.cpp

@@ -1,7 +1,7 @@
 /**
- * @file misc.cpp
+ * @file src/misc.cpp
+ * @brief todo
  */
-
 // standard includes
 #include <fstream>
 

src/platform/linux/misc.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/misc.h
+ * @brief todo
+ */
 #pragma once
 
 #include <unistd.h>

src/platform/linux/publish.cpp

@@ -1,5 +1,9 @@
-
-// adapted from https://www.avahi.org/doxygen/html/client-publish-service_8c-example.html
+/**
+ * @file src/platform/linux/publish.cpp
+ * @brief todo
+ * @note Adapted from https://www.avahi.org/doxygen/html/client-publish-service_8c-example.html
+ * @todo Use a common file for this and src/platform/macos/publish.cpp
+ */
 #include <thread>
 
 #include "misc.h"
@@ -13,7 +17,7 @@ using namespace std::literals;
 namespace avahi {
 
   /**
-   * @brief Error codes used by avahi
+   * @brief Error codes used by avahi.
    */
   enum err_e {
     OK = 0, /**< OK */
@@ -116,7 +120,7 @@ namespace avahi {
   };
 
   /**
-   * @brief Some flags for publishing functions
+   * @brief Flags for publishing functions.
    */
   enum PublishFlags {
     PUBLISH_UNIQUE = 1, /**< For raw records: The RRset is intended to be unique */

src/platform/linux/vaapi.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/vaapi.cpp
+ * @brief todo
+ */
 #include <sstream>
 #include <string>
 
@@ -82,7 +86,7 @@ namespace va {
   };
 
   /**
-   * @brief Currently defined profiles
+   * @brief Defined profiles
    */
   enum class profile_e {
     // Profile ID used for video processing.

src/platform/linux/vaapi.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/vaapi.h
+ * @brief todo
+ */
 #pragma once
 
 #include "misc.h"

src/platform/linux/wayland.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/wayland.cpp
+ * @brief todo
+ */
 #include <wayland-client.h>
 #include <wayland-util.h>
 

src/platform/linux/wayland.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/wayland.h
+ * @brief todo
+ */
 #pragma once
 
 #include <bitset>

src/platform/linux/wlgrab.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/wlgrab.cpp
+ * @brief todo
+ */
 #include "src/platform/common.h"
 
 #include "src/main.h"

src/platform/linux/x11grab.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/x11grab.cpp
+ * @brief todo
+ */
 #include "src/platform/common.h"
 
 #include <fstream>

src/platform/linux/x11grab.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/linux/x11grab.h
+ * @brief todo
+ */
 #pragma once
 
 #include <optional>

src/platform/macos/av_audio.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/macos/av_audio.h
+ * @brief todo
+ */
 #pragma once
 
 #import <AVFoundation/AVFoundation.h>

src/platform/macos/av_audio.m

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/macos/av_audio.m
+ * @brief todo
+ */
 #import "av_audio.h"
 
 @implementation AVAudio

src/platform/macos/av_img_t.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/macos/av_img_t.h
+ * @brief todo
+ */
 #pragma once
 
 #include "src/platform/common.h"

src/platform/macos/av_video.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/macos/av_video.h
+ * @brief todo
+ */
 #pragma once
 
 #import <AVFoundation/AVFoundation.h>

src/platform/macos/av_video.m

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/macos/av_video.m
+ * @brief todo
+ */
 #import "av_video.h"
 
 @implementation AVVideo

src/platform/macos/display.mm

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/macos/display.mm
+ * @brief todo
+ */
 #include "src/platform/common.h"
 #include "src/platform/macos/av_img_t.h"
 #include "src/platform/macos/av_video.h"

src/platform/macos/input.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/macos/input.cpp
+ * @brief todo
+ */
 #import <Carbon/Carbon.h>
 #include <mach/mach.h>
 #include <mach/mach_time.h>

src/platform/macos/microphone.mm

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/macos/microphone.mm
+ * @brief todo
+ */
 #include "src/platform/common.h"
 #include "src/platform/macos/av_audio.h"
 

src/platform/macos/misc.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/macos/misc.h
+ * @brief todo
+ */
 #pragma once
 
 #include <vector>

src/platform/macos/misc.mm

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/macos/misc.mm
+ * @brief todo
+ */
 #include <Foundation/Foundation.h>
 #include <arpa/inet.h>
 #include <dlfcn.h>

src/platform/macos/nv12_zero_device.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/macos/nv12_zero_device.cpp
+ * @brief todo
+ */
 #include "src/platform/macos/nv12_zero_device.h"
 #include "src/platform/macos/av_img_t.h"
 

src/platform/macos/nv12_zero_device.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/macos/nv12_zero_device.h
+ * @brief todo
+ */
 #pragma once
 
 #include "src/platform/common.h"

src/platform/macos/publish.cpp

@@ -1,5 +1,9 @@
-
-// adapted from https://www.avahi.org/doxygen/html/client-publish-service_8c-example.html
+/**
+ * @file src/platform/macos/publish.cpp
+ * @brief todo
+ * @note Adapted from https://www.avahi.org/doxygen/html/client-publish-service_8c-example.html
+ * @todo Use a common file for this and src/platform/linux/publish.cpp
+ */
 #include <thread>
 
 #include "misc.h"
@@ -13,7 +17,7 @@ using namespace std::literals;
 namespace avahi {
 
   /**
-   * @brief Error codes used by avahi
+   * @brief Error codes used by avahi.
    */
   enum err_e {
     OK = 0, /**< OK */
@@ -116,7 +120,7 @@ namespace avahi {
   };
 
   /**
-   * @brief Some flags for publishing functions
+   * @brief Flags for publishing functions.
    */
   enum PublishFlags {
     PUBLISH_UNIQUE = 1, /**< For raw records: The RRset is intended to be unique */

src/platform/windows/PolicyConfig.h

@@ -1,10 +1,10 @@
-// ----------------------------------------------------------------------------
-// PolicyConfig.h
-// Undocumented COM-interface IPolicyConfig.
-// Use for set default audio render endpoint
-// @author EreTIk
-// http://eretik.omegahg.com/
-// ----------------------------------------------------------------------------
+/**
+ * @file src/platform/windows/PolicyConfig.h
+ * @brief Undocumented COM-interface IPolicyConfig.
+ * @details Use for setting default audio render endpoint.
+ * @author EreTIk
+ * @see http://eretik.omegahg.com/
+ */
 
 #pragma once
 

src/platform/windows/audio.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/audio.cpp
+ * @brief todo
+ */
 #include <audioclient.h>
 #include <mmdeviceapi.h>
 #include <roapi.h>
@@ -678,11 +682,9 @@ namespace platf::audio {
     }
 
     /**
-     * @brief Find the audio device ID given a user-specified name
-     *
-     * @param name The name provided by the user
-     *
-     * @return The matching device ID, or nothing if not found
+     * @brief Find the audio device ID given a user-specified name.
+     * @param name The name provided by the user.
+     * @return The matching device ID, or nothing if not found.
      */
     std::optional<std::wstring>
     find_device_id_by_name(const std::string &name) {

src/platform/windows/display.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/display.h
+ * @brief todo
+ */
 #pragma once
 
 #include <d3d11.h>

src/platform/windows/display_base.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/display_base.cpp
+ * @brief todo
+ */
 #include <cmath>
 #include <codecvt>
 #include <initguid.h>

src/platform/windows/display_ram.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/display_ram.cpp
+ * @brief todo
+ */
 #include "display.h"
 
 #include "misc.h"

src/platform/windows/display_vram.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/display_vram.cpp
+ * @brief todo
+ */
 #include <cmath>
 
 #include <codecvt>

src/platform/windows/input.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/input.cpp
+ * @brief todo
+ */
 #include <windows.h>
 
 #include <cmath>

src/platform/windows/misc.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/misc.cpp
+ * @brief todo
+ */
 #include <csignal>
 #include <filesystem>
 #include <iomanip>
@@ -229,9 +233,8 @@ namespace platf {
   }
 
   /**
-   * @brief A function to obtain the current sessions user's primary token with elevated privileges
-   *
-   * @return The users token, if user has admin capability it will be elevated. If not, it will return back a limited token. On error, nullptrs
+   * @brief Obtain the current sessions user's primary token with elevated privileges.
+   * @return The user's token. If user has admin capability it will be elevated, otherwise it will be a limited token. On error, `nullptr`.
    */
   HANDLE
   retrieve_users_token(bool elevated) {
@@ -333,10 +336,9 @@ namespace platf {
   }
 
   /**
-
-@brief Check if the current process is running with system-level privileges.
-@return true if the current process has system-level privileges, false otherwise.
-*/
+   * @brief Check if the current process is running with system-level privileges.
+   * @return `true` if the current process has system-level privileges, `false` otherwise.
+   */
   bool
   is_running_as_system() {
     BOOL ret;
@@ -430,14 +432,13 @@ namespace platf {
   }
 
   /**
-   * @brief Creates a bp::child object from the results of launching a process
-   *
-   * @param process_launched A boolean indicating whether the launch was successful or not
-   * @param cmd The command that was used to launch the process
-   * @param ec A reference to an std::error_code object that will store any error that occurred during the launch
-   * @param process_info A reference to a PROCESS_INFORMATION structure that contains information about the new process
-   * @param group A pointer to a bp::group object that will add the new process to its group, if not null
-   * @return A bp::child object representing the new process, or an empty bp::child object if the launch failed or an error occurred
+   * @brief Create a `bp::child` object from the results of launching a process.
+   * @param process_launched A boolean indicating if the launch was successful.
+   * @param cmd The command that was used to launch the process.
+   * @param ec A reference to an `std::error_code` object that will store any error that occurred during the launch.
+   * @param process_info A reference to a `PROCESS_INFORMATION` structure that contains information about the new process.
+   * @param group A pointer to a `bp::group` object that will add the new process to its group, if not null.
+   * @return A `bp::child` object representing the new process, or an empty `bp::child` object if the launch failed.
    */
   bp::child
   create_boost_child_from_results(bool process_launched, const std::string &cmd, std::error_code &ec, PROCESS_INFORMATION &process_info, bp::group *group) {
@@ -477,11 +478,10 @@ namespace platf {
   }
 
   /**
-   * @brief Impersonate the current user, invoke the callback function, then returns back to system context.
-   *
-   * @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
+   * @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
    */
   std::error_code
   impersonate_current_user(HANDLE user_token, std::function<void()> callback) {
@@ -515,11 +515,10 @@ namespace platf {
   }
 
   /**
-   * @brief A function to 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 ec A reference to an 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
+   * @brief A function to 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 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.
    */
   STARTUPINFOEXW
   create_startup_info(FILE *file, std::error_code &ec) {
@@ -563,22 +562,19 @@ namespace platf {
   }
 
   /**
-   * @brief Runs a command on the users profile
+   * @brief Run a command on the users profile.
    *
-   * This function launches a child process as the user, using the current user's environment
-   * and a specific working directory. If the launch is successful, a `bp::child` object representing the new
-   * process is returned. Otherwise, an error code is returned.
+   * Launches a child process as the user, using the current user's environment and a specific working directory.
    *
-   * @param elevated Specify to elevate the process or not
-   * @param interactive Specifies whether this will run in a window or hidden
-   * @param cmd The command to run
-   * @param working_dir The working directory for the new process
-   * @param env The environment variables to use for the new process
-   * @param file A file object to redirect the child process's output to (may be nullptr)
-   * @param ec An error code, set to indicate any errors that occur during the launch process
-   * @param group A pointer to a `bp::group` object to which the new process should belong (may be nullptr)
-   *
-   * @return A `bp::child` object representing the new process, or an empty `bp::child` object if the launch fails
+   * @param elevated Specify whether to elevate the process.
+   * @param interactive Specify whether this will run in a window or hidden.
+   * @param cmd The command to run.
+   * @param working_dir The working directory for the new process.
+   * @param env The environment variables to use for the new process.
+   * @param file A file object to redirect the child process's output to (may be `nullptr`).
+   * @param ec An error code, set to indicate any errors that occur during the launch process.
+   * @param group A pointer to a `bp::group` object to which the new process should belong (may be `nullptr`).
+   * @return A `bp::child` object representing the new process, or an empty `bp::child` object if the launch fails.
    */
   bp::child
   run_command(bool elevated, bool interactive, const std::string &cmd, boost::filesystem::path &working_dir, bp::environment &env, FILE *file, std::error_code &ec, bp::group *group) {

src/platform/windows/misc.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/misc.h
+ * @brief todo
+ */
 #pragma once
 
 #include <chrono>

src/platform/windows/publish.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/platform/windows/publish.cpp
+ * @brief todo
+ */
 #include <winsock2.h>
 
 #include <windows.h>