documentation: add some basic documentation accross the headers

Signed-off-by: Amir Hammad <amir.hammad@hotmail.com>

include/driver/usbh_device_driver.h

@@ -56,20 +56,49 @@ enum USBH_POLL_STATUS {
 	USBH_POLL_STATUS_DEVICE_DISCONNECTED
 };
 
+/**
+ * @brief The _usbh_device struct
+ *
+ * This represents exactly one connected device.
+ */
 struct _usbh_device {
+	/// max packet size for control endpoint(0)
 	uint16_t packet_size_max0;
+
+	/// Device's address
 	int8_t address;
-	enum USBH_SPEED speed;		// (USBH_SPEED_*)
-	uint8_t state; // for enumeration purposes
+
+	/// @see USBH_SPEED
+	enum USBH_SPEED speed;
+
+	/// state used for enumeration purposes
+	uint8_t state;
+
+	/// toggle bit
 	uint8_t toggle0;
+
+	/**
+	 * @brief drv - device driver used for this connected device
+	 */
+
 	const usbh_dev_driver_t *drv;
+	/**
+	 * @brief drvdata - device driver's private data
+	 */
 	void *drvdata;
+
+	/**
+	 * @brief lld - pointer to a low-level driver's instance
+	 */
 	const void *lld;
 };
 typedef struct _usbh_device usbh_device_t;
 
 struct _usbh_packet_callback_data {
+	/// status - it is used for reporting of the errors
 	enum USBH_PACKET_CALLBACK_STATUS status;
+
+	/// count of bytes that has been actually transferred
 	uint32_t transferred_length;
 };
 typedef struct _usbh_packet_callback_data usbh_packet_callback_data_t;
@@ -77,27 +106,76 @@ typedef struct _usbh_packet_callback_data usbh_packet_callback_data_t;
 typedef void (*usbh_packet_callback_t)(usbh_device_t *dev, usbh_packet_callback_data_t status);
 
 struct _usbh_packet {
-	void *data;		// Pointer to data
-	uint16_t datalen;	// Data length 0..1023
-	int8_t address;	// Device address
-	uint8_t endpoint_type;		// Endpoint type (see USBH_EPTYP_*)
-	uint8_t endpoint_address;		// Endpoint number 0..15
-	uint16_t endpoint_size_max;	// Max packet size for an endpoint
-	enum USBH_SPEED speed;		// (USBH_SPEED_*)
+	/// pointer to data
+	void *data;
+
+	/// length of the data (up to 1023)
+	uint16_t datalen;
+
+	/// Device's address
+	int8_t address;
+
+	/// Endpoint type (see USBH_ENDPOINT_TYPE_*)
+	uint8_t endpoint_type;
+
+	/// Endpoint number 0..15
+	uint8_t endpoint_address;
+
+	/// Max packet size for an endpoint
+	uint16_t endpoint_size_max;
+
+	/// @see USBH_SPEED
+	enum USBH_SPEED speed;
 	uint8_t *toggle;
+
+	/**
+	 * @brief callback this will be called when the packet is finished - either successfuly or not.
+	 */
 	usbh_packet_callback_t callback;
+
+	/**
+	 * @brief callback_arg argument passed into callback
+	 *
+	 * Low level driver is not allowed to alter the data pointed by callback_arg
+	 */
 	void *callback_arg;
 };
 typedef struct _usbh_packet usbh_packet_t;
 
 struct _usbh_driver {
+	/**
+	 * @brief init initialization routine of the low-level driver
+	 *
+	 *
+	 * This function is called during the initialization of the library(@see usbh_init())
+	 */
 	void (*init)(void *drvdata);
+
+	/**
+	 * write - perform a write to a device (@see usbh_packet_t)
+	 */
 	void (*write)(void *drvdata, const usbh_packet_t *packet);
+
+	/**
+	 * @brief read - perform a read from a device (@see usbh_packet_t)
+	 */
 	void (*read)(void *drvdata, usbh_packet_t *packet);
+
+	/**
+	 * @brief this is called as a part of @ref usbh_poll() routine
+	 */
 	enum USBH_POLL_STATUS (*poll)(void *drvdata, uint32_t time_curr_us);
 
-	// Pointer to Low-level driver data
+	/**
+	 * @brief speed of the low-level bus
+	 */
 	enum USBH_SPEED (*root_speed)(void *drvdata);
+
+	/**
+	 * @brief Pointer to Low-level driver data
+	 *
+	 * Data pointed by this pointer should not be altered by the logic other from low-level driver's logic
+	 */
 	void *driver_data;
 };
 typedef struct _usbh_driver usbh_driver_t;

include/usbh_driver_ac_midi.h

@@ -36,9 +36,24 @@ struct _midi_config {
 };
 typedef struct _midi_config midi_config_t;
 
-typedef void (*midi_write_callback_t)(uint8_t);
+/**
+ * @param bytes_written count of bytes that were actually written
+ */
+typedef void (*midi_write_callback_t)(uint8_t bytes_written);
 
+/**
+ * @brief midi_driver_init initialization routine - this will initialize internal structures of this device driver
+ * @param config
+ */
 void midi_driver_init(const midi_config_t *config);
+
+/**
+ * @brief usbh_midi_write
+ * @param device_id
+ * @param data
+ * @param length
+ * @param callback this is called when the write call finishes
+ */
 void usbh_midi_write(uint8_t device_id, const void *data, uint32_t length, midi_write_callback_t callback);
 
 extern const usbh_dev_driver_t usbh_midi_driver;

