mirror of
https://github.com/silenty4ng/uv-k5-firmware-chinese-lts
synced 2025-01-26 12:13:31 +00:00
281 lines
12 KiB
Text
281 lines
12 KiB
Text
Rules for CMSIS API Function documentation
|
|
===========================================
|
|
|
|
This document describes how to generate Doxygen-style documentation for middleware "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 documentation.
|
|
*.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 following snippet 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 multiple instances), they are included in
|
|
#ifdef __DOXYGEN__ / #endif sections.
|
|
|
|
{code}
|
|
/// \brief Called during \ref USBD_Initialize to initialize 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 description 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 exactly 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 assignments 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 related 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
|
|
|
|
|
|
|
|
Cross references (between components)
|
|
-------------------------------------
|
|
|
|
Within a single component (same .dxy configuration) one can easily created cross references.
|
|
Known symbol names are automatically assumed as a reference by Doxygen. Pages, sections and
|
|
subsections can be referenced using "\ref" notation.
|
|
|
|
Cross references do not work between different components, though. Doxygen offers the possibility
|
|
to import so called tags (symbol and section names) from an another external documentation.
|
|
Unfortunately this creates output that crashes the MDK DoxyIndex importer. Hence cross references
|
|
needs to be placed manually using <a href="[url]">...</a> notation, for the time being.
|