RT-Thread
/
rt-thread
mirror of https://github.com/RT-Thread/rt-thread
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

doxygen: finsh: Normalize macro definitions (#10006) 

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__ */ #endif /* __TI_COMPILER_VERSION__ */
/** /**
* Macro to export a command along with its name, description, and options to the symbol table in MSVC. * @brief 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[in] name The function name associated with the command.
* @param desc The description of the command. * @param[in] cmd The command name.
* @param opt The options associated with the command, used for option completion. * @param[in] desc The description of the command.
* @param[in] opt The options associated with the command, used for option completion.
*/ */
#ifdef _MSC_VER #ifdef _MSC_VER
#define MSH_FUNCTION_EXPORT_CMD(name, cmd, desc, opt) \ #define MSH_FUNCTION_EXPORT_CMD(name, cmd, desc, opt) \
@ -90,7 +91,7 @@ typedef long (*syscall_func)(void);
#endif /* FINSH_USING_SYMTAB */ #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_MACRO(_1, _2, _3, _FUN, ...) _FUN
#define __MSH_GET_EXPORT_MACRO(_1, _2, _3, _4, _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 * @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[in] name Name of function.
* @param desc the description of function, which will show in help. * @param[in] desc Description of function, which will show in help.
*/ */
#define FINSH_FUNCTION_EXPORT(name, desc) #define FINSH_FUNCTION_EXPORT(name, desc)
/** /**
* @ingroup group_finsh * @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[in] name Name of function.
* @param alias the alias name of function. * @param[in] alias Alias name of function.
* @param desc the description of function, which will show in help. * @param[in] desc Description of function, which will show in help.
*/ */
#define FINSH_FUNCTION_EXPORT_ALIAS(name, alias, desc) #define FINSH_FUNCTION_EXPORT_ALIAS(name, alias, desc)
/** /**
* @ingroup group_finsh * @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. * @b Parameters
* 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 * <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(...) \ #define MSH_CMD_EXPORT(...) \
__MSH_GET_MACRO(__VA_ARGS__, _MSH_FUNCTION_CMD2_OPT, \ __MSH_GET_MACRO(__VA_ARGS__, _MSH_FUNCTION_CMD2_OPT, \
_MSH_FUNCTION_CMD2)(__VA_ARGS__) _MSH_FUNCTION_CMD2)(__VA_ARGS__)
@ -146,16 +155,22 @@ typedef long (*syscall_func)(void);
/** /**
* @ingroup group_finsh * @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. * @b Parameters
* param alias is the alias of the command. *
* param desc is the description of the command, which will show in help list. * <tt>[in]</tt> @b command Name of the command.
* param opt This is an option, enter any content to enable option completion *
* @code * <tt>[in]</tt> @b alias Alias of the command.
* #define MSH_CMD_EXPORT_ALIAS(command, alias, desc) or *
* #define MSH_CMD_EXPORT_ALIAS(command, alias, desc, opt) * <tt>[in]</tt> @b desc Description of the command, which will show in help list.
* @endcode *
* <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(...) \ #define MSH_CMD_EXPORT_ALIAS(...) \
__MSH_GET_EXPORT_MACRO(__VA_ARGS__, _MSH_FUNCTION_EXPORT_CMD3_OPT, \ __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 */ /* Command options declaration and definition macros */
/** /**
* Declares a static array of command options for a specific command. * @brief Declares a static array of command options for a specific command.
* @param command The command associated with these options. *
* @param[in] command The command associated with these options.
*/ */
#define CMD_OPTIONS_STATEMENT(command) static struct msh_cmd_opt command##_msh_options[]; #define CMD_OPTIONS_STATEMENT(command) static struct msh_cmd_opt command##_msh_options[];
/** /**
* Starts the definition of command options for a specific command. * @brief Starts the definition of command options for a specific command.
* @param command The command these options are associated with. *
* @param[in] command The command these options are associated with.
*/ */
#define CMD_OPTIONS_NODE_START(command) static struct msh_cmd_opt command##_msh_options[] = { #define CMD_OPTIONS_NODE_START(command) static struct msh_cmd_opt command##_msh_options[] = {
/** /**
* Defines a single command option. * @brief Defines a single command option.
* @param _id Unique identifier for the option. *
* @param _name The name of the option. * @param[in] _id Unique identifier for the option.
* @param _des Description of 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}, #define CMD_OPTIONS_NODE(_id, _name, _des) {.id = _id, .name = #_name, .des = #_des},