arreglat makefile, info.plist i sdl.frameworks per a compilar en macos intel

release/SDL2.framework/Versions/A/Headers/SDL_gamecontroller.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -19,10 +19,12 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
+/* WIKI CATEGORY: GameController */
+
 /**
- *  \file SDL_gamecontroller.h
+ * # CategoryGameController
  *
- *  Include file for SDL game controller event handling
+ * Include file for SDL game controller event handling
  */
 
 #ifndef SDL_gamecontroller_h_
@@ -44,7 +46,7 @@ extern "C" {
  *  \file SDL_gamecontroller.h
  *
  *  In order to use these functions, SDL_Init() must have been called
- *  with the ::SDL_INIT_GAMECONTROLLER flag.  This causes SDL to scan the system
+ *  with the SDL_INIT_GAMECONTROLLER flag.  This causes SDL to scan the system
  *  for game controllers, and load appropriate drivers.
  *
  *  If you would like to receive controller updates while the application
@@ -58,7 +60,7 @@ extern "C" {
 struct _SDL_GameController;
 typedef struct _SDL_GameController SDL_GameController;
 
-typedef enum
+typedef enum SDL_GameControllerType
 {
     SDL_CONTROLLER_TYPE_UNKNOWN = 0,
     SDL_CONTROLLER_TYPE_XBOX360,
@@ -73,10 +75,11 @@ typedef enum
     SDL_CONTROLLER_TYPE_NVIDIA_SHIELD,
     SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_LEFT,
     SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT,
-    SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_PAIR
+    SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_PAIR,
+    SDL_CONTROLLER_TYPE_MAX
 } SDL_GameControllerType;
 
-typedef enum
+typedef enum SDL_GameControllerBindType
 {
     SDL_CONTROLLER_BINDTYPE_NONE = 0,
     SDL_CONTROLLER_BINDTYPE_BUTTON,
@@ -85,7 +88,7 @@ typedef enum
 } SDL_GameControllerBindType;
 
 /**
- *  Get the SDL joystick layer binding for this controller button/axis mapping
+ * Get the SDL joystick layer binding for this controller button/axis mapping
  */
 typedef struct SDL_GameControllerButtonBind
 {
@@ -143,6 +146,10 @@ typedef struct SDL_GameControllerButtonBind
  * If a new mapping is loaded for an already known controller GUID, the later
  * version will overwrite the one currently loaded.
  *
+ * If this function is called before SDL_Init, SDL will generate an
+ * SDL_CONTROLLERDEVICEADDED event for matching controllers that are plugged
+ * in at the time that SDL_Init is called.
+ *
  * Mappings not belonging to the current platform or with no platform field
  * specified will be ignored (i.e. mappings for Linux will be ignored in
  * Windows, etc).
@@ -151,8 +158,8 @@ typedef struct SDL_GameControllerButtonBind
  * processing it, so take this into consideration if you are in a memory
  * constrained environment.
  *
- * \param rw the data stream for the mappings to be added
- * \param freerw non-zero to close the stream after being read
+ * \param rw the data stream for the mappings to be added.
+ * \param freerw non-zero to close the stream after being read.
  * \returns the number of mappings added or -1 on error; call SDL_GetError()
  *          for more information.
  *
@@ -161,13 +168,15 @@ typedef struct SDL_GameControllerButtonBind
  * \sa SDL_GameControllerAddMapping
  * \sa SDL_GameControllerAddMappingsFromFile
  * \sa SDL_GameControllerMappingForGUID
+ * \sa SDL_CONTROLLERDEVICEADDED
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw);
 
 /**
- *  Load a set of mappings from a file, filtered by the current SDL_GetPlatform()
+ * Load a set of mappings from a file, filtered by the current
+ * SDL_GetPlatform()
  *
- *  Convenience macro.
+ * Convenience macro.
  */
 #define SDL_GameControllerAddMappingsFromFile(file)   SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1)
 
@@ -189,7 +198,11 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
  * "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7"
  * ```
  *
- * \param mappingString the mapping string
+ * If this function is called before SDL_Init, SDL will generate an
+ * SDL_CONTROLLERDEVICEADDED event for matching controllers that are plugged
+ * in at the time that SDL_Init is called.
+ *
+ * \param mappingString the mapping string.
  * \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
  *          -1 on error; call SDL_GetError() for more information.
  *
@@ -197,6 +210,7 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
  *
  * \sa SDL_GameControllerMapping
  * \sa SDL_GameControllerMappingForGUID
+ * \sa SDL_CONTROLLERDEVICEADDED
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping(const char* mappingString);
 
@@ -224,7 +238,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_ind
  *
  * The returned string must be freed with SDL_free().
  *
- * \param guid a structure containing the GUID for which a mapping is desired
+ * \param guid a structure containing the GUID for which a mapping is desired.
  * \returns a mapping string or NULL on error; call SDL_GetError() for more
  *          information.
  *
@@ -243,7 +257,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID(SDL_JoystickGUID
  * Details about mappings are discussed with SDL_GameControllerAddMapping().
  *
  * \param gamecontroller the game controller you want to get the current
- *                       mapping for
+ *                       mapping for.
  * \returns a string that has the controller's mapping or NULL if no mapping
  *          is available; call SDL_GetError() for more information.
  *
@@ -261,7 +275,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gam
  * SDL_JoystickOpen().
  *
  * \param joystick_index the device_index of a device, up to
- *                       SDL_NumJoysticks()
+ *                       SDL_NumJoysticks().
  * \returns SDL_TRUE if the given joystick is supported by the game controller
  *          interface, SDL_FALSE if it isn't or it's an invalid index.
  *
@@ -281,7 +295,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index);
  * SDL_JoystickOpen().
  *
  * \param joystick_index the device_index of a device, from zero to
- *                       SDL_NumJoysticks()-1
+ *                       SDL_NumJoysticks()-1.
  * \returns the implementation-dependent name for the game controller, or NULL
  *          if there is no name or the index is invalid.
  *
@@ -302,7 +316,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_
  * SDL_JoystickOpen().
  *
  * \param joystick_index the device_index of a device, from zero to
- *                       SDL_NumJoysticks()-1
+ *                       SDL_NumJoysticks()-1.
  * \returns the implementation-dependent path for the game controller, or NULL
  *          if there is no path or the index is invalid.
  *
@@ -318,7 +332,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerPathForIndex(int joystick_
  * This can be called before any controllers are opened.
  *
  * \param joystick_index the device_index of a device, from zero to
- *                       SDL_NumJoysticks()-1
+ *                       SDL_NumJoysticks()-1.
  * \returns the controller type.
  *
  * \since This function is available since SDL 2.0.12.
@@ -331,7 +345,7 @@ extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(in
  * This can be called before any controllers are opened.
  *
  * \param joystick_index the device_index of a device, from zero to
- *                       SDL_NumJoysticks()-1
+ *                       SDL_NumJoysticks()-1.
  * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
  *          no mapping is available.
  *
@@ -351,7 +365,7 @@ extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joysti
  * be used there instead.
  *
  * \param joystick_index the device_index of a device, up to
- *                       SDL_NumJoysticks()
+ *                       SDL_NumJoysticks().
  * \returns a gamecontroller identifier or NULL if an error occurred; call
  *          SDL_GetError() for more information.
  *
@@ -366,7 +380,7 @@ extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_
 /**
  * Get the SDL_GameController associated with an instance id.
  *
- * \param joyid the instance id to get the SDL_GameController for
+ * \param joyid the instance id to get the SDL_GameController for.
  * \returns an SDL_GameController on success or NULL on failure; call
  *          SDL_GetError() for more information.
  *
@@ -398,7 +412,7 @@ extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromPlayerIndex(in
  * it takes a controller identifier instead of the (unstable) device index.
  *
  * \param gamecontroller a game controller identifier previously returned by
- *                       SDL_GameControllerOpen()
+ *                       SDL_GameControllerOpen().
  * \returns the implementation dependent name for the game controller, or NULL
  *          if there is no name or the identifier passed is invalid.
  *
@@ -416,7 +430,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *g
  * it takes a controller identifier instead of the (unstable) device index.
  *
  * \param gamecontroller a game controller identifier previously returned by
- *                       SDL_GameControllerOpen()
+ *                       SDL_GameControllerOpen().
  * \returns the implementation dependent path for the game controller, or NULL
  *          if there is no path or the identifier passed is invalid.
  *
@@ -523,11 +537,25 @@ extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetFirmwareVersion(SDL_GameCont
  */
 extern DECLSPEC const char * SDLCALL SDL_GameControllerGetSerial(SDL_GameController *gamecontroller);
 
+/**
+ * Get the Steam Input handle of an opened controller, if available.
+ *
+ * Returns an InputHandle_t for the controller that can be used with Steam
+ * Input API: https://partner.steamgames.com/doc/api/ISteamInput
+ *
+ * \param gamecontroller the game controller object to query.
+ * \returns the gamepad handle, or 0 if unavailable.
+ *
+ * \since This function is available since SDL 2.30.0.
+ */
+extern DECLSPEC Uint64 SDLCALL SDL_GameControllerGetSteamHandle(SDL_GameController *gamecontroller);
+
+
 /**
  * Check if a controller has been opened and is currently connected.
  *
  * \param gamecontroller a game controller identifier previously returned by
- *                       SDL_GameControllerOpen()
+ *                       SDL_GameControllerOpen().
  * \returns SDL_TRUE if the controller has been opened and is currently
  *          connected, or SDL_FALSE if not.
  *
@@ -552,7 +580,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameControlle
  * cause SDL to crash.
  *
  * \param gamecontroller the game controller object that you want to get a
- *                       joystick from
+ *                       joystick from.
  * \returns a SDL_Joystick object; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 2.0.0.
@@ -569,7 +597,7 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameCont
  * Any number can be passed to SDL_GameControllerEventState(), but only -1, 0,
  * and 1 will have any effect. Other numbers will just be returned.
  *
- * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
+ * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`.
  * \returns the same value passed to the function, with exception to -1
  *          (SDL_QUERY), which will return the current state.
  *
@@ -592,15 +620,19 @@ extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void);
 
 
 /**
- *  The list of axes available from a controller
+ * The list of axes available from a controller
  *
- *  Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to SDL_JOYSTICK_AXIS_MAX,
- *  and are centered within ~8000 of zero, though advanced UI will allow users to set
- *  or autodetect the dead zone, which varies between controllers.
+ * Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to
+ * SDL_JOYSTICK_AXIS_MAX, and are centered within ~8000 of zero, though
+ * advanced UI will allow users to set or autodetect the dead zone, which
+ * varies between controllers.
  *
- *  Trigger axis values range from 0 to SDL_JOYSTICK_AXIS_MAX.
+ * Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX (fully
+ * pressed) when reported by SDL_GameControllerGetAxis(). Note that this is
+ * not the same range that will be reported by the lower-level
+ * SDL_GetJoystickAxis().
  */
-typedef enum
+typedef enum SDL_GameControllerAxis
 {
     SDL_CONTROLLER_AXIS_INVALID = -1,
     SDL_CONTROLLER_AXIS_LEFTX,
@@ -624,7 +656,7 @@ typedef enum
  * `SDL_CONTROLLER_AXIS_TRIGGERRIGHT` and `SDL_CONTROLLER_AXIS_TRIGGERLEFT`,
  * respectively.
  *
- * \param str string representing a SDL_GameController axis
+ * \param str string representing a SDL_GameController axis.
  * \returns the SDL_GameControllerAxis enum corresponding to the input string,
  *          or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
  *
@@ -639,7 +671,7 @@ extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromStri
  *
  * The caller should not SDL_free() the returned string.
  *
- * \param axis an enum value for a given SDL_GameControllerAxis
+ * \param axis an enum value for a given SDL_GameControllerAxis.
  * \returns a string for the given axis, or NULL if an invalid axis is
  *          specified. The string returned is of the format used by
  *          SDL_GameController mapping strings.
@@ -653,8 +685,8 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameC
 /**
  * Get the SDL joystick layer binding for a controller axis mapping.
  *
- * \param gamecontroller a game controller
- * \param axis an axis enum value (one of the SDL_GameControllerAxis values)
+ * \param gamecontroller a game controller.
+ * \param axis an axis enum value (one of the SDL_GameControllerAxis values).
  * \returns a SDL_GameControllerButtonBind describing the bind. On failure
  *          (like the given Controller axis doesn't exist on the device), its
  *          `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
@@ -673,8 +705,8 @@ SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller,
  * This merely reports whether the controller's mapping defined this axis, as
  * that is all the information SDL has about the physical device.
  *
- * \param gamecontroller a game controller
- * \param axis an axis enum value (an SDL_GameControllerAxis value)
+ * \param gamecontroller a game controller.
+ * \param axis an axis enum value (an SDL_GameControllerAxis value).
  * \returns SDL_TRUE if the controller has this axis, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 2.0.14.
@@ -687,11 +719,15 @@ SDL_GameControllerHasAxis(SDL_GameController *gamecontroller, SDL_GameController
  *
  * The axis indices start at index 0.
  *
- * The state is a value ranging from -32768 to 32767. Triggers, however, range
- * from 0 to 32767 (they never return a negative value).
+ * For thumbsticks, the state is a value ranging from -32768 (up/left) to
+ * 32767 (down/right).
  *
- * \param gamecontroller a game controller
- * \param axis an axis index (one of the SDL_GameControllerAxis values)
+ * Triggers range from 0 when released to 32767 when fully pressed, and never
+ * return a negative value. Note that this differs from the value reported by
+ * the lower-level SDL_JoystickGetAxis(), which normally uses the full range.
+ *
+ * \param gamecontroller a game controller.
+ * \param axis an axis index (one of the SDL_GameControllerAxis values).
  * \returns axis state (including 0) on success or 0 (also) on failure; call
  *          SDL_GetError() for more information.
  *
@@ -703,9 +739,9 @@ extern DECLSPEC Sint16 SDLCALL
 SDL_GameControllerGetAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
 
 /**
- *  The list of buttons available from a controller
+ * The list of buttons available from a controller
  */
-typedef enum
+typedef enum SDL_GameControllerButton
 {
     SDL_CONTROLLER_BUTTON_INVALID = -1,
     SDL_CONTROLLER_BUTTON_A,
@@ -740,7 +776,7 @@ typedef enum
  * SDL_GameController mapping. You do not normally need to call this function
  * unless you are parsing SDL_GameController mappings in your own code.
  *
- * \param str string representing a SDL_GameController axis
+ * \param str string representing a SDL_GameController axis.
  * \returns the SDL_GameControllerButton enum corresponding to the input
  *          string, or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
  *
@@ -753,7 +789,7 @@ extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFrom
  *
  * The caller should not SDL_free() the returned string.
  *
- * \param button an enum value for a given SDL_GameControllerButton
+ * \param button an enum value for a given SDL_GameControllerButton.
  * \returns a string for the given button, or NULL if an invalid button is
  *          specified. The string returned is of the format used by
  *          SDL_GameController mapping strings.
@@ -767,8 +803,8 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_Gam
 /**
  * Get the SDL joystick layer binding for a controller button mapping.
  *
- * \param gamecontroller a game controller
- * \param button an button enum value (an SDL_GameControllerButton value)
+ * \param gamecontroller a game controller.
+ * \param button an button enum value (an SDL_GameControllerButton value).
  * \returns a SDL_GameControllerButtonBind describing the bind. On failure
  *          (like the given Controller button doesn't exist on the device),
  *          its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
@@ -787,8 +823,8 @@ SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller,
  * This merely reports whether the controller's mapping defined this button,
  * as that is all the information SDL has about the physical device.
  *
- * \param gamecontroller a game controller
- * \param button a button enum value (an SDL_GameControllerButton value)
+ * \param gamecontroller a game controller.
+ * \param button a button enum value (an SDL_GameControllerButton value).
  * \returns SDL_TRUE if the controller has this button, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 2.0.14.
@@ -799,8 +835,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasButton(SDL_GameController
 /**
  * Get the current state of a button on a game controller.
  *
- * \param gamecontroller a game controller
- * \param button a button index (one of the SDL_GameControllerButton values)
+ * \param gamecontroller a game controller.
+ * \param button a button index (one of the SDL_GameControllerButton values).
  * \returns 1 for pressed state or 0 for not pressed state or error; call
  *          SDL_GetError() for more information.
  *
@@ -836,8 +872,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameControll
 /**
  * Return whether a game controller has a particular sensor.
  *
- * \param gamecontroller The controller to query
- * \param type The type of sensor to query
+ * \param gamecontroller The controller to query.
+ * \param type The type of sensor to query.
  * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 2.0.14.
@@ -847,9 +883,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController
 /**
  * Set whether data reporting for a game controller sensor is enabled.
  *
- * \param gamecontroller The controller to update
- * \param type The type of sensor to enable/disable
- * \param enabled Whether data reporting should be enabled
+ * \param gamecontroller The controller to update.
+ * \param type The type of sensor to enable/disable.
+ * \param enabled Whether data reporting should be enabled.
  * \returns 0 or -1 if an error occurred.
  *
  * \since This function is available since SDL 2.0.14.
@@ -859,8 +895,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameControlle
 /**
  * Query whether sensor data reporting is enabled for a game controller.
  *
- * \param gamecontroller The controller to query
- * \param type The type of sensor to query
+ * \param gamecontroller The controller to query.
+ * \param type The type of sensor to query.
  * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 2.0.14.
@@ -871,8 +907,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameContr
  * Get the data rate (number of events per second) of a game controller
  * sensor.
  *
- * \param gamecontroller The controller to query
- * \param type The type of sensor to query
+ * \param gamecontroller The controller to query.
+ * \param type The type of sensor to query.
  * \return the data rate, or 0.0f if the data rate is not available.
  *
  * \since This function is available since SDL 2.0.16.
@@ -885,10 +921,10 @@ extern DECLSPEC float SDLCALL SDL_GameControllerGetSensorDataRate(SDL_GameContro
  * The number of values and interpretation of the data is sensor dependent.
  * See SDL_sensor.h for the details for each type of sensor.
  *
- * \param gamecontroller The controller to query
- * \param type The type of sensor to query
- * \param data A pointer filled with the current sensor state
- * \param num_values The number of values to write to data
+ * \param gamecontroller The controller to query.
+ * \param type The type of sensor to query.
+ * \param data A pointer filled with the current sensor state.
+ * \param num_values The number of values to write to data.
  * \return 0 or -1 if an error occurred.
  *
  * \since This function is available since SDL 2.0.14.
@@ -902,12 +938,12 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorData(SDL_GameController *
  * The number of values and interpretation of the data is sensor dependent.
  * See SDL_sensor.h for the details for each type of sensor.
  *
- * \param gamecontroller The controller to query
- * \param type The type of sensor to query
+ * \param gamecontroller The controller to query.
+ * \param type The type of sensor to query.
  * \param timestamp A pointer filled with the timestamp in microseconds of the
- *                  current sensor reading if available, or 0 if not
- * \param data A pointer filled with the current sensor state
- * \param num_values The number of values to write to data
+ *                  current sensor reading if available, or 0 if not.
+ * \param data A pointer filled with the current sensor state.
+ * \param num_values The number of values to write to data.
  * \return 0 or -1 if an error occurred.
  *
  * \since This function is available since SDL 2.26.0.
@@ -920,13 +956,13 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorDataWithTimestamp(SDL_Gam
  * Each call to this function cancels any previous rumble effect, and calling
  * it with 0 intensity stops any rumbling.
  *
- * \param gamecontroller The controller to vibrate
+ * \param gamecontroller The controller to vibrate.
  * \param low_frequency_rumble The intensity of the low frequency (left)
- *                             rumble motor, from 0 to 0xFFFF
+ *                             rumble motor, from 0 to 0xFFFF.
  * \param high_frequency_rumble The intensity of the high frequency (right)
- *                              rumble motor, from 0 to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
- * \returns 0, or -1 if rumble isn't supported on this controller
+ *                              rumble motor, from 0 to 0xFFFF.
+ * \param duration_ms The duration of the rumble effect, in milliseconds.
+ * \returns 0, or -1 if rumble isn't supported on this controller.
  *
  * \since This function is available since SDL 2.0.9.
  *
@@ -945,13 +981,13 @@ extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecon
  * want the (more common) whole-controller rumble, use
  * SDL_GameControllerRumble() instead.
  *
- * \param gamecontroller The controller to vibrate
+ * \param gamecontroller The controller to vibrate.
  * \param left_rumble The intensity of the left trigger rumble motor, from 0
- *                    to 0xFFFF
+ *                    to 0xFFFF.
  * \param right_rumble The intensity of the right trigger rumble motor, from 0
- *                     to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
- * \returns 0, or -1 if trigger rumble isn't supported on this controller
+ *                     to 0xFFFF.
+ * \param duration_ms The duration of the rumble effect, in milliseconds.
+ * \returns 0, or -1 if trigger rumble isn't supported on this controller.
  *
  * \since This function is available since SDL 2.0.14.
  *
@@ -962,9 +998,9 @@ extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController
 /**
  * Query whether a game controller has an LED.
  *
- * \param gamecontroller The controller to query
+ * \param gamecontroller The controller to query.
  * \returns SDL_TRUE, or SDL_FALSE if this controller does not have a
- *          modifiable LED
+ *          modifiable LED.
  *
  * \since This function is available since SDL 2.0.14.
  */
@@ -973,9 +1009,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasLED(SDL_GameController *ga
 /**
  * Query whether a game controller has rumble support.
  *
- * \param gamecontroller The controller to query
+ * \param gamecontroller The controller to query.
  * \returns SDL_TRUE, or SDL_FALSE if this controller does not have rumble
- *          support
+ *          support.
  *
  * \since This function is available since SDL 2.0.18.
  *
@@ -986,9 +1022,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumble(SDL_GameController
 /**
  * Query whether a game controller has rumble support on triggers.
  *
- * \param gamecontroller The controller to query
+ * \param gamecontroller The controller to query.
  * \returns SDL_TRUE, or SDL_FALSE if this controller does not have trigger
- *          rumble support
+ *          rumble support.
  *
  * \since This function is available since SDL 2.0.18.
  *
@@ -999,11 +1035,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumbleTriggers(SDL_GameCon
 /**
  * Update a game controller's LED color.
  *
- * \param gamecontroller The controller to update
- * \param red The intensity of the red LED
- * \param green The intensity of the green LED
- * \param blue The intensity of the blue LED
- * \returns 0, or -1 if this controller does not have a modifiable LED
+ * \param gamecontroller The controller to update.
+ * \param red The intensity of the red LED.
+ * \param green The intensity of the green LED.
+ * \param blue The intensity of the blue LED.
+ * \returns 0, or -1 if this controller does not have a modifiable LED.
  *
  * \since This function is available since SDL 2.0.14.
  */
@@ -1012,11 +1048,11 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecon
 /**
  * Send a controller specific effect packet
  *
- * \param gamecontroller The controller to affect
- * \param data The data to send to the controller
- * \param size The size of the data to send to the controller
+ * \param gamecontroller The controller to affect.
+ * \param data The data to send to the controller.
+ * \param size The size of the data to send to the controller.
  * \returns 0, or -1 if this controller or driver doesn't support effect
- *          packets
+ *          packets.
  *
  * \since This function is available since SDL 2.0.16.
  */
@@ -1026,7 +1062,7 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSendEffect(SDL_GameController *gam
  * Close a game controller previously opened with SDL_GameControllerOpen().
  *
  * \param gamecontroller a game controller identifier previously returned by
- *                       SDL_GameControllerOpen()
+ *                       SDL_GameControllerOpen().
  *
  * \since This function is available since SDL 2.0.0.
  *
@@ -1038,9 +1074,9 @@ extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecon
  * Return the sfSymbolsName for a given button on a game controller on Apple
  * platforms.
  *
- * \param gamecontroller the controller to query
- * \param button a button on the game controller
- * \returns the sfSymbolsName or NULL if the name can't be found
+ * \param gamecontroller the controller to query.
+ * \param button a button on the game controller.
+ * \returns the sfSymbolsName or NULL if the name can't be found.
  *
  * \since This function is available since SDL 2.0.18.
  *
@@ -1052,9 +1088,9 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetAppleSFSymbolsNameForBu
  * Return the sfSymbolsName for a given axis on a game controller on Apple
  * platforms.
  *
- * \param gamecontroller the controller to query
- * \param axis an axis on the game controller
- * \returns the sfSymbolsName or NULL if the name can't be found
+ * \param gamecontroller the controller to query.
+ * \param axis an axis on the game controller.
+ * \returns the sfSymbolsName or NULL if the name can't be found.
  *
  * \since This function is available since SDL 2.0.18.
  *