|
|
@@ -0,0 +1,269 @@
|
|
|
+Rules for CMSIS API Funcction documentation
|
|
|
+===========================================
|
|
|
+
|
|
|
+This document describes how to generate Doxygen-style documentation for middlware "Components".
|
|
|
+It explains how the Doxygen documentation under "Reference" is provided in header (*.h),
|
|
|
+text (*.txt), template (*.c), and config files.
|
|
|
+
|
|
|
+Folder structure:
|
|
|
+ .\MW\component\Include *.h files
|
|
|
+ .\MW\component\Template *.c user code templates
|
|
|
+ .\MW\component\Config *.c or *.h config files
|
|
|
+ .\MW\Doc\component *.txt files
|
|
|
+ .\MW\Doc\component\images graphic files used by *.txt files
|
|
|
+
|
|
|
+Files: Middleware components have the following files that are used to generate the API documentation:
|
|
|
+
|
|
|
+ - *.h files: one or more header files which expose data types and functions (the API). Doxygen uses the *.h files
|
|
|
+ that are in .\MW\component\include folder.
|
|
|
+
|
|
|
+ - *.txt files: documentation files that group functions and explain overall the API. Each *.h file should have a *.txt
|
|
|
+ file with the same name, i.e. rl_usb.h => rl_usb.txt; a exception is permitted when a template is used to explain
|
|
|
+ API functions.
|
|
|
+
|
|
|
+ - *.c templates: show the usage of some middleware functionality and may be included in the Doxygen documenation.
|
|
|
+ *.c templates with '%Instance%' are copied to .\MW\Doc\component and '%Instance%' is replaced with 'n', otherwise
|
|
|
+ Doxygen uses the *.c templates in folder .\MW\component\Template. If a template is used in documentation
|
|
|
+ the related *.txt file has the same name as the template, i.e. USBD_User_HID.c => USBD_User_HID.txt.
|
|
|
+
|
|
|
+ - *.c or *.h config files should be self-explaining using <i> tags. config files will not be replicated
|
|
|
+ in Doxygen *.txt files, but the high-level usage will be explained. The impact of parameters to middleware
|
|
|
+ needs therefore be part of the config files.
|
|
|
+
|
|
|
+Source files (*.c and *.h) should NOT use <TAB> character. Instead of <TAB> <space> characters are used.
|
|
|
+
|
|
|
+
|
|
|
+API Documentation in .\Include\*.h files
|
|
|
+----------------------------------------
|
|
|
+
|
|
|
+Example:
|
|
|
+
|
|
|
+The follwoing sniplet shows a sample documentation (correct). In general functions are grouped and
|
|
|
+a short descriptive line is added before a group of functions. In case that functions are only
|
|
|
+relevant for the documentation (i.e. available in muplitiple instances), they are included in
|
|
|
+#ifdef __DOXYGEN__ / #endif sections.
|
|
|
+
|
|
|
+{code}
|
|
|
+/// \brief Called during \ref USBD_Initialize to initialze the USB Device class.
|
|
|
+/// \return none
|
|
|
+extern void USBD_HIDn_Initialize (void);
|
|
|
+
|
|
|
+// ==== USB Host Human Interface Device Functions ====
|
|
|
+
|
|
|
+/// \brief Get status of the Human Interface Device.
|
|
|
+/// \param[in] index instance index of HID.
|
|
|
+/// \return true device is configured and initialized.
|
|
|
+/// \return false device not ready.
|
|
|
+extern bool USBH_HID_GetStatus (uint8_t index);
|
|
|
+
|
|
|
+/// \brief Read data received from Human Interface Device.
|
|
|
+/// \param[in] index instance index of HID.
|
|
|
+/// \param[out] ptr_data data to be read.
|
|
|
+/// \return value >= 0 number of bytes read.
|
|
|
+/// \return value -1 communication error.
|
|
|
+extern int USBH_HID_Read (uint8_t index, uint8_t *ptr_data);
|
|
|
+
|
|
|
+/// \brief Write data to Human Interface Device.
|
|
|
+/// \param[in] index instance index of HID.
|
|
|
+/// \param[in] ptr_data data to be written.
|
|
|
+/// \param[in] data_len number of data bytes to be written.
|
|
|
+/// \return number of bytes written.
|
|
|
+extern int USBH_HID_Write (uint8_t index, uint8_t *ptr_data, uint16_t data_len);
|
|
|
+
|
|
|
+/// \brief Get last error that happened on the Human Interface Device.
|
|
|
+/// \param[in] index instance index of HID.
|
|
|
+/// \return error code.
|
|
|
+extern uint32_t USBH_HID_GetLastError (uint8_t index);
|
|
|
+
|
|
|
+/// \brief Retrieve state change since last call of HID Mouse.
|
|
|
+/// \param[in] index instance index of HID.
|
|
|
+/// \param[out] button pointer to variable that receives button state.
|
|
|
+/// \param[out] x pointer to variable that receives x position change.
|
|
|
+/// \param[out] y pointer to variable that receives y position change.
|
|
|
+/// \param[out] wheel pointer to variable that receives wheel change.
|
|
|
+/// \return true state change since last call.
|
|
|
+/// \return false no state change since last call.
|
|
|
+extern bool USBH_HID_GetMouseData (uint8_t index, uint8_t *button, int8_t *x, int8_t *y, int8_t *wheel);
|
|
|
+
|
|
|
+// ==== USB Device Human Interface Device Functions ====
|
|
|
+
|
|
|
+#ifdef __DOXYGEN__
|
|
|
+// following functions are available for each instance of a HID class.
|
|
|
+// generic prefix USBD_HIDn is USBD_HID0 for HID class instance 0.
|
|
|
+
|
|
|
+/// \brief Prepare HID report data to be sent.
|
|
|
+/// \param[in] rtype Report type
|
|
|
+/// - HID_REPORT_INPUT = Input report requested.
|
|
|
+/// - HID_REPORT_FEATURE = Feature report requested.
|
|
|
+/// \param[in] rid Report ID (0 if only one report exists)
|
|
|
+/// \param[out] buf Buffer for report data to be sent.
|
|
|
+/// \param[in] req Request type
|
|
|
+/// - USBD_HID_REQ_EP_CTRL = Control endpoint request.
|
|
|
+/// - USBD_HID_REQ_PERIOD_UPDATE = Idle period expiration request.
|
|
|
+/// - USBD_HID_REQ_EP_INT = Previously sent report on interrupt endpoint request.
|
|
|
+/// \return value >= 0 number of data bytes prepared
|
|
|
+/// \return value < 0 error code
|
|
|
+int32_t USBD_HIDn_GetReport (uint8_t rtype, uint8_t rid, uint8_t *buf, uint8_t req);
|
|
|
+
|
|
|
+{code}
|
|
|
+
|
|
|
+This section contains things that should be NOT DONE:
|
|
|
+
|
|
|
+/// \brief Prepares HID report data to be sent
|
|
|
+*** NO '.' to terminate brief documentation.
|
|
|
+
|
|
|
+
|
|
|
+/// \brief Prepares HID report data to be sent.
|
|
|
+*** NO 's' after a verb in brief documentation.
|
|
|
+
|
|
|
+
|
|
|
+/// \brief Retrieve a state change since last call of the HID Mouse.
|
|
|
+*** NO 'a' or 'the' in brief text.
|
|
|
+
|
|
|
+
|
|
|
+/// \return true when state change since last call, false otherwise.
|
|
|
+*** Confusing return statement, separate into two lines (looks also better):
|
|
|
+/// \return
|
|
|
+/// - true = when state change since last call
|
|
|
+/// - false = otherwise.
|
|
|
+
|
|
|
+
|
|
|
+/// \return 0 no communication error.
|
|
|
+/// \return - 1 communication error.
|
|
|
+*** Confusing, may generate a bullet point, use instead "value" in front of plain numbers, correct is:
|
|
|
+/// \return value 0 no communication error.
|
|
|
+/// \return value -1 communication error.
|
|
|
+
|
|
|
+
|
|
|
+/// \param[in] req Request type:
|
|
|
+/// USBD_HID_REQ_EP_CTRL = Control endpoint request.
|
|
|
+/// USBD_HID_REQ_PERIOD_UPDATE = Idle period expiration request.
|
|
|
+/// USBD_HID_REQ_EP_INT = Previously sent report on interrupt endpoint request.
|
|
|
+*** Missing '-' in front of parameter details => hard to read in documentation.
|
|
|
+
|
|
|
+
|
|
|
+/// \param[in] stat error status and line states
|
|
|
+/// - bit 6 - bOverRun
|
|
|
+/// - bit 5 - bParity
|
|
|
+*** Missing ':' after states and bit numbers, correct is:
|
|
|
+/// \param[in] stat error status and line states:
|
|
|
+/// - bit 6: bOverRun
|
|
|
+/// - bit 5: bParity
|
|
|
+
|
|
|
+
|
|
|
+/// \param[in] ptr_data pointer to data buffer where information is written.
|
|
|
+*** Wrong, should be param[out].
|
|
|
+*** Redundant: a data buffer is always a pointer, better is:
|
|
|
+/// \param[out] ptr_data data buffer that receives information.
|
|
|
+
|
|
|
+
|
|
|
+/// \fn bool USBH_HID_GetStatus (uint8_t index);
|
|
|
+/// \brief Get status of the Human Interface Device.
|
|
|
+/// \param[in] index instance index of HID.
|
|
|
+/// \return true device is configured and initialized.
|
|
|
+/// \return false device not ready.
|
|
|
+extern bool USBH_HID_GetStatus (uint8_t index);
|
|
|
+Wrong: \fn not needed
|
|
|
+
|
|
|
+
|
|
|
+/* USB Host Speed constants */
|
|
|
+enum {
|
|
|
+ USBH_LS = 0, /* Low speed */
|
|
|
+ USBH_FS, /* Full speed */
|
|
|
+ USBH_HS /* High speed */
|
|
|
+};
|
|
|
+Wrong, should be Doxygen style. Correct is:
|
|
|
+/// USB Host Speed constants
|
|
|
+enum {
|
|
|
+ USBH_LS = 0, ///< Low speed
|
|
|
+ USBH_FS, ///< Full speed
|
|
|
+ USBH_HS ///< High speed
|
|
|
+};
|
|
|
+
|
|
|
+
|
|
|
+typedef struct { ///< Hw Endpoint settings structure
|
|
|
+ osThreadId thread_id; ///< Thread ID of thread that uses URB
|
|
|
+ USBH_URB urb; ///< URB used for endpoint communication} USBH_EP;
|
|
|
+Wrong: '/// comment' before 'struct {'
|
|
|
+Bad: repeat of Thread ID and URB does not add value; avoid abbreviations like 'Hw'
|
|
|
+
|
|
|
+Better is:
|
|
|
+/// Hardware Endpoint Settings for communication functions
|
|
|
+typedef struct {
|
|
|
+ osThreadId thread_id; ///< thread using USB Request Block (urb)
|
|
|
+ USBH_URB urb; ///< USB Request Block for endpoint communication
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+API Documentation in *.txt files
|
|
|
+--------------------------------
|
|
|
+
|
|
|
+A *.txt file that relates to a *.h contains:
|
|
|
+ - Functional group assignments using \defgroup along with \brief description
|
|
|
+ - Under \details an overview descrption for each functional group (should contain a useful code example)
|
|
|
+ - For each function in the header file a detailed description
|
|
|
+
|
|
|
+
|
|
|
+IMPORTANT:
|
|
|
+Text *.txt files that document the user API of a component are located in .\MW\Doc\component.
|
|
|
+Only for *.h files that provide user API, there is exaclty one text file with the same name.
|
|
|
+Defines/Functions that are internally used by a Component have no *.txt file.
|
|
|
+
|
|
|
+Example:
|
|
|
+ .\MW\component\Include\rl_usb.h => .\MW\Doc\component\rl_usb.txt
|
|
|
+
|
|
|
+The file documents each function that is exposed in *.h header file (and only those functions).
|
|
|
+In case that functions are described in other files (i.e. USB Class Templates) there is a reference.
|
|
|
+
|
|
|
+Functional Group assignemts uses this syntax:
|
|
|
+---------------------------
|
|
|
+/**
|
|
|
+\defgroup a group definition
|
|
|
+[\ingroup] optionally within a group
|
|
|
+\brief brief description of the group
|
|
|
+\details
|
|
|
+description
|
|
|
+*/
|
|
|
+
|
|
|
+/**
|
|
|
+\addtogroup a group definition
|
|
|
+@{
|
|
|
+*/
|
|
|
+
|
|
|
+Below \addtogroup the documentation for releated functions is provided. This section
|
|
|
+ends with @}
|
|
|
+
|
|
|
+Function documentation uses this syntax:
|
|
|
+--------
|
|
|
+/**
|
|
|
+\fn functionName( args )
|
|
|
+\details
|
|
|
+[\note]
|
|
|
+[<b>Code Example</b>
|
|
|
+\code | \snippet]
|
|
|
+*/
|
|
|
+
|
|
|
+See rl_usb.txt for examples
|
|
|
+No ';' at the end of the function declaration. Otherwise function description gets ignored.
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+Comments in doxygen code blocks should be marked with // and not /* ... */, which leads to errors.
|
|
|
+-------------------------------------------------------
|
|
|
+Example: Wrong:
|
|
|
+\code
|
|
|
+void ftp_server_notify (uint8_t event) {
|
|
|
+ /* Notify the user application about events in FTP server.*/
|
|
|
+ ...
|
|
|
+}
|
|
|
+\endcode
|
|
|
+
|
|
|
+Example: correct:
|
|
|
+\code
|
|
|
+void ftp_server_notify (uint8_t event) {
|
|
|
+ // Notify the user application about events in FTP server.
|
|
|
+ ...
|
|
|
+}
|
|
|
+\endcode
|
|
|
+
|
|
|
+
|
ReinhardKeil