--- a/libmlk-core/mlk/core/gamepad.h	Sat Mar 04 16:47:54 2023 +0100
+++ b/libmlk-core/mlk/core/gamepad.h	Sat Mar 04 17:12:14 2023 +0100
@@ -19,61 +19,233 @@
 #ifndef MLK_CORE_GAMEPAD_H
 #define MLK_CORE_GAMEPAD_H
 
+/**
+ * \file mlk/core/gamepad.h
+ * \brief Game controller support
+ *
+ * This module abstract the gamepad support using a predefined gamepad layout
+ * similar to the XBox 360 controller.
+ *
+ * Once a gamepad is opened, it will automatically generate events depending on
+ * the device.
+ */
+
+/**
+ * \enum mlk_gamepad_button
+ * \brief Describe a gamepad button
+ */
 enum mlk_gamepad_button {
+	/**
+	 * Unknown button.
+	 */
 	MLK_GAMEPAD_BUTTON_UNKNOWN,
+
+	/**
+	 * Button A.
+	 */
 	MLK_GAMEPAD_BUTTON_A,
+
+	/**
+	 * Button B.
+	 */
 	MLK_GAMEPAD_BUTTON_B,
+
+	/**
+	 * Button X.
+	 */
 	MLK_GAMEPAD_BUTTON_X,
+
+	/**
+	 * Button Y.
+	 */
 	MLK_GAMEPAD_BUTTON_Y,
+
+	/**
+	 * Button back/select depending on the gamepad.
+	 */
 	MLK_GAMEPAD_BUTTON_BACK,
+
+	/**
+	 * Button logo/brand or usually in the middle of the gamepad.
+	 */
 	MLK_GAMEPAD_BUTTON_LOGO,
+
+	/**
+	 * Button start.
+	 */
 	MLK_GAMEPAD_BUTTON_START,
+
+	/**
+	 * Left thumb click.
+	 */
 	MLK_GAMEPAD_BUTTON_LTHUMB,
+
+	/**
+	 * Right thumb click.
+	 */
 	MLK_GAMEPAD_BUTTON_RTHUMB,
+
+	/**
+	 * Left shoulder.
+	 */
 	MLK_GAMEPAD_BUTTON_LSHOULDER,
+
+	/**
+	 * Right shoulder.
+	 */
 	MLK_GAMEPAD_BUTTON_RSHOULDER,
+
+	/**
+	 * D-Pad up.
+	 */
 	MLK_GAMEPAD_BUTTON_UP,
+
+	/**
+	 * D-Pad down.
+	 */
 	MLK_GAMEPAD_BUTTON_DOWN,
+
+	/**
+	 * D-Pad left.
+	 */
 	MLK_GAMEPAD_BUTTON_LEFT,
+
+	/**
+	 * D-Pad right.
+	 */
 	MLK_GAMEPAD_BUTTON_RIGHT
 };
 
+/**
+ * \enum mlk_gamepad_axis
+ * \brief Describe a joystick axis.
+ */
 enum mlk_gamepad_axis {
+	/**
+	 * Unknown axis.
+	 */
 	MLK_GAMEPAD_AXIS_UNKNOWN,
+
+	/**
+	 * Left thumb horizontal axis.
+	 */
 	MLK_GAMEPAD_AXIS_LX,
+
+	/**
+	 * Left thumb vertical axis.
+	 */
 	MLK_GAMEPAD_AXIS_LY,
+
+	/**
+	 * Right thumb horizontal axis.
+	 */
 	MLK_GAMEPAD_AXIS_RX,
+
+	/**
+	 * Right thumb vertical axis.
+	 */
 	MLK_GAMEPAD_AXIS_RY,
+
+	/**
+	 * Left shoulder axis.
+	 */
 	MLK_GAMEPAD_AXIS_LTRIGGER,
+
+	/**
+	 * Right shoulder axis.
+	 */
 	MLK_GAMEPAD_AXIS_RTRIGGER
 };
 
+/**
+ * \struct mlk_gamepad
+ * \brief Gamepad structure
+ */
 struct mlk_gamepad {
+	/**
+	 * (read-only, borrowed)
+	 *
+	 * Gamepad name.
+	 */
 	const char *name;
+
+	/** \cond MLK_PRIVATE_DECLS */
 	void *handle;
+	/** \endcond MLK_PRIVATE_DECLS */
 };
 
+/**
+ * \struct mlk_gamepad_iter
+ * \brief Iterate over all plugged gamepads.
+ */
 struct mlk_gamepad_iter {
+	/**
+	 * (read-only, borrowed)
+	 *
+	 * Gamepad name.
+	 */
 	const char *name;
-	int idx;
+
+	/**
+	 * (read-only)
+	 *
+	 * Device index on the system, can be used to open a device using
+	 * ::mlk_gamepad_open.
+	 */
+	int index;
+
+	/** \cond MLK_PRIVATE_DECLS */
 	int end;
+	/** \endcond MLK_PRIVATE_DECLS */
 };
 
 #if defined(__cplusplus)
 extern "C" {
 #endif
 
+/**
+ * Open the gamepad at the given device index.
+ *
+ * \pre pad != NULL
+ * \param pad the gamepad to initialize
+ * \param index the device index
+ * \return 0 on success or any error code instead
+ */
 int
-mlk_gamepad_open(struct mlk_gamepad *pad, int idx);
+mlk_gamepad_open(struct mlk_gamepad *pad, int index);
 
+/**
+ * Close this gamepad.
+ *
+ * \pre pad != NULL
+ * \param pad the gamepad
+ */
 void
 mlk_gamepad_finish(struct mlk_gamepad *pad);
 
+/**
+ * Start iterating gamepad devices.
+ *
+ * On success, call ::mlk_gamepad_iter_next to retrieve the next device
+ * (including the first one) in a loop.
+ *
+ * \pre iter the iter to start
+ * \return 0 on success or any error code instead
+ */
 int
-mlk_gamepad_iter_begin(struct mlk_gamepad_iter *);
+mlk_gamepad_iter_begin(struct mlk_gamepad_iter *iter);
 
+/**
+ * Retrieve the next device.
+ *
+ * This function should be called in a loop to retrieve all devices available
+ * on the system.
+ *
+ * \pre iter the iter to start
+ * \return 1 if there are still devices available
+ */
 int
-mlk_gamepad_iter_next(struct mlk_gamepad_iter *);
+mlk_gamepad_iter_next(struct mlk_gamepad_iter *iter);
 
 #if defined(__cplusplus)
 }