docs(src): apply new patterns from LizardByte#2763

src/input/common.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/input/common.cpp
+ * @brief Definitions for common input.
+ */
 #include "common.h"
 #include "init.h"
 
@@ -10,35 +14,16 @@ using namespace std::literals;
 
 namespace input {
 
-  /**
-   * @brief Converts a little-endian netfloat to a native endianness float.
-   * @param f Netfloat value.
-   * @return Float value.
-   */
   float
   from_netfloat(netfloat f) {
     return boost::endian::endian_load<float, sizeof(float), boost::endian::order::little>(f);
   }
 
-  /**
-   * @brief Converts 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.
-   */
   float
   from_clamped_netfloat(netfloat f, float min, float max) {
     return std::clamp(from_netfloat(f), min, max);
   }
 
-  /**
-   * @brief Multiplies 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.
-   * @return The scaled radial coordinate.
-   */
   float
   multiply_polar_by_cartesian_scalar(float r, float angle, const std::pair<float, float> &scalar) {
     // Convert polar to cartesian coordinates
@@ -53,17 +38,10 @@ namespace input {
     return std::sqrt(std::pow(x, 2) + std::pow(y, 2));
   }
 
-  /**
-   * @brief Scales 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.
-   * @return The major and minor axis pair.
-   */
   std::pair<float, float>
   scale_client_contact_area(const std::pair<float, float> &val, uint16_t rotation, const std::pair<float, float> &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

src/input/common.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/input/common.h
+ * @brief Declarations for common input.
+ */
 #pragma once
 
 #include <cstdint>
@@ -38,25 +42,25 @@ 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);
 
   /**
-   * @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);
 
   /**
-   * @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.
@@ -66,7 +70,7 @@ namespace input {
   multiply_polar_by_cartesian_scalar(float r, float angle, const std::pair<float, float> &scalar);
 
   /**
-   * @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.

src/input/gamepad.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/input/gamepad.cpp
+ * @brief Definitions for common gamepad input.
+ */
 #include "gamepad.h"
 #include "common.h"
 #include "init.h"
@@ -55,10 +59,6 @@ namespace input::gamepad {
       << "--end controller packet--"sv;
   }
 
-  /**
-   * @brief Prints a controller arrival packet.
-   * @param packet The controller arrival packet.
-   */
   void
   print(PSS_CONTROLLER_ARRIVAL_PACKET packet) {
     BOOST_LOG(debug)
@@ -70,10 +70,6 @@ namespace input::gamepad {
       << "--end controller arrival packet--"sv;
   }
 
-  /**
-   * @brief Prints a controller touch packet.
-   * @param packet The controller touch packet.
-   */
   void
   print(PSS_CONTROLLER_TOUCH_PACKET packet) {
     BOOST_LOG(debug)
@@ -87,10 +83,6 @@ namespace input::gamepad {
       << "--end controller touch packet--"sv;
   }
 
-  /**
-   * @brief Prints a controller motion packet.
-   * @param packet The controller motion packet.
-   */
   void
   print(PSS_CONTROLLER_MOTION_PACKET packet) {
     BOOST_LOG(verbose)
@@ -103,10 +95,6 @@ namespace input::gamepad {
       << "--end controller motion packet--"sv;
   }
 
-  /**
-   * @brief Prints a controller battery packet.
-   * @param packet The controller battery packet.
-   */
   void
   print(PSS_CONTROLLER_BATTERY_PACKET packet) {
     BOOST_LOG(verbose)
@@ -117,11 +105,6 @@ namespace input::gamepad {
       << "--end controller battery packet--"sv;
   }
 
-  /**
-   * @brief Called to pass a controller arrival message to the platform backend.
-   * @param input The input context pointer.
-   * @param packet The controller arrival packet.
-   */
   void
   passthrough(std::shared_ptr<input_t> &input, PSS_CONTROLLER_ARRIVAL_PACKET packet) {
     if (!config::input.controller) {
@@ -158,11 +141,6 @@ namespace input::gamepad {
     (*input->gamepads)[packet->controllerNumber].id = id;
   }
 
-  /**
-   * @brief Called to pass a controller touch message to the platform backend.
-   * @param input The input context pointer.
-   * @param packet The controller touch packet.
-   */
   void
   passthrough(std::shared_ptr<input_t> &input, PSS_CONTROLLER_TOUCH_PACKET packet) {
     if (!config::input.controller) {
@@ -192,11 +170,6 @@ namespace input::gamepad {
     platf::gamepad_touch(PlatformInput::getInstance(), touch);
   }
 
-  /**
-   * @brief Called to pass a controller motion message to the platform backend.
-   * @param input The input context pointer.
-   * @param packet The controller motion packet.
-   */
   void
   passthrough(std::shared_ptr<input_t> &input, PSS_CONTROLLER_MOTION_PACKET packet) {
     if (!config::input.controller) {
@@ -343,11 +316,6 @@ namespace input::gamepad {
     gamepad.gamepad_state = gamepad_state;
   }
 
-  /**
-   * @brief Called to pass a controller battery message to the platform backend.
-   * @param input The input context pointer.
-   * @param packet The controller battery packet.
-   */
   void
   passthrough(std::shared_ptr<input_t> &input, PSS_CONTROLLER_BATTERY_PACKET packet) {
     if (!config::input.controller) {
@@ -374,12 +342,6 @@ namespace input::gamepad {
     platf::gamepad_battery(PlatformInput::getInstance(), battery);
   }
 
-  /**
-   * @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.
-   */
   batch_result_e
   batch(PSS_CONTROLLER_TOUCH_PACKET dest, PSS_CONTROLLER_TOUCH_PACKET src) {
     // Only batch hover or move events
@@ -415,12 +377,6 @@ namespace input::gamepad {
     return batch_result_e::batched;
   }
 
-  /**
-   * @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.
-   */
   batch_result_e
   batch(PNV_MULTI_CONTROLLER_PACKET dest, PNV_MULTI_CONTROLLER_PACKET src) {
     // Do not allow batching if the active controllers change
@@ -444,12 +400,6 @@ namespace input::gamepad {
     return batch_result_e::batched;
   }
 
-  /**
-   * @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.
-   */
   batch_result_e
   batch(PSS_CONTROLLER_MOTION_PACKET dest, PSS_CONTROLLER_MOTION_PACKET src) {
     // We can only batch entries for the same controller, but allow batching attempts to continue

src/input/gamepad.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/input/gamepad.h
+ * @brief Declarations for common gamepad input.
+ */
 #pragma once
 
 #include "platform_input.h"
@@ -133,7 +137,7 @@ namespace input::gamepad {
    * @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);
@@ -142,7 +146,7 @@ namespace input::gamepad {
    * @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);
@@ -151,7 +155,7 @@ namespace input::gamepad {
    * @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);

src/input/init.h

@@ -1,11 +1,15 @@
+/**
+ * @file src/input/init.h
+ * @brief Declarations for common input initialization.
+ */
 #pragma once
 
 namespace input {
   struct input_t;
 
   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,  ///< Batched with the source entry
+    not_batchable,  ///< Not eligible to batch but continue attempts to batch
+    terminate_batch,  ///< Stop trying to batch
   };
 }  // namespace input

src/input/keyboard.cpp

@@ -1,3 +1,7 @@
+/**
+ * @file src/input/keyboard.cpp
+ * @brief Definitions for common keyboard input.
+ */
 #include "keyboard.h"
 #include "init.h"
 
@@ -55,11 +59,9 @@ namespace input::keyboard {
   }
 
   /**
-   * 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) {
@@ -93,7 +95,7 @@ namespace input::keyboard {
   }
 
   /**
-   * Update flags for keyboard shortcut combo's
+   * @brief Update flags for keyboard shortcut combos
    */
   inline void
   update_shortcutFlags(int *flags, short keyCode, bool release) {
@@ -277,4 +279,4 @@ namespace input::keyboard {
   cancel() {
     task_pool.cancel(key_press_repeat_id);
   }
-}  // namespace input::keyboard
+}  // namespace input::keyboard

src/input/keyboard.h

@@ -1,3 +1,7 @@
+/**
+ * @file src/input/keyboard.h
+ * @brief Declarations for common keyboard input.
+ */
 #pragma once
 
 #include <cstdint>