shell: support setting help string for each entry in a dictionary command

Add support for setting the help description for each entry in a dictionary
command. Currently the syntax string alone may not provide sufficient
description of its entry. This commit also helps keep the help messages
consistent with existing style.

Signed-off-by: Xinyang Tan <[email protected]>

Author: Xinyang Tan

drivers/adc/adc_shell.c

@@ -357,30 +357,30 @@ static int cmd_adc_print(const struct shell *shell, size_t argc, char **argv)
 }
 
 SHELL_SUBCMD_DICT_SET_CREATE(sub_ref_cmds, cmd_adc_ref,
-	(VDD_1, ADC_REF_VDD_1),
-	(VDD_1_2, ADC_REF_VDD_1_2),
-	(VDD_1_3, ADC_REF_VDD_1_3),
-	(VDD_1_4, ADC_REF_VDD_1_4),
-	(INTERNAL, ADC_REF_INTERNAL),
-	(EXTERNAL_0, ADC_REF_EXTERNAL0),
-	(EXTERNAL_1, ADC_REF_EXTERNAL1)
+	(VDD_1, ADC_REF_VDD_1, "VDD"),
+	(VDD_1_2, ADC_REF_VDD_1_2, "VDD/2"),
+	(VDD_1_3, ADC_REF_VDD_1_3, "VDD/3"),
+	(VDD_1_4, ADC_REF_VDD_1_4, "VDD/4"),
+	(INTERNAL, ADC_REF_INTERNAL, "Internal"),
+	(EXTERNAL_0, ADC_REF_EXTERNAL0, "External, input 0"),
+	(EXTERNAL_1, ADC_REF_EXTERNAL1, "External, input 1")
 );
 
 SHELL_SUBCMD_DICT_SET_CREATE(sub_gain_cmds, cmd_adc_gain,
-	(GAIN_1_6, ADC_GAIN_1_6),
-	(GAIN_1_5, ADC_GAIN_1_5),
-	(GAIN_1_4, ADC_GAIN_1_4),
-	(GAIN_1_3, ADC_GAIN_1_3),
-	(GAIN_1_2, ADC_GAIN_1_2),
-	(GAIN_2_3, ADC_GAIN_2_3),
-	(GAIN_1, ADC_GAIN_1),
-	(GAIN_2, ADC_GAIN_2),
-	(GAIN_3, ADC_GAIN_3),
-	(GAIN_4, ADC_GAIN_4),
-	(GAIN_8, ADC_GAIN_8),
-	(GAIN_16, ADC_GAIN_16),
-	(GAIN_32, ADC_GAIN_32),
-	(GAIN_64, ADC_GAIN_64)
+	(GAIN_1_6, ADC_GAIN_1_6, "x 1/6"),
+	(GAIN_1_5, ADC_GAIN_1_5, "x 1/5"),
+	(GAIN_1_4, ADC_GAIN_1_4, "x 1/4"),
+	(GAIN_1_3, ADC_GAIN_1_3, "x 1/3"),
+	(GAIN_1_2, ADC_GAIN_1_2, "x 1/2"),
+	(GAIN_2_3, ADC_GAIN_2_3, "x 2/3"),
+	(GAIN_1, ADC_GAIN_1, "x 1"),
+	(GAIN_2, ADC_GAIN_2, "x 2"),
+	(GAIN_3, ADC_GAIN_3, "x 3"),
+	(GAIN_4, ADC_GAIN_4, "x 4"),
+	(GAIN_8, ADC_GAIN_8, "x 8"),
+	(GAIN_16, ADC_GAIN_16, "x 16"),
+	(GAIN_32, ADC_GAIN_32, "x 32"),
+	(GAIN_64, ADC_GAIN_64, "x 64")
 );
 
 SHELL_STATIC_SUBCMD_SET_CREATE(sub_channel_cmds,

include/zephyr/shell/shell.h

@@ -510,7 +510,7 @@ static int UTIL_CAT(UTIL_CAT(cmd_dict_, UTIL_CAT(_handler, _)),		\
 
 /* Internal macro used for creating dictionary commands. */
 #define SHELL_CMD_DICT_CREATE(_data, _handler)				\
-	SHELL_CMD_ARG(GET_ARG_N(1, __DEBRACKET _data), NULL, NULL,	\
+	SHELL_CMD_ARG(GET_ARG_N(1, __DEBRACKET _data), NULL, GET_ARG_N(3, __DEBRACKET _data),	\
 		UTIL_CAT(UTIL_CAT(cmd_dict_, UTIL_CAT(_handler, _)),	\
 			GET_ARG_N(1, __DEBRACKET _data)), 1, 0)
 
@@ -540,7 +540,8 @@ static int UTIL_CAT(UTIL_CAT(cmd_dict_, UTIL_CAT(_handler, _)),		\
  *	}
  *
  *	SHELL_SUBCMD_DICT_SET_CREATE(sub_dict_cmds, my_handler,
- *		(value_0, 0), (value_1, 1), (value_2, 2), (value_3, 3)
+ *		(value_0, 0, "value 0"), (value_1, 1, "value 1"),
+ *		(value_2, 2, "value 2"), (value_3, 3, "value 3")
  *	);
  *	SHELL_CMD_REGISTER(dictionary, &sub_dict_cmds, NULL, NULL);
  */

samples/subsys/shell/shell_module/src/main.c

@@ -369,7 +369,8 @@ static int cmd_dict(const struct shell *shell, size_t argc, char **argv,
 }
 
 SHELL_SUBCMD_DICT_SET_CREATE(sub_dict_cmds, cmd_dict,
-	(value_0, 0), (value_1, 1), (value_2, 2), (value_3, 3)
+	(value_0, 0, "value 0"), (value_1, 1, "value 1"),
+	(value_2, 2, "value 2"), (value_3, 3, "value 3")
 );
 
 SHELL_STATIC_SUBCMD_SET_CREATE(sub_demo,

tests/subsys/shell/shell/src/main.c

@@ -445,8 +445,8 @@ static int cmd_handler_dict_2(const struct shell *sh, size_t argc, char **argv,
 	return n + n;
 }
 
-SHELL_SUBCMD_DICT_SET_CREATE(dict1, cmd_handler_dict_1, (one, 1), (two, 2));
-SHELL_SUBCMD_DICT_SET_CREATE(dict2, cmd_handler_dict_2, (one, 1), (two, 2));
+SHELL_SUBCMD_DICT_SET_CREATE(dict1, cmd_handler_dict_1, (one, 1, "one"), (two, 2, "two"));
+SHELL_SUBCMD_DICT_SET_CREATE(dict2, cmd_handler_dict_2, (one, 1, "one"), (two, 2, "two"));
 
 SHELL_CMD_REGISTER(dict1, &dict1, NULL, NULL);
 SHELL_CMD_REGISTER(dict2, &dict2, NULL, NULL);