documentation: add some basic documentation accross the headers

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

7 files changed, 171 insertions, 20 deletions

diff --git a/include/driver/usbh_device_driver.h b/include/driver/usbh_device_driver.h
index 3a4fbe3..2839a17 100644
--- a/include/driver/usbh_device_driver.h
+++ b/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;
diff --git a/include/usbh_driver_ac_midi.h b/include/usbh_driver_ac_midi.h
index 7b006a9..0993589 100644
--- a/include/usbh_driver_ac_midi.h
+++ b/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;
diff --git a/include/usbh_driver_gp_xbox.h b/include/usbh_driver_gp_xbox.h
index 8080f30..90d0ca1 100644
--- a/include/usbh_driver_gp_xbox.h
+++ b/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;
diff --git a/include/usbh_driver_hid_mouse.h b/include/usbh_driver_hid_mouse.h
index c12fed4..de7707c 100644
--- a/include/usbh_driver_hid_mouse.h
+++ b/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;
diff --git a/include/usbh_driver_hub.h b/include/usbh_driver_hub.h
index cda1463..8555f79 100644
--- a/include/usbh_driver_hub.h
+++ b/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;

diff --git a/include/usbh_hubbed.h b/include/usbh_hubbed.h
index f99108d..ca4a489 100644
--- a/include/usbh_hubbed.h
+++ b/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);

diff --git a/src/usbh_hubbed.c b/src/usbh_hubbed.c
index b631263..7ffc83d 100644
--- a/src/usbh_hubbed.c
+++ b/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