docs(src): fix some doxygen warnings (#2731)

docs/Doxyfile

@@ -860,7 +860,8 @@ WARNINGS               = YES
 # will automatically be disabled.
 # The default value is: YES.
 
-WARN_IF_UNDOCUMENTED   = YES
+# TODO: Enable this when we have complete documentation
+WARN_IF_UNDOCUMENTED = NO
 
 # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
 # potential errors in the documentation, such as documenting some parameters in

src/file_handler.cpp

@@ -13,7 +13,7 @@
 
 namespace file_handler {
   /**
-   * @breif Get the parent directory of a file or directory.
+   * @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.
    */

src/platform/common.h

@@ -569,13 +569,12 @@ namespace platf {
   audio_control();
 
   /**
-   * display_name --> The name of the monitor that SHOULD be displayed
+   * @brief Get the display_t instance for the given hwdevice_type.
-   *    If display_name is empty --> Use the first monitor that's compatible you can find
+   * @param display_name The name of the monitor that SHOULD be displayed
-   *    If you require to use this parameter in a separate thread --> make a copy of it.
+   * 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.
-   * config --> Stream configuration
+   * @param config Stream configuration
-   *
+   * @returns display_t based on hwdevice_type
-   * Returns display_t based on hwdevice_type
    */
   std::shared_ptr<display_t>
   display(mem_type_e hwdevice_type, const std::string &display_name, const video::config_t &config);

src/platform/linux/cuda.cpp

@@ -498,8 +498,8 @@ namespace cuda {
 
   /**
    * @brief Create a GL->CUDA encoding device for consuming captured dmabufs.
-   * @param in_width Width of captured frames.
+   * @param width Width of captured frames.
-   * @param in_height Height of captured frames.
+   * @param height Height of captured frames.
    * @param offset_x Offset of content in captured frame.
    * @param offset_y Offset of content in captured frame.
    * @return FFmpeg encoding device context.

src/platform/linux/input/legacy_input.cpp

@@ -778,13 +778,6 @@ namespace platf {
       return 0;
     }
 
-    /**
-     * @brief Creates a new virtual gamepad.
-     * @param id The gamepad ID.
-     * @param metadata Controller metadata from client (empty if none provided).
-     * @param feedback_queue The queue for posting messages back to the client.
-     * @return 0 on success.
-     */
     int
     alloc_gamepad(const gamepad_id_t &id, const gamepad_arrival_t &metadata, feedback_queue_t &&feedback_queue) {
       TUPLE_2D_REF(input, gamepad_state, gamepads[id.globalIndex]);
@@ -1599,14 +1592,6 @@ namespace platf {
     keyboard_ev(kb, KEY_LEFTCTRL, 0);
   }
 
-  /**
-   * @brief Creates 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).
-   * @param feedback_queue The queue for posting messages back to the client.
-   * @return 0 on success.
-   */
   int
   alloc_gamepad(input_t &input, const gamepad_id_t &id, const gamepad_arrival_t &metadata, feedback_queue_t feedback_queue) {
     return ((input_raw_t *) input.get())->alloc_gamepad(id, metadata, std::move(feedback_queue));

src/platform/linux/misc.cpp

@@ -326,11 +326,6 @@ namespace platf {
     lifetime::exit_sunshine(0, true);
   }
 
-  /**
-   * @brief Attempt to gracefully terminate a process group.
-   * @param native_handle The process group ID.
-   * @return true if termination was successfully requested.
-   */
   bool
   request_process_group_exit(std::uintptr_t native_handle) {
     if (kill(-((pid_t) native_handle), SIGTERM) == 0 || errno == ESRCH) {
@@ -343,11 +338,6 @@ namespace platf {
     }
   }
 
-  /**
-   * @brief Checks if a process group still has running children.
-   * @param native_handle The process group ID.
-   * @return true if processes are still running.
-   */
   bool
   process_group_running(std::uintptr_t native_handle) {
     return waitpid(-((pid_t) native_handle), nullptr, WNOHANG) >= 0;

src/platform/linux/wayland.h

@@ -196,8 +196,10 @@ namespace wl {
   class display_t {
   public:
     /**
-     * Initialize display with display_name
+     * @brief Initialize display.
      * If display_name == nullptr -> display_name = std::getenv("WAYLAND_DISPLAY")
+     * @param display_name The name of the display.
+     * @return 0 on success, -1 on failure.
      */
     int
     init(const char *display_name = nullptr);

src/platform/macos/input.cpp

@@ -297,14 +297,6 @@ const KeyCodeMap kKeyCodesMap[] = {
     BOOST_LOG(info) << "unicode: Unicode input not yet implemented for MacOS."sv;
   }
 
-  /**
-   * @brief Creates a new virtual gamepad.
-   * @param input The input context.
-   * @param id The gamepad ID.
-   * @param metadata Controller metadata from client (empty if none provided).
-   * @param feedback_queue The queue for posting messages back to the client.
-   * @return 0 on success.
-   */
   int
   alloc_gamepad(input_t &input, const gamepad_id_t &id, const gamepad_arrival_t &metadata, feedback_queue_t feedback_queue) {
     BOOST_LOG(info) << "alloc_gamepad: Gamepad not yet implemented for MacOS."sv;

src/platform/macos/misc.mm

@@ -253,11 +253,6 @@ namespace platf {
     lifetime::exit_sunshine(0, true);
   }
 
-  /**
-   * @brief Attempt to gracefully terminate a process group.
-   * @param native_handle The process group ID.
-   * @return true if termination was successfully requested.
-   */
   bool
   request_process_group_exit(std::uintptr_t native_handle) {
     if (killpg((pid_t) native_handle, SIGTERM) == 0 || errno == ESRCH) {
@@ -270,11 +265,6 @@ namespace platf {
     }
   }
 
-  /**
-   * @brief Checks if a process group still has running children.
-   * @param native_handle The process group ID.
-   * @return true if processes are still running.
-   */
   bool
   process_group_running(std::uintptr_t native_handle) {
     return waitpid(-((pid_t) native_handle), nullptr, WNOHANG) >= 0;

src/platform/windows/input.cpp

@@ -1197,14 +1197,6 @@ namespace platf {
     }
   }
 
-  /**
-   * @brief Creates 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).
-   * @param feedback_queue The queue for posting messages back to the client.
-   * @return 0 on success.
-   */
   int
   alloc_gamepad(input_t &input, const gamepad_id_t &id, const gamepad_arrival_t &metadata, feedback_queue_t feedback_queue) {
     auto raw = (input_raw_t *) input.get();

src/platform/windows/misc.cpp

@@ -1299,11 +1299,6 @@ namespace platf {
     return TRUE;
   }
 
-  /**
-   * @brief Attempt to gracefully terminate a process group.
-   * @param native_handle The job object handle.
-   * @return true if termination was successfully requested.
-   */
   bool
   request_process_group_exit(std::uintptr_t native_handle) {
     auto job_handle = (HANDLE) native_handle;
@@ -1348,11 +1343,6 @@ namespace platf {
     return enum_ctx.requested_exit;
   }
 
-  /**
-   * @brief Checks if a process group still has running children.
-   * @param native_handle The job object handle.
-   * @return true if processes are still running.
-   */
   bool
   process_group_running(std::uintptr_t native_handle) {
     JOBOBJECT_BASIC_ACCOUNTING_INFORMATION accounting_info;

src/upnp.cpp

@@ -280,8 +280,8 @@ namespace upnp {
 
     /**
      * @brief Unmaps all ports.
+     * @param urls urls_t from UPNP_GetValidIGD()
      * @param data IGDdatas from UPNP_GetValidIGD()
-     * @param data urls_t from UPNP_GetValidIGD()
      */
     void
     unmap_all_upnp_ports(const urls_t &urls, const IGDdatas &data) {