include/usbh_driver_gp_xbox.h

@@ -64,6 +64,11 @@ struct _gp_xbox_config {
 };
 typedef struct _gp_xbox_config gp_xbox_config_t;
 
+
+/**
+ * @brief gp_xbox_driver_init initialization routine - this will initialize internal structures of this device driver
+ * @param config
+ */
 void gp_xbox_driver_init(const gp_xbox_config_t *config);
 
 extern const usbh_dev_driver_t usbh_gp_xbox_driver;

include/usbh_driver_hid_mouse.h

@@ -30,10 +30,19 @@
 BEGIN_DECLS
 
 struct _hid_mouse_config {
+	/**
+	 * @brief this is called when some data is read when polling the device
+	 * @param device_id
+	 * @param data pointer to the data (only 4 bytes are valid!)
+	 */
 	void (*mouse_in_message_handler)(uint8_t device_id, const uint8_t *data);
 };
 typedef struct _hid_mouse_config hid_mouse_config_t;
 
+/**
+ * @brief hid_mouse_driver_init initialization routine - this will initialize internal structures of this device driver
+ * @param config
+ */
 void hid_mouse_driver_init(const hid_mouse_config_t *config);
 
 extern const usbh_dev_driver_t usbh_hid_mouse_driver;

include/usbh_driver_hub.h

@@ -27,6 +27,9 @@
 
 BEGIN_DECLS
 
+/**
+ * @brief hub_driver_init initialization routine - this will initialize internal structures of this device driver
+ */
 void hub_driver_init(void);
 
 extern const usbh_dev_driver_t usbh_hub_driver;

include/usbh_hubbed.h

@@ -40,7 +40,7 @@
 
 BEGIN_DECLS
 
-// set to -1 to unused items
+/// set to -1 for unused items ("don't care" functionality) @see find_driver()
 struct _usbh_dev_driver_info {
 	int32_t deviceClass;
 	int32_t deviceSubClass;
@@ -54,22 +54,63 @@ struct _usbh_dev_driver_info {
 typedef struct _usbh_dev_driver_info usbh_dev_driver_info_t;
 
 struct _usbh_dev_driver {
+	/**
+	 * @brief init is initialization routine of the device driver
+	 *
+	 * This function is called during the initialization of the device driver
+	 */
 	void *(*init)(void *usbh_dev);
-	bool (*analyze_descriptor)(void *drv, void *descriptor);
+
+	/**
+	 * @brief analyze descriptor
+	 * @param[in/out] drvdata is the device driver's private data
+	 * @param[in] descriptor is the pointer to the descriptor that should
+	 *		be parsed in order to prepare driver to be loaded
+	 *
+	 * @retval true when the enumeration is complete and the driver is ready to be used
+	 * @retval false when the device driver is not ready to be used
+	 *
+	 * This should be used for getting correct endpoint numbers, getting maximum sizes of endpoints.
+	 * Should return true, when no more data is needed.
+	 *
+	 */
+	bool (*analyze_descriptor)(void *drvdata, void *descriptor);
+
+	/**
+	 * @brief poll method is called periodically by the library core (@see usbh_poll())
+	 * @param[in/out] drvdata is the device driver's private data
+	 * @param[in] time_curr_us current timestamp in microseconds
+	 */
 	void (*poll)(void *drvdata, uint32_t time_curr_us);
+
+	/**
+	 * @brief unloads the device driver
+	 * @param[in/out] drvdata is the device driver's private data
+	 *
+	 * This should free any data associated with this device
+	 */
 	void (*remove)(void *drvdata);
+
+	/**
+	 * @brief info - compatibility information about the driver. It is used by the core during device enumeration (@see find_driver())
+	 */
 	const usbh_dev_driver_info_t * const info;
 };
 typedef struct _usbh_dev_driver usbh_dev_driver_t;
 
-void usbh_init(const void *drivers[], const usbh_dev_driver_t * const device_drivers[]);
+/**
+ * @brief usbh_init
+ * @param low_level_drivers list of the low level drivers to be used by this library
+ * @param device_drivers list of the device drivers that could be used with attached devices
+ */
+void usbh_init(const void *low_level_drivers[], const usbh_dev_driver_t * const device_drivers[]);
 
 /**
- * \brief usbh_poll
- * \param time_curr_us - use monotically rising time
+ * @brief usbh_poll
+ * @param time_curr_us - use monotically rising time
  *
  *	time_curr_us:
- *		* can overflow, in time of this writing, after 1s)
+ *		* can overflow, in time of this writing, after 1s
  *		* unit is microseconds
  */
 void usbh_poll(uint32_t time_curr_us);

src/usbh_hubbed.c

@@ -163,13 +163,13 @@ static void device_register(void *descriptors, uint16_t descriptors_len, usbh_de
 	LOG_PRINTF("Device NOT Initialized\n");
 }
 
-void usbh_init(const void *drivers_lld[], const usbh_dev_driver_t * const device_drivers[])
+void usbh_init(const void *low_level_drivers[], const usbh_dev_driver_t * const device_drivers[])
 {
-	if (!drivers_lld) {
+	if (!low_level_drivers) {
 		return;
 	}
 
-	usbh_data.lld_drivers = (const usbh_driver_t **)drivers_lld;
+	usbh_data.lld_drivers = (const usbh_driver_t **)low_level_drivers;
 	usbh_data.dev_drivers = device_drivers;
 
 	// TODO: init structures