From 72af14c0ee1937baaa0737c424c0c2be51321ffa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjamin=20H=C3=B6glinger-Stelzer?= Date: Tue, 1 Sep 2020 18:45:29 +0200 Subject: [PATCH] Doc comment formatting fixes --- sdk/include/ViGEm/Client.h | 380 ++++++++++++++++--------------------- 1 file changed, 160 insertions(+), 220 deletions(-) diff --git a/sdk/include/ViGEm/Client.h b/sdk/include/ViGEm/Client.h index 3d36283..bcfd55f 100644 --- a/sdk/include/ViGEm/Client.h +++ b/sdk/include/ViGEm/Client.h @@ -41,12 +41,8 @@ extern "C" { #else #define VIGEM_API #endif - - /** - * \typedef enum _VIGEM_ERRORS - * - * \brief Defines an alias representing the ViGEm errors. - */ + + /** Values that represent ViGEm errors */ typedef enum _VIGEM_ERRORS { VIGEM_ERROR_NONE = 0x20000000, @@ -68,30 +64,20 @@ extern "C" { } VIGEM_ERROR; - /** - * \def VIGEM_SUCCESS(_val_) (_val_ == VIGEM_ERROR_NONE); - * - * \brief A macro that defines success. - * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 - * - * \param _val_ The VIGEM_ERROR value. - */ +/** + * A macro that defines if the API succeeded + * + * @author Benjamin "Nefarius" Höglinger-Stelzer + * @date 01.09.2020 + * + * @param _val_ The error value. + */ #define VIGEM_SUCCESS(_val_) (_val_ == VIGEM_ERROR_NONE) - /** - * \typedef struct _VIGEM_CLIENT_T *PVIGEM_CLIENT - * - * \brief Defines an alias representing a driver connection object. - */ + /** Defines an alias representing a driver connection object */ typedef struct _VIGEM_CLIENT_T *PVIGEM_CLIENT; - /** - * \typedef struct _VIGEM_TARGET_T *PVIGEM_TARGET - * - * \brief Defines an alias representing a target device object. - */ + /** Defines an alias representing a target device object */ typedef struct _VIGEM_TARGET_T *PVIGEM_TARGET; typedef @@ -134,363 +120,317 @@ extern "C" { typedef EVT_VIGEM_DS4_NOTIFICATION *PFN_VIGEM_DS4_NOTIFICATION; /** - * \fn PVIGEM_CLIENT vigem_alloc(void); + * Allocates an object representing a driver connection * - * \brief Allocates an object representing a driver connection. + * @author Benjamin "Nefarius" Höglinger-Stelzer + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 - * - * \return A new driver connection object. + * @returns A PVIGEM_CLIENT object. */ VIGEM_API PVIGEM_CLIENT vigem_alloc(void); /** - * \fn void vigem_free(PVIGEM_CLIENT vigem); + * Frees up memory used by the driver connection object * - * \brief Frees up memory used by the driver connection object. + * @author Benjamin "Nefarius" Höglinger-Stelzer + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 - * - * \param vigem The driver connection object. + * @param vigem The PVIGEM_CLIENT object. */ VIGEM_API void vigem_free(PVIGEM_CLIENT vigem); /** - * \fn VIGEM_ERROR vigem_connect(PVIGEM_CLIENT vigem); - * - * \brief Initializes the driver object and establishes a connection to the emulation bus + * Initializes the driver object and establishes a connection to the emulation bus * driver. Returns an error if no compatible bus device has been found. * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 + * @author Benjamin "Nefarius" Höglinger-Stelzer + * @date 28.08.2017 * - * \param vigem The driver connection object. + * @param vigem The PVIGEM_CLIENT object. * - * \return A VIGEM_ERROR. + * @returns A VIGEM_ERROR. */ VIGEM_API VIGEM_ERROR vigem_connect(PVIGEM_CLIENT vigem); /** - * \fn void vigem_disconnect(PVIGEM_CLIENT vigem); + * Disconnects from the bus device and resets the driver object state. The driver object + * may be reused again after calling this function. When called, all targets which may + * still be connected will be destroyed automatically. Be aware, that allocated target + * objects won't be automatically freed, this has to be taken care of by the caller. * - * \brief Disconnects from the bus device and resets the driver object state. The driver object - * may be reused again after calling this function. When called, all targets which may - * still be connected will be destroyed automatically. Be aware, that allocated target - * objects won't be automatically freed, this has to be taken care of by the caller. + * @author Benjamin "Nefarius" Höglinger-Stelzer + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 - * - * \param vigem The driver connection object. + * @param vigem The PVIGEM_CLIENT object. */ VIGEM_API void vigem_disconnect(PVIGEM_CLIENT vigem); /** - * \fn PVIGEM_TARGET vigem_target_x360_alloc(void); + * Allocates an object representing an Xbox 360 Controller device. * - * \brief Allocates an object representing an Xbox 360 Controller device. + * @author Benjamin "Nefarius" Höglinger-Stelzer + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 - * - * \return A PVIGEM_TARGET representing an Xbox 360 Controller device. + * @returns A PVIGEM_TARGET representing an Xbox 360 Controller device. */ VIGEM_API PVIGEM_TARGET vigem_target_x360_alloc(void); /** - * \fn PVIGEM_TARGET vigem_target_ds4_alloc(void); + * Allocates an object representing a DualShock 4 Controller device. * - * \brief Allocates an object representing a DualShock 4 Controller device. + * @author Benjamin "Nefarius" Höglinger-Stelzer + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 - * - * \return A PVIGEM_TARGET representing a DualShock 4 Controller device. + * @returns A PVIGEM_TARGET representing a DualShock 4 Controller device. */ VIGEM_API PVIGEM_TARGET vigem_target_ds4_alloc(void); /** - * \fn void vigem_target_free(PVIGEM_TARGET target); - * - * \brief Frees up memory used by the target device object. This does not automatically remove + * Frees up memory used by the target device object. This does not automatically remove * the associated device from the bus, if present. If the target device doesn't get * removed before this call, the device becomes orphaned until the owning process is * terminated. * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 + * @author Benjamin "Nefarius" Höglinger-Stelzer + * @date 28.08.2017 * - * \param target The target device object. + * @param target The target device object. */ VIGEM_API void vigem_target_free(PVIGEM_TARGET target); /** - * \fn VIGEM_ERROR vigem_target_add(PVIGEM_CLIENT vigem, PVIGEM_TARGET target); - * - * \brief Adds a provided target device to the bus driver, which is equal to a device plug-in + * Adds a provided target device to the bus driver, which is equal to a device plug-in * event of a physical hardware device. This function blocks until the target device is * in full operational mode. * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 + * @author Benjamin "Nefarius" Höglinger-Stelzer + * @date 28.08.2017 * - * \param vigem The driver connection object. - * \param target The target device object. + * @param vigem The driver connection object. + * @param target The target device object. * - * \return A VIGEM_ERROR. + * @returns A VIGEM_ERROR. */ VIGEM_API VIGEM_ERROR vigem_target_add(PVIGEM_CLIENT vigem, PVIGEM_TARGET target); /** - * \fn VIGEM_ERROR vigem_target_add_async(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, PVIGEM_TARGET_ADD_RESULT result); - * - * \brief Adds a provided target device to the bus driver, which is equal to a device plug-in + * Adds a provided target device to the bus driver, which is equal to a device plug-in * event of a physical hardware device. This function immediately returns. An optional * callback may be registered which gets called on error or if the target device has * become fully operational. * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 + * @author Benjamin "Nefarius" Höglinger-Stelzer + * @date 28.08.2017 * - * \param vigem The driver connection object. - * \param target The target device object. - * \param result An optional function getting called when the target device becomes available. + * @param vigem The driver connection object. + * @param target The target device object. + * @param result An optional function getting called when the target device becomes available. * - * \return A VIGEM_ERROR. + * @returns A VIGEM_ERROR. */ VIGEM_API VIGEM_ERROR vigem_target_add_async(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, PFN_VIGEM_TARGET_ADD_RESULT result); /** - * \fn VIGEM_ERROR vigem_target_remove(PVIGEM_CLIENT vigem, PVIGEM_TARGET target); + * Removes a provided target device from the bus driver, which is equal to a device + * unplug event of a physical hardware device. The target device object may be reused + * after this function is called. If this function is never called on target device + * objects, they will be removed from the bus when the owning process terminates. * - * \brief Removes a provided target device from the bus driver, which is equal to a device - * unplug event of a physical hardware device. The target device object may be reused - * after this function is called. If this function is never called on target device - * objects, they will be removed from the bus when the owning process terminates. + * @author Benjamin "Nefarius" Höglinger + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 + * @param vigem The driver connection object. + * @param target The target device object. * - * \param vigem The driver connection object. - * \param target The target device object. - * - * \return A VIGEM_ERROR. + * @returns A VIGEM_ERROR. */ VIGEM_API VIGEM_ERROR vigem_target_remove(PVIGEM_CLIENT vigem, PVIGEM_TARGET target); /** - * \fn VIGEM_ERROR vigem_target_x360_register_notification(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, PVIGEM_X360_NOTIFICATION notification); + * Registers a function which gets called, when LED index or vibration state changes + * occur on the provided target device. This function fails if the provided + * target device isn't fully operational or in an erroneous state. * - * \brief Registers a function which gets called, when LED index or vibration state changes - * occur on the provided target device. This function fails if the provided target - * device isn't fully operational or in an erroneous state. + * @author Benjamin "Nefarius" Höglinger + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 + * @param vigem The driver connection object. + * @param target The target device object. + * @param notification The notification callback. + * @param userData The user data passed to the notification callback. * - * \param vigem The driver connection object. - * \param target The target device object. - * \param notification The notification callback. - * \param userData The user data passed to the notification callback. - * - * \return A VIGEM_ERROR. + * @returns A VIGEM_ERROR. */ VIGEM_API VIGEM_ERROR vigem_target_x360_register_notification(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, PFN_VIGEM_X360_NOTIFICATION notification, LPVOID userData); /** - * \fn VIGEM_ERROR vigem_target_ds4_register_notification(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, PVIGEM_DS4_NOTIFICATION notification); + * Registers a function which gets called, when LightBar or vibration state changes + * occur on the provided target device. This function fails if the provided + * target device isn't fully operational or in an erroneous state. * - * \brief Registers a function which gets called, when LightBar or vibration state changes - * occur on the provided target device. This function fails if the provided target - * device isn't fully operational or in an erroneous state. + * @author Benjamin "Nefarius" Höglinger + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 + * @param vigem The driver connection object. + * @param target The target device object. + * @param notification The notification callback. + * @param userData The user data passed to the notification callback. * - * \param vigem The driver connection object. - * \param target The target device object. - * \param notification The notification callback. - * \param userData The user data passed to the notification callback. - * - * \return A VIGEM_ERROR. + * @returns A VIGEM_ERROR. */ VIGEM_API VIGEM_ERROR vigem_target_ds4_register_notification(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, PFN_VIGEM_DS4_NOTIFICATION notification, LPVOID userData); /** - * \fn void vigem_target_x360_unregister_notification(PVIGEM_TARGET target); + * Removes a previously registered callback function from the provided target object. * - * \brief Removes a previously registered callback function from the provided target object. + * @author Benjamin "Nefarius" Höglinger + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 - * - * \param target The target device object. + * @param target The target device object. */ VIGEM_API void vigem_target_x360_unregister_notification(PVIGEM_TARGET target); /** - * \fn void vigem_target_ds4_unregister_notification(PVIGEM_TARGET target); + * Removes a previously registered callback function from the provided target object. * - * \brief Removes a previously registered callback function from the provided target object. + * @author Benjamin "Nefarius" Höglinger + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 - * - * \param target The target device object. + * @param target The target device object. */ VIGEM_API void vigem_target_ds4_unregister_notification(PVIGEM_TARGET target); /** - * \fn void vigem_target_set_vid(PVIGEM_TARGET target, USHORT vid); + * Overrides the default Vendor ID value with the provided one. * - * \brief Overrides the default Vendor ID value with the provided one. + * @author Benjamin "Nefarius" Höglinger + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 - * - * \param target The target device object. - * \param vid The Vendor ID to set. + * @param target The target device object. + * @param vid The Vendor ID to set. */ VIGEM_API void vigem_target_set_vid(PVIGEM_TARGET target, USHORT vid); /** - * \fn void vigem_target_set_pid(PVIGEM_TARGET target, USHORT pid); + * Overrides the default Product ID value with the provided one. * - * \brief Overrides the default Product ID value with the provided one. + * @author Benjamin "Nefarius" Höglinger + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 - * - * \param target The target device object. - * \param pid The Product ID to set. + * @param target The target device object. + * @param pid The Product ID to set. */ VIGEM_API void vigem_target_set_pid(PVIGEM_TARGET target, USHORT pid); /** - * \fn USHORT vigem_target_get_vid(PVIGEM_TARGET target); + * Returns the Vendor ID of the provided target device object. * - * \brief Returns the Vendor ID of the provided target device object. + * @author Benjamin "Nefarius" Höglinger + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 + * @param target The target device object. * - * \param target The target device object. - * - * \return The Vendor ID. + * @returns The Vendor ID. */ VIGEM_API USHORT vigem_target_get_vid(PVIGEM_TARGET target); /** - * \fn USHORT vigem_target_get_pid(PVIGEM_TARGET target); + * Returns the Product ID of the provided target device object. * - * \brief Returns the Product ID of the provided target device object. + * @author Benjamin "Nefarius" Höglinger + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 + * @param target The target device object. * - * \param target The target device object. - * - * \return The Product ID. + * @returns The Product ID. */ VIGEM_API USHORT vigem_target_get_pid(PVIGEM_TARGET target); /** - * \fn VIGEM_ERROR vigem_target_x360_update(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, XUSB_REPORT report); + * Sends a state report to the provided target device. * - * \brief Sends a state report to the provided target device. + * @author Benjamin "Nefarius" Höglinger + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 + * @param vigem The driver connection object. + * @param target The target device object. + * @param report The report to send to the target device. * - * \param vigem The driver connection object. - * \param target The target device object. - * \param report The report to send to the target device. - * - * \return A VIGEM_ERROR. + * @returns A VIGEM_ERROR. */ VIGEM_API VIGEM_ERROR vigem_target_x360_update(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, XUSB_REPORT report); /** - * \fn VIGEM_ERROR vigem_target_ds4_update(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, DS4_REPORT report); + * Sends a state report to the provided target device. * - * \brief Sends a state report to the provided target device. + * @author Benjamin "Nefarius" Höglinger + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 + * @param vigem The driver connection object. + * @param target The target device object. + * @param report The report to send to the target device. * - * \param vigem The driver connection object. - * \param target The target device object. - * \param report The report to send to the target device. - * - * \return A VIGEM_ERROR. + * @returns A VIGEM_ERROR. */ VIGEM_API VIGEM_ERROR vigem_target_ds4_update(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, DS4_REPORT report); /** - * \fn ULONG vigem_target_get_index(PVIGEM_TARGET target); + * Returns the internal index (serial number) the bus driver assigned to the provided + * target device object. Note that this value is specific to the inner workings of + * the bus driver, it does not reflect related values like player index or device + * arrival order experienced by other APIs. It may be used to identify the target + * device object for its lifetime. This value becomes invalid once the target + * device is removed from the bus and may change on the next addition of the + * device. * - * \brief Returns the internal index (serial number) the bus driver assigned to the provided - * target device object. Note that this value is specific to the inner workings of the - * bus driver, it does not reflect related values like player index or device arrival - * order experienced by other APIs. It may be used to identify the target device object - * for its lifetime. This value becomes invalid once the target device is removed from - * the bus and may change on the next addition of the device. + * @author Benjamin "Nefarius" Höglinger + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 + * @param target The target device object. * - * \param target The target device object. - * - * \return The internally used index of the target device. + * @returns The internally used index of the target device. */ VIGEM_API ULONG vigem_target_get_index(PVIGEM_TARGET target); /** - * \fn VIGEM_TARGET_TYPE vigem_target_get_type(PVIGEM_TARGET target); + * Returns the type of the provided target device object. * - * \brief Returns the type of the provided target device object. + * @author Benjamin "Nefarius" Höglinger + * @date 28.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 28.08.2017 + * @param target The target device object. * - * \param target The target device object. - * - * \return A VIGEM_TARGET_TYPE. + * @returns A VIGEM_TARGET_TYPE. */ VIGEM_API VIGEM_TARGET_TYPE vigem_target_get_type(PVIGEM_TARGET target); /** - * \fn BOOL vigem_target_is_attached(PVIGEM_TARGET target); + * Returns TRUE if the provided target device object is currently attached to the bus, + * FALSE otherwise. * - * \brief Returns TRUE if the provided target device object is currently attached to the bus, - * FALSE otherwise. + * @author Benjamin "Nefarius" Höglinger + * @date 30.08.2017 * - * \author Benjamin "Nefarius" Höglinger - * \date 30.08.2017 + * @param target The target device object. * - * \param target The target device object. - * - * \return TRUE if device is attached to the bus, FALSE otherwise. + * @returns TRUE if device is attached to the bus, FALSE otherwise. */ VIGEM_API BOOL vigem_target_is_attached(PVIGEM_TARGET target); /** - * \fn VIGEM_API VIGEM_ERROR vigem_target_x360_get_user_index(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, PULONG index); + * Returns the user index of the emulated Xenon device. This value correspondents to the + * (zero-based) index number representing the player number via LED present on a + * physical controller and is compatible to the dwUserIndex property of the + * XInput* APIs. * - * \brief Returns the user index of the emulated Xenon device. This value correspondents to the - * (zero-based) index number representing the player number via LED present on a - * physical controller and is compatible to the dwUserIndex propery of the XInput* APIs. + * @author Benjamin "Nefarius" Höglinger + * @date 10.05.2018 * - * \author Benjamin "Nefarius" Höglinger - * \date 10.05.2018 + * @param vigem The driver connection object. + * @param target The target device object. + * @param index The (zero-based) user index of the Xenon device. * - * \param vigem The driver connection object. - * \param target The target device object. - * \param index The (zero-based) user index of the Xenon device. - * - * \return A VIGEM_ERROR. + * @returns A VIGEM_ERROR. */ VIGEM_API VIGEM_ERROR vigem_target_x360_get_user_index(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, PULONG index);