add some doxygen

1 files changed, 44 insertions, 1 deletions

diff --git a/tinyusb/class/cdc_device.h b/tinyusb/class/cdc_device.h
index 601b29cca..dd4fd5e6d 100644
--- a/tinyusb/class/cdc_device.h
+++ b/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);