From b9b28c0457e81d80fc51670b88692a062ea9e08e Mon Sep 17 00:00:00 2001 From: Morph <39850852+Morph1984@users.noreply.github.com> Date: Mon, 29 Nov 2021 16:16:05 -0500 Subject: [PATCH] core: hid: Cleanup and amend documentation --- src/core/hid/emulated_console.h | 26 +++++++------- src/core/hid/emulated_controller.h | 58 +++++++++++++++--------------- src/core/hid/emulated_devices.h | 38 ++++++++++---------- src/core/hid/input_converter.h | 23 ++++++------ 4 files changed, 76 insertions(+), 69 deletions(-) diff --git a/src/core/hid/emulated_console.h b/src/core/hid/emulated_console.h index 25c183eee..67981b844 100644 --- a/src/core/hid/emulated_console.h +++ b/src/core/hid/emulated_console.h @@ -78,7 +78,7 @@ struct ConsoleUpdateCallback { class EmulatedConsole { public: /** - * Contains all input data related to the console like motion and touch input + * Contains all input data within the emulated switch console tablet such as touch and motion */ EmulatedConsole(); ~EmulatedConsole(); @@ -89,14 +89,16 @@ public: /// Removes all callbacks created from input devices void UnloadInput(); - /// Sets the emulated console into configuring mode. Locking all HID service events from being - /// moddified + /** + * Sets the emulated console into configuring mode + * This prevents the modification of the HID state of the emulated console by input commands + */ void EnableConfiguration(); - /// Returns the emulated console to the normal behaivour + /// Returns the emulated console into normal mode, allowing the modification of the HID state void DisableConfiguration(); - /// Returns true if the emulated console is on configuring mode + /// Returns true if the emulated console is in configuring mode bool IsConfiguring() const; /// Reload all input devices @@ -116,7 +118,7 @@ public: /** * Updates the current mapped motion device - * @param ParamPackage with controller data to be mapped + * @param param ParamPackage with controller data to be mapped */ void SetMotionParam(Common::ParamPackage param); @@ -134,14 +136,14 @@ public: /** * Adds a callback to the list of events - * @param ConsoleUpdateCallback that will be triggered + * @param update_callback A ConsoleUpdateCallback that will be triggered * @return an unique key corresponding to the callback index in the list */ int SetCallback(ConsoleUpdateCallback update_callback); /** * Removes a callback from the list stopping any future events to this object - * @param Key corresponding to the callback index in the list + * @param key Key corresponding to the callback index in the list */ void DeleteCallback(int key); @@ -151,20 +153,20 @@ private: /** * Updates the motion status of the console - * @param A CallbackStatus containing gyro and accelerometer data + * @param callback A CallbackStatus containing gyro and accelerometer data */ void SetMotion(Common::Input::CallbackStatus callback); /** * Updates the touch status of the console - * @param callback: A CallbackStatus containing the touch position - * @param index: Finger ID to be updated + * @param callback A CallbackStatus containing the touch position + * @param index Finger ID to be updated */ void SetTouch(Common::Input::CallbackStatus callback, std::size_t index); /** * Triggers a callback that something has changed on the console status - * @param Input type of the event to trigger + * @param type Input type of the event to trigger */ void TriggerOnChange(ConsoleTriggerType type); diff --git a/src/core/hid/emulated_controller.h b/src/core/hid/emulated_controller.h index 2c5d51bc8..5887e3e38 100644 --- a/src/core/hid/emulated_controller.h +++ b/src/core/hid/emulated_controller.h @@ -132,8 +132,8 @@ struct ControllerUpdateCallback { class EmulatedController { public: /** - * Contains all input data related to this controller. Like buttons, joysticks, motion. - * @param Npad id type for this specific controller + * Contains all input data (buttons, joysticks, vibration, and motion) within this controller. + * @param npad_id_type npad id type for this specific controller */ explicit EmulatedController(NpadIdType npad_id_type_); ~EmulatedController(); @@ -155,7 +155,7 @@ public: /** * Gets the NpadStyleIndex for this controller - * @param If true tmp_npad_type will be returned + * @param get_temporary_value If true tmp_npad_type will be returned * @return NpadStyleIndex set on the controller */ NpadStyleIndex GetNpadStyleIndex(bool get_temporary_value = false) const; @@ -168,7 +168,7 @@ public: /** * Is the emulated connected - * @param If true tmp_is_connected will be returned + * @param get_temporary_value If true tmp_is_connected will be returned * @return true if the controller has the connected status */ bool IsConnected(bool get_temporary_value = false) const; @@ -179,14 +179,16 @@ public: /// Removes all callbacks created from input devices void UnloadInput(); - /// Sets the emulated console into configuring mode. Locking all HID service events from being - /// moddified + /** + * Sets the emulated controller into configuring mode + * This prevents the modification of the HID state of the emulated controller by input commands + */ void EnableConfiguration(); - /// Returns the emulated console to the normal behaivour + /// Returns the emulated controller into normal mode, allowing the modification of the HID state void DisableConfiguration(); - /// Returns true if the emulated device is on configuring mode + /// Returns true if the emulated controller is in configuring mode bool IsConfiguring() const; /// Reload all input devices @@ -215,19 +217,19 @@ public: /** * Updates the current mapped button device - * @param ParamPackage with controller data to be mapped + * @param param ParamPackage with controller data to be mapped */ void SetButtonParam(std::size_t index, Common::ParamPackage param); /** * Updates the current mapped stick device - * @param ParamPackage with controller data to be mapped + * @param param ParamPackage with controller data to be mapped */ void SetStickParam(std::size_t index, Common::ParamPackage param); /** * Updates the current mapped motion device - * @param ParamPackage with controller data to be mapped + * @param param ParamPackage with controller data to be mapped */ void SetMotionParam(std::size_t index, Common::ParamPackage param); @@ -270,13 +272,13 @@ public: /// Returns the latest battery status from the controller BatteryLevelState GetBattery() const; - /* + /** * Sends a specific vibration to the output device * @return returns true if vibration had no errors */ bool SetVibration(std::size_t device_index, VibrationValue vibration); - /* + /** * Sends a small vibration to the output device * @return returns true if SetVibration was successfull */ @@ -290,14 +292,14 @@ public: /** * Adds a callback to the list of events - * @param ConsoleUpdateCallback that will be triggered + * @param update_callback A ConsoleUpdateCallback that will be triggered * @return an unique key corresponding to the callback index in the list */ int SetCallback(ControllerUpdateCallback update_callback); /** * Removes a callback from the list stopping any future events to this object - * @param Key corresponding to the callback index in the list + * @param key Key corresponding to the callback index in the list */ void DeleteCallback(int key); @@ -310,43 +312,43 @@ private: /** * Updates the button status of the controller - * @param callback: A CallbackStatus containing the button status - * @param index: Button ID of the to be updated + * @param callback A CallbackStatus containing the button status + * @param index Button ID of the to be updated */ void SetButton(Common::Input::CallbackStatus callback, std::size_t index, Common::UUID uuid); /** * Updates the analog stick status of the controller - * @param callback: A CallbackStatus containing the analog stick status - * @param index: stick ID of the to be updated + * @param callback A CallbackStatus containing the analog stick status + * @param index stick ID of the to be updated */ void SetStick(Common::Input::CallbackStatus callback, std::size_t index, Common::UUID uuid); /** * Updates the trigger status of the controller - * @param callback: A CallbackStatus containing the trigger status - * @param index: trigger ID of the to be updated + * @param callback A CallbackStatus containing the trigger status + * @param index trigger ID of the to be updated */ void SetTrigger(Common::Input::CallbackStatus callback, std::size_t index, Common::UUID uuid); /** * Updates the motion status of the controller - * @param callback: A CallbackStatus containing gyro and accelerometer data - * @param index: motion ID of the to be updated + * @param callback A CallbackStatus containing gyro and accelerometer data + * @param index motion ID of the to be updated */ void SetMotion(Common::Input::CallbackStatus callback, std::size_t index); /** * Updates the battery status of the controller - * @param callback: A CallbackStatus containing the battery status - * @param index: Button ID of the to be updated + * @param callback A CallbackStatus containing the battery status + * @param index Button ID of the to be updated */ void SetBattery(Common::Input::CallbackStatus callback, std::size_t index); /** * Triggers a callback that something has changed on the controller status - * @param type: Input type of the event to trigger - * @param is_service_update: indicates if this event should be sended to only services + * @param type Input type of the event to trigger + * @param is_service_update indicates if this event should only be sent to HID services */ void TriggerOnChange(ControllerTriggerType type, bool is_service_update); @@ -357,7 +359,7 @@ private: f32 motion_sensitivity{0.01f}; bool force_update_motion{false}; - // Temporary values to avoid doing changes while the controller is on configuration mode + // Temporary values to avoid doing changes while the controller is in configuring mode NpadStyleIndex tmp_npad_type{NpadStyleIndex::None}; bool tmp_is_connected{false}; diff --git a/src/core/hid/emulated_devices.h b/src/core/hid/emulated_devices.h index 05a945d08..d4f457651 100644 --- a/src/core/hid/emulated_devices.h +++ b/src/core/hid/emulated_devices.h @@ -75,7 +75,7 @@ class EmulatedDevices { public: /** * Contains all input data related to external devices that aren't necesarily a controller - * like keyboard and mouse + * This includes devices such as the keyboard or mouse */ EmulatedDevices(); ~EmulatedDevices(); @@ -86,14 +86,16 @@ public: /// Removes all callbacks created from input devices void UnloadInput(); - /// Sets the emulated console into configuring mode. Locking all HID service events from being - /// moddified + /** + * Sets the emulated devices into configuring mode + * This prevents the modification of the HID state of the emulated devices by input commands + */ void EnableConfiguration(); - /// Returns the emulated console to the normal behaivour + /// Returns the emulated devices into normal mode, allowing the modification of the HID state void DisableConfiguration(); - /// Returns true if the emulated device is on configuring mode + /// Returns true if the emulated device is in configuring mode bool IsConfiguring() const; /// Reload all input devices @@ -134,14 +136,14 @@ public: /** * Adds a callback to the list of events - * @param InterfaceUpdateCallback that will be triggered + * @param update_callback InterfaceUpdateCallback that will be triggered * @return an unique key corresponding to the callback index in the list */ int SetCallback(InterfaceUpdateCallback update_callback); /** * Removes a callback from the list stopping any future events to this object - * @param Key corresponding to the callback index in the list + * @param key Key corresponding to the callback index in the list */ void DeleteCallback(int key); @@ -151,42 +153,42 @@ private: /** * Updates the touch status of the keyboard device - * @param callback: A CallbackStatus containing the key status - * @param index: key ID to be updated + * @param callback A CallbackStatus containing the key status + * @param index key ID to be updated */ void SetKeyboardButton(Common::Input::CallbackStatus callback, std::size_t index); /** * Updates the keyboard status of the keyboard device - * @param callback: A CallbackStatus containing the modifier key status - * @param index: modifier key ID to be updated + * @param callback A CallbackStatus containing the modifier key status + * @param index modifier key ID to be updated */ void SetKeyboardModifier(Common::Input::CallbackStatus callback, std::size_t index); /** * Updates the mouse button status of the mouse device - * @param callback: A CallbackStatus containing the button status - * @param index: Button ID to be updated + * @param callback A CallbackStatus containing the button status + * @param index Button ID to be updated */ void SetMouseButton(Common::Input::CallbackStatus callback, std::size_t index); /** * Updates the mouse wheel status of the mouse device - * @param callback: A CallbackStatus containing the wheel status - * @param index: wheel ID to be updated + * @param callback A CallbackStatus containing the wheel status + * @param index wheel ID to be updated */ void SetMouseAnalog(Common::Input::CallbackStatus callback, std::size_t index); /** * Updates the mouse position status of the mouse device - * @param callback: A CallbackStatus containing the position status - * @param index: stick ID to be updated + * @param callback A CallbackStatus containing the position status + * @param index stick ID to be updated */ void SetMouseStick(Common::Input::CallbackStatus callback); /** * Triggers a callback that something has changed on the device status - * @param Input type of the event to trigger + * @param type Input type of the event to trigger */ void TriggerOnChange(DeviceTriggerType type); diff --git a/src/core/hid/input_converter.h b/src/core/hid/input_converter.h index 1492489d7..d24582226 100644 --- a/src/core/hid/input_converter.h +++ b/src/core/hid/input_converter.h @@ -21,7 +21,7 @@ namespace Core::HID { /** * Converts raw input data into a valid battery status. * - * @param Supported callbacks: Analog, Battery, Trigger. + * @param callback Supported callbacks: Analog, Battery, Trigger. * @return A valid BatteryStatus object. */ Common::Input::BatteryStatus TransformToBattery(const Common::Input::CallbackStatus& callback); @@ -29,7 +29,7 @@ Common::Input::BatteryStatus TransformToBattery(const Common::Input::CallbackSta /** * Converts raw input data into a valid button status. Applies invert properties to the output. * - * @param Supported callbacks: Analog, Button, Trigger. + * @param callback Supported callbacks: Analog, Button, Trigger. * @return A valid TouchStatus object. */ Common::Input::ButtonStatus TransformToButton(const Common::Input::CallbackStatus& callback); @@ -37,7 +37,7 @@ Common::Input::ButtonStatus TransformToButton(const Common::Input::CallbackStatu /** * Converts raw input data into a valid motion status. * - * @param Supported callbacks: Motion. + * @param callback Supported callbacks: Motion. * @return A valid TouchStatus object. */ Common::Input::MotionStatus TransformToMotion(const Common::Input::CallbackStatus& callback); @@ -46,7 +46,7 @@ Common::Input::MotionStatus TransformToMotion(const Common::Input::CallbackStatu * Converts raw input data into a valid stick status. Applies offset, deadzone, range and invert * properties to the output. * - * @param Supported callbacks: Stick. + * @param callback Supported callbacks: Stick. * @return A valid StickStatus object. */ Common::Input::StickStatus TransformToStick(const Common::Input::CallbackStatus& callback); @@ -54,7 +54,7 @@ Common::Input::StickStatus TransformToStick(const Common::Input::CallbackStatus& /** * Converts raw input data into a valid touch status. * - * @param Supported callbacks: Touch. + * @param callback Supported callbacks: Touch. * @return A valid TouchStatus object. */ Common::Input::TouchStatus TransformToTouch(const Common::Input::CallbackStatus& callback); @@ -63,7 +63,7 @@ Common::Input::TouchStatus TransformToTouch(const Common::Input::CallbackStatus& * Converts raw input data into a valid trigger status. Applies offset, deadzone, range and * invert properties to the output. Button status uses the threshold property if necessary. * - * @param Supported callbacks: Analog, Button, Trigger. + * @param callback Supported callbacks: Analog, Button, Trigger. * @return A valid TriggerStatus object. */ Common::Input::TriggerStatus TransformToTrigger(const Common::Input::CallbackStatus& callback); @@ -72,22 +72,23 @@ Common::Input::TriggerStatus TransformToTrigger(const Common::Input::CallbackSta * Converts raw input data into a valid analog status. Applies offset, deadzone, range and * invert properties to the output. * - * @param Supported callbacks: Analog. + * @param callback Supported callbacks: Analog. * @return A valid AnalogStatus object. */ Common::Input::AnalogStatus TransformToAnalog(const Common::Input::CallbackStatus& callback); /** * Converts raw analog data into a valid analog value - * @param An analog object containing raw data and properties, bool that determines if the value - * needs to be clamped between -1.0f and 1.0f. + * @param analog An analog object containing raw data and properties + * @param clamp_value determines if the value needs to be clamped between -1.0f and 1.0f. */ void SanitizeAnalog(Common::Input::AnalogStatus& analog, bool clamp_value); /** * Converts raw stick data into a valid stick value - * @param Two analog objects containing raw data and properties, bool that determines if the value - * needs to be clamped into the unit circle. + * @param analog_x raw analog data and properties for the x-axis + * @param analog_y raw analog data and properties for the y-axis + * @param clamp_value bool that determines if the value needs to be clamped into the unit circle. */ void SanitizeStick(Common::Input::AnalogStatus& analog_x, Common::Input::AnalogStatus& analog_y, bool clamp_value);