add some doxygen

tinyusb/class/cdc_device.h

@@ -55,10 +55,44 @@
 //--------------------------------------------------------------------+
 // APPLICATION API
 //--------------------------------------------------------------------+
-//bool tusbd_cdc_is_configured(uint8_t coreid);
+/** \brief      Check if the interface is currently busy or not
+ * \param[in]   coreid USB Controller ID
+ * \retval      true if the interface is busy meaning the stack is still transferring/waiting data from/to host
+ * \retval      false if the interface is not busy meaning the stack successfully transferred data from/to host
+ * \note        This function is primarily used for polling/waiting result after \ref tusbd_hid_keyboard_send.
+ */
 bool tusbd_cdc_is_busy(uint8_t coreid, cdc_pipeid_t pipeid)  ATTR_PURE ATTR_WARN_UNUSED_RESULT;
 
+/** \brief        Submit USB transfer
+ * \param[in]		  coreid USB Controller ID
+ * \param[in]     p_data  buffer containing data from application. Must be accessible by USB controller (see \ref TUSB_CFG_ATTR_USBRAM)
+ * \param[in]     length number of bytes in \a p_data.
+ * \param[in]     is_notify indicates whether the hardware completion (data transferred through USB bus) will be notified
+ *                to Application (via \ref tusbd_cdc_xfer_cb)
+ * \returns       \ref tusb_error_t type to indicate success or error condition.
+ * \retval        TUSB_ERROR_NONE on success
+ * \retval        TUSB_ERROR_INTERFACE_IS_BUSY if the interface is busy transferring previous data.
+ * \retval        TUSB_ERROR_DEVICE_NOT_READY if device is not yet configured (by SET CONFIGURED request)
+ * \retval        TUSB_ERROR_INVALID_PARA if input parameters are not correct
+ * \note          This function is non-blocking and returns immediately. Data will be transferred when USB Host work with this interface.
+ *                The result of usb transfer will be reported by the interface's callback function if \a is_notify is true
+ */
 tusb_error_t tusbd_cdc_send(uint8_t coreid, void * p_data, uint32_t length, bool is_notify);
+
+/** \brief        Submit USB transfer
+ * \param[in]		  coreid USB Controller ID
+ * \param[in]     p_buffer  application's buffer to receive data. Must be accessible by USB controller (see \ref TUSB_CFG_ATTR_USBRAM)
+ * \param[in]     length number of bytes in \a p_buffer.
+ * \param[in]     is_notify indicates whether the hardware completion (data transferred through USB bus) will be notified
+ *                to Application (via \ref tusbd_cdc_xfer_cb)
+ * \returns       \ref tusb_error_t type to indicate success or error condition.
+ * \retval        TUSB_ERROR_NONE on success
+ * \retval        TUSB_ERROR_INTERFACE_IS_BUSY if the interface is busy transferring previous data.
+ * \retval        TUSB_ERROR_DEVICE_NOT_READY if device is not yet configured (by SET CONFIGURED request)
+ * \retval        TUSB_ERROR_INVALID_PARA if input parameters are not correct
+ * \note          This function is non-blocking and returns immediately. Data will be transferred when USB Host work with this interface.
+ *                The result of usb transfer will be reported by the interface's callback function if \a is_notify is true
+ */
 tusb_error_t tusbd_cdc_receive(uint8_t coreid, void * p_buffer, uint32_t length, bool is_notify);
 
 //--------------------------------------------------------------------+
