From e707c401c86839e1b7df0c485f95e24ebd8b78ad Mon Sep 17 00:00:00 2001
From: twinaphex <libretro@gmail.com>
Date: Sat, 10 Jan 2015 20:48:26 +0100
Subject: [PATCH] More documentation for input/input_joypad.c

---
 input/input_joypad.c | 30 +++++++++++++++++++++++++++++
 input/input_joypad.h | 46 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+)

diff --git a/input/input_joypad.c b/input/input_joypad.c
index 10fbd4d510..ae8f1081e4 100644
--- a/input/input_joypad.c
+++ b/input/input_joypad.c
@@ -41,6 +41,17 @@ const char *input_joypad_name(const rarch_joypad_driver_t *drv,
    return drv->name(port);
 }
 
+/**
+ * input_joypad_set_rumble:
+ * @drv                     : Joypad driver handle.
+ * @port                    : User number.
+ * @effect                  : Rumble effect to set.
+ * @strength                : Strength of rumble effect.
+ *
+ * Sets rumble effect @effect with strength @strength.
+ *
+ * Returns: true (1) if successful, otherwise false (0).
+ **/
 bool input_joypad_set_rumble(const rarch_joypad_driver_t *drv,
       unsigned port, enum retro_rumble_effect effect, uint16_t strength)
 {
@@ -125,6 +136,25 @@ bool input_joypad_pressed(const rarch_joypad_driver_t *drv,
    return true;
 }
 
+/**
+ * input_joypad_analog:
+ * @drv                     : Joypad driver handle.
+ * @port                    : User number.
+ * @idx                     : Analog key index.
+ *                            E.g.: 
+ *                            - RETRO_DEVICE_INDEX_ANALOG_LEFT
+ *                            - RETRO_DEVICE_INDEX_ANALOG_RIGHT
+ * @ident                   : Analog key identifier.
+ *                            E.g.:
+ *                            - RETRO_DEVICE_ID_ANALOG_X
+ *                            - RETRO_DEVICE_ID_ANALOG_Y
+ * @binds                   : Binds of user.
+ *
+ * Gets analog value of analog key identifiers @idx and @ident
+ * from user with number @port with provided keybinds (@binds).
+ *
+ * Returns: analog value on success, otherwise 0.
+ **/
 int16_t input_joypad_analog(const rarch_joypad_driver_t *drv,
       unsigned port, unsigned idx, unsigned ident,
       const struct retro_keybind *binds)
diff --git a/input/input_joypad.h b/input/input_joypad.h
index b696c636e6..f2d670c9f3 100644
--- a/input/input_joypad.h
+++ b/input/input_joypad.h
@@ -24,6 +24,22 @@ extern "C" {
 #include <stdint.h>
 #include "../driver.h"
 
+/**
+ * input_conv_analog_id_to_bind_id:
+ * @idx                     : Analog key index.
+ *                            E.g.: 
+ *                            - RETRO_DEVICE_INDEX_ANALOG_LEFT
+ *                            - RETRO_DEVICE_INDEX_ANALOG_RIGHT
+ * @ident                   : Analog key identifier.
+ *                            E.g.:
+ *                            - RETRO_DEVICE_ID_ANALOG_X
+ *                            - RETRO_DEVICE_ID_ANALOG_Y
+ * @ident_minus             : Bind ID minus, will be set by function.
+ * @ident_plus              : Bind ID plus,  will be set by function.
+ *
+ * Takes as input analog key identifiers and converts
+ * them to corresponding bind IDs @ident_minus and @ident_plus.
+ **/
 static inline void input_conv_analog_id_to_bind_id(unsigned idx, unsigned ident,
       unsigned *ident_minus, unsigned *ident_plus)
 {
@@ -67,10 +83,40 @@ static inline void input_conv_analog_id_to_bind_id(unsigned idx, unsigned ident,
 bool input_joypad_pressed(const rarch_joypad_driver_t *driver,
       unsigned port, const struct retro_keybind *binds, unsigned key);
 
+/**
+ * input_joypad_analog:
+ * @drv                     : Joypad driver handle.
+ * @port                    : User number.
+ * @idx                     : Analog key index.
+ *                            E.g.: 
+ *                            - RETRO_DEVICE_INDEX_ANALOG_LEFT
+ *                            - RETRO_DEVICE_INDEX_ANALOG_RIGHT
+ * @ident                   : Analog key identifier.
+ *                            E.g.:
+ *                            - RETRO_DEVICE_ID_ANALOG_X
+ *                            - RETRO_DEVICE_ID_ANALOG_Y
+ * @binds                   : Binds of user.
+ *
+ * Gets analog value of analog key identifiers @idx and @ident
+ * from user with number @port with provided keybinds (@binds).
+ *
+ * Returns: analog value on success, otherwise 0.
+ **/
 int16_t input_joypad_analog(const rarch_joypad_driver_t *driver,
       unsigned port, unsigned idx, unsigned ident,
       const struct retro_keybind *binds);
 
+/**
+ * input_joypad_set_rumble:
+ * @drv                     : Joypad driver handle.
+ * @port                    : User number.
+ * @effect                  : Rumble effect to set.
+ * @strength                : Strength of rumble effect.
+ *
+ * Sets rumble effect @effect with strength @strength.
+ *
+ * Returns: true (1) if successful, otherwise false (0).
+ **/
 bool input_joypad_set_rumble(const rarch_joypad_driver_t *driver,
       unsigned port, enum retro_rumble_effect effect, uint16_t strength);