[msh] add comment for secondary-commands

新增加的二级命令使用方式没有清晰的描述
- 功能实现PR：https://github.com/RT-Thread/rt-thread/pull/8086
- 补充优化PR：https://github.com/RT-Thread/rt-thread/pull/8251
- 使用二级命令的例子：https://github.com/RT-Thread/rt-thread/pull/8398
- 相关issue：https://github.com/RT-Thread/rt-thread/issues/8691

1 files changed, 36 insertions, 4 deletions

diff --git a/components/finsh/finsh.h b/components/finsh/finsh.h
index f8e4ba5060..4e9727df5b 100644
--- a/components/finsh/finsh.h
+++ b/components/finsh/finsh.h
@@ -35,6 +35,13 @@ typedef long (*syscall_func)(void);
 #define __TI_FINSH_EXPORT_FUNCTION(f)  PRAGMA(DATA_SECTION(f,"FSymTab"))
 #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.
+ */
 #ifdef _MSC_VER
 #define MSH_FUNCTION_EXPORT_CMD(name, cmd, desc, opt)               \
                 const char __fsym_##cmd##_name[] = #cmd;            \
@@ -80,9 +87,11 @@ typedef long (*syscall_func)(void);
                 };
 
 #endif  /* _MSC_VER */
-#endif /* end of FINSH_USING_SYMTAB */
-
+#endif /* FINSH_USING_SYMTAB */
 
+/**
+ * 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
 
@@ -143,9 +152,10 @@ typedef long (*syscall_func)(void);
  * @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
+ * @note
+ *      #define MSH_CMD_EXPORT_ALIAS(command, alias, desc) or
+ *      #define MSH_CMD_EXPORT_ALIAS(command, alias, desc, opt)
  */
-/* #define MSH_CMD_EXPORT_ALIAS(command, alias, desc) or
-   #define MSH_CMD_EXPORT_ALIAS(command, alias, desc, opt) */
 #define MSH_CMD_EXPORT_ALIAS(...)                                           \
     __MSH_GET_EXPORT_MACRO(__VA_ARGS__, _MSH_FUNCTION_EXPORT_CMD3_OPT,      \
             _MSH_FUNCTION_EXPORT_CMD3)(__VA_ARGS__)
@@ -179,9 +189,31 @@ typedef struct msh_cmd_opt
     const char      *des;
 } msh_cmd_opt_t;
 
+/* 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.
+ */
 #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.
+ */
 #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.
+ */
 #define CMD_OPTIONS_NODE(_id, _name, _des) {.id = _id, .name = #_name, .des = #_des},
+
+/**
+ * Marks the end of command options definition.
+ */
 #define CMD_OPTIONS_NODE_END    {0},};
 
 void msh_opt_list_dump(void *options);