libs/rt-thread-official
libs/rt-thread-official
4
0
Fork 0
mirror of https://github.com/RT-Thread/rt-thread.git synced 2025-02-21 20:05:21 +08:00
Code Issues Releases Wiki Activity

doxygen: finsh: Normalize macro definitions (#10006)

Browse Source 
Regular macro definitions according to [1].

Note: for variadic macros such as MSH_CMD_EXPORT, we can
not use normal @param command, otherwise doxygen will
report "@param is not found in the argument list of ...".
So I just write the parameters by manual.

Link: https://rt-thread.github.io/rt-thread/page_howto_macro.html [1]

Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
This commit is contained in:
Chen Wang 2025-02-19 21:06:45 +08:00 committed by GitHub
parent 6a0909ac1a
commit 14cfc72fb8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 53 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
components/finsh/finsh.h
View File

@ -36,11 +36,12 @@ typedef long (*syscall_func)(void);
#endif /* __TI_COMPILER_VERSION__ */
/**
* Macro to export a command along with its name, description, and options to the symbol table in MSVC.
* @param name The function name associated with the command.
* @param cmd The command name.
* @param desc The description of the command.
* @param opt The options associated with the command, used for option completion.
* @brief Macro to export a command along with its name, description, and options to the symbol table in MSVC.
*
* @param[in] name The function name associated with the command.
* @param[in] cmd The command name.
* @param[in] desc The description of the command.
* @param[in] opt The options associated with the command, used for option completion.
*/
#ifdef _MSC_VER
#define MSH_FUNCTION_EXPORT_CMD(name, cmd, desc, opt) \
@ -90,7 +91,7 @@ typedef long (*syscall_func)(void);
#endif /* FINSH_USING_SYMTAB */
/**
* Macro definitions to simplify the declaration of exported functions or commands.
* @brief Macro definitions to simplify the declaration of exported functions or commands.
*/
#define __MSH_GET_MACRO(_1, _2, _3, _FUN, ...) _FUN
#define __MSH_GET_EXPORT_MACRO(_1, _2, _3, _4, _FUN, ...) _FUN
@ -111,34 +112,42 @@ typedef long (*syscall_func)(void);
/**
* @ingroup group_finsh
*
* This macro exports a system function to finsh shell.
* @brief This macro exports a system function to finsh shell.
*
* @param name the name of function.
* @param desc the description of function, which will show in help.
* @param[in] name Name of function.
* @param[in] desc Description of function, which will show in help.
*/
#define FINSH_FUNCTION_EXPORT(name, desc)
/**
* @ingroup group_finsh
*
* This macro exports a system function with an alias name to finsh shell.
* @brief Exports a system function with an alias name to finsh shell.
*
* @param name the name of function.
* @param alias the alias name of function.
* @param desc the description of function, which will show in help.
* @param[in] name Name of function.
* @param[in] alias Alias name of function.
* @param[in] desc Description of function, which will show in help.
*/
#define FINSH_FUNCTION_EXPORT_ALIAS(name, alias, desc)
/**
* @ingroup group_finsh
*
* This macro exports a command to module shell.
* @brief Exports a command to module shell.
*
* param command is the name of the command.
* param desc is the description of the command, which will show in help list.
* param opt This is an option, enter any content to enable option completion
* @b Parameters
*
* <tt>[in]</tt> @b command Name of the command.
*
* <tt>[in]</tt> @b desc Description of the command, which will show in help list.
*
* <tt>[in]</tt> @b opt This is an option, enter any content to enable option completion
*
* @note This macro can be used in two ways:
* @code MSH_CMD_EXPORT(command, desc) @endcode
* or
* @code MSH_CMD_EXPORT(command, desc, opt) @endcode
*/
/* MSH_CMD_EXPORT(command, desc) or MSH_CMD_EXPORT(command, desc, opt) */
#define MSH_CMD_EXPORT(...) \
__MSH_GET_MACRO(__VA_ARGS__, _MSH_FUNCTION_CMD2_OPT, \
_MSH_FUNCTION_CMD2)(__VA_ARGS__)
@ -146,16 +155,22 @@ typedef long (*syscall_func)(void);
/**
* @ingroup group_finsh
*
* This macro exports a command with alias to module shell.
* @brief Exports a command with alias to module shell.
*
* param command is the name of the command.
* param alias is the alias of the command.
* param desc is the description of the command, which will show in help list.
* param opt This is an option, enter any content to enable option completion
* @code
* #define MSH_CMD_EXPORT_ALIAS(command, alias, desc) or
* #define MSH_CMD_EXPORT_ALIAS(command, alias, desc, opt)
* @endcode
* @b Parameters
*
* <tt>[in]</tt> @b command Name of the command.
*
* <tt>[in]</tt> @b alias Alias of the command.
*
* <tt>[in]</tt> @b desc Description of the command, which will show in help list.
*
* <tt>[in]</tt> @b opt An option, enter any content to enable option completion.
*
* @note This macro can be used in two ways:
* @code #define MSH_CMD_EXPORT_ALIAS(command, alias, desc) @endcode
* or
* @code #define MSH_CMD_EXPORT_ALIAS(command, alias, desc, opt) @endcode
*/
#define MSH_CMD_EXPORT_ALIAS(...) \
__MSH_GET_EXPORT_MACRO(__VA_ARGS__, _MSH_FUNCTION_EXPORT_CMD3_OPT, \
@ -193,22 +208,25 @@ typedef struct msh_cmd_opt
/* Command options declaration and definition macros */
/**
* Declares a static array of command options for a specific command.
* @param command The command associated with these options.
* @brief Declares a static array of command options for a specific command.
*
* @param[in] command The command associated with these options.
*/
#define CMD_OPTIONS_STATEMENT(command) static struct msh_cmd_opt command##_msh_options[];
/**
* Starts the definition of command options for a specific command.
* @param command The command these options are associated with.
* @brief Starts the definition of command options for a specific command.
*
* @param[in] command The command these options are associated with.
*/
#define CMD_OPTIONS_NODE_START(command) static struct msh_cmd_opt command##_msh_options[] = {
/**
* Defines a single command option.
* @param _id Unique identifier for the option.
* @param _name The name of the option.
* @param _des Description of the option.
* @brief Defines a single command option.
*
* @param[in] _id Unique identifier for the option.
* @param[in] _name The name of the option.
* @param[in] _des Description of the option.
*/
#define CMD_OPTIONS_NODE(_id, _name, _des) {.id = _id, .name = #_name, .des = #_des},