@@ -66,6 +100,15 @@ tusb_error_t tusbd_cdc_receive(uint8_t coreid, void * p_buffer, uint32_t length,
 //--------------------------------------------------------------------+
 void tusbd_cdc_mounted_cb(uint8_t coreid);
 void tusbd_cdc_unmounted_cb(uint8_t coreid);
+
+/** \brief      Callback function that is invoked when an completion (error or success) of an USB transfer previously submitted
+ *              by application (e.g \ref tusbd_cdc_send or \ref tusbd_cdc_send) with \a is_notify set to true.
+ * \param[in]		coreid	USB Controller ID
+ * \param[in]   event an value from \ref tusb_event_t
+ * \param[in]   pipe_id indicates which pipe of this interface the event occured.
+ * \param[in]   xferred_bytes is actual number of bytes transferred via USB bus. This value in general can be different to
+ *              the one that previously submitted by application.
+ */
 void tusbd_cdc_xfer_cb(uint8_t coreid, tusb_event_t event, cdc_pipeid_t pipe_id, uint32_t xferred_bytes);
 //void tusbd_cdc_line_coding_changed_cb(uint8_t coreid, cdc_line_coding_t* p_line_coding);
 

tinyusb/class/hid_device.h

@@ -64,7 +64,7 @@
  */
 bool tusbd_hid_keyboard_is_busy(uint8_t coreid);
 
-/** \brief        Perform transfer queuing
+/** \brief        Submit USB transfer
  * \param[in]		  coreid USB Controller ID
  * \param[in,out] p_report address that is used to store data from device. Must be accessible by usb controller (see \ref TUSB_CFG_ATTR_USBRAM)
  * \returns       \ref tusb_error_t type to indicate success or error condition.
@@ -94,9 +94,32 @@ void tusbd_hid_keyboard_unmounted_cb(uint8_t coreid);
  */
 void tusbd_hid_keyboard_cb(uint8_t coreid, tusb_event_t event, uint32_t xferred_bytes);
 
-void tusbd_hid_keyboard_set_report_cb(uint8_t coreid, hid_request_report_type_t report_type, uint8_t p_report_data[], uint16_t length);
+/** \brief      Callback function that is invoked when USB host request \ref HID_REQUEST_CONTROL_GET_REPORT
+ *              via control endpoint.
+ * \param[in]		coreid	USB Controller ID
+ * \param[in]   report_type specify which report (INPUT, OUTPUT, FEATURE) that host requests
+ * \param[out]  pp_report pointer to buffer that application need to update, value must be accessible by USB controller (see \ref TUSB_CFG_ATTR_USBRAM)
+ * \param[in]   requested_length  number of bytes that host requested
+ * \retval      non-zero Actual number of bytes in the response's buffer.
+ * \retval      zero  indicates the current request is not supported. Tinyusb device stack will reject the request by
+ *              sending STALL in the data phase.
+ * \note        After this callback, the request is silently executed by the tinyusb stack, thus
+ *              the completion of this control request will not be reported to application.
+ *              For Keyboard, USB host often uses this to turn on/off the LED for CAPLOCKS, NUMLOCK (\ref hid_keyboard_led_bm_t)
+ */
 uint16_t tusbd_hid_keyboard_get_report_cb(uint8_t coreid, hid_request_report_type_t report_type, void** pp_report, uint16_t requested_length);
 
+/** \brief      Callback function that is invoked when USB host request \ref HID_REQUEST_CONTROL_SET_REPORT
+ *              via control endpoint.
+ * \param[in]		coreid	USB Controller ID
+ * \param[in]   report_type specify which report (INPUT, OUTPUT, FEATURE) that host requests
+ * \param[in]   p_report_data buffer containing the report's data
+ * \param[in]   length  number of bytes in the \a p_report_data
+ * \note        By the time this callback is invoked, the USB control transfer is already completed in the hardware side.
+ *              Application are free to handle data at its own will.
+ */
+void tusbd_hid_keyboard_set_report_cb(uint8_t coreid, hid_request_report_type_t report_type, uint8_t p_report_data[], uint16_t length);
+
 /** @} */
 /** @} */
 
@@ -147,8 +170,31 @@ void tusbd_hid_mouse_unmounted_cb(uint8_t coreid);
  */
 void tusbd_hid_mouse_cb(uint8_t coreid, tusb_event_t event, uint32_t xferred_bytes);
 
+/** \brief      Callback function that is invoked when USB host request \ref HID_REQUEST_CONTROL_GET_REPORT
+ *              via control endpoint.
+ * \param[in]		coreid	USB Controller ID
+ * \param[in]   report_type specify which report (INPUT, OUTPUT, FEATURE) that host requests
+ * \param[out]  pp_report pointer to buffer that application need to update, value must be accessible by USB controller (see \ref TUSB_CFG_ATTR_USBRAM)
+ * \param[in]   requested_length  number of bytes that host requested
+ * \retval      non-zero Actual number of bytes in the response's buffer.
+ * \retval      zero  indicates the current request is not supported. Tinyusb device stack will reject the request by
+ *              sending STALL in the data phase.
+ * \note        After this callback, the request is silently executed by the tinyusb stack, thus
+ *              the completion of this control request will not be reported to application
+ */
 uint16_t tusbd_hid_mouse_get_report_cb(uint8_t coreid, hid_request_report_type_t report_type, void** pp_report, uint16_t requested_length);
+
+/** \brief      Callback function that is invoked when USB host request \ref HID_REQUEST_CONTROL_SET_REPORT
+ *              via control endpoint.
+ * \param[in]		coreid	USB Controller ID
+ * \param[in]   report_type specify which report (INPUT, OUTPUT, FEATURE) that host requests
+ * \param[in]   p_report_data buffer containing the report's data
+ * \param[in]   length  number of bytes in the \a p_report_data
+ * \note        By the time this callback is invoked, the USB control transfer is already completed in the hardware side.
+ *              Application are free to handle data at its own will.
+ */
 void tusbd_hid_mouse_set_report_cb(uint8_t coreid, hid_request_report_type_t report_type, uint8_t p_report_data[], uint16_t length);
+
 /** @} */
 /** @} */