[PATCH 3/4] gdb: update the docs for add_cmd and do_add_cmd to match reality

[Marco Barisione <mbarisione@undo.io>]

It looks like the docs for add_cmd ended up being the docs for
do_add_cmd.  Moreover, they were outdated.

gdb/ChangeLog:

	* cli/cli-decode.c (do_add_cmd): Remove outdated documentation
	and refer to the documentation for add_cmd.
	(add_cmd): Add comment referring to the docs in command.h.
	* command.h (add_cmd): Add updated documentation.
---
 gdb/cli/cli-decode.c | 22 +++++-----------------
 gdb/command.h        | 40 +++++++++++++++++++++++++++++++++-------
 2 files changed, 38 insertions(+), 24 deletions(-)

diff --git a/gdb/cli/cli-decode.c b/gdb/cli/cli-decode.c
index 87785107e3d..a25e3f420b3 100644
--- a/gdb/cli/cli-decode.c
+++ b/gdb/cli/cli-decode.c
@@ -160,23 +160,7 @@ set_cmd_completer_handle_brkchars (struct cmd_list_element *cmd,
   cmd->completer_handle_brkchars = func;
 }
 
-/* Add element named NAME.
-   Space for NAME and DOC must be allocated by the caller.
-   CLASS is the top level category into which commands are broken down
-   for "help" purposes.
-   FUN should be the function to execute the command;
-   it will get a character string as argument, with leading
-   and trailing blanks already eliminated.
-
-   DOC is a documentation string for the command.
-   Its first line should be a complete sentence.
-   It should start with ? for a command that is an abbreviation
-   or with * for a command that most users don't need to know about.
-
-   Add this command to command list *LIST.
-
-   Returns a pointer to the added command (not necessarily the head 
-   of *LIST).  */
+/* Like ADD_CMD, but the command function fields are not modified.  */
 
 static struct cmd_list_element *
 do_add_cmd (const char *name, enum command_class theclass,
@@ -227,6 +211,8 @@ do_add_cmd (const char *name, enum command_class theclass,
   return c;
 }
 
+/* See command.h.  */
+
 struct cmd_list_element *
 add_cmd (const char *name, enum command_class theclass,
 	 const char *doc, struct cmd_list_element **list)
@@ -237,6 +223,8 @@ add_cmd (const char *name, enum command_class theclass,
   return result;
 }
 
+/* See command.h.  */
+
 struct cmd_list_element *
 add_cmd (const char *name, enum command_class theclass,
 	 cmd_const_cfunc_ftype *fun,
diff --git a/gdb/command.h b/gdb/command.h
index 827a19637a2..df40cbf7119 100644
--- a/gdb/command.h
+++ b/gdb/command.h
@@ -155,18 +155,44 @@ extern bool valid_user_defined_cmd_name_p (const char *name);
 
 extern bool valid_cmd_char_p (int c);
 
-/* Const-correct variant of the above.  */
+/* Add a command named NAME in command list *LIST.
 
-extern struct cmd_list_element *add_cmd (const char *, enum command_class,
+   NAME and DOC are not duplicated. If they are not static string, they
+   must have been allocated with xmalloc or xstrdup and the
+   NAME_ALLOCATED/DOC_ALLOCATED fields must be set to 1 on the returned
+   command.
+
+   THECLASS is the top level category into which commands are broken down
+   for "help" purposes.
+
+   FUN should be the function to execute the command; it will get two
+   arguments, a character string (with leading and trailing blanks already
+   eliminated) containing the command arguments, and an integer indicating
+   whether input comes from a TTY or not.
+
+   DOC is a documentation string for the command.
+   Its first line should be a complete sentence.
+   It should start with ? for a command that is an abbreviation
+   or with * for a command that most users don't need to know about.
+
+   If NAME already existed in *LIST, all its hooks and aliases are moved
+   to the new command.
+
+   Return a pointer to the added command (not necessarily the head of
+   *LIST).  */
+
+extern struct cmd_list_element *add_cmd (const char *name,
+					 enum command_class theclass,
 					 cmd_const_cfunc_ftype *fun,
-					 const char *,
-					 struct cmd_list_element **);
+					 const char *doc,
+					 struct cmd_list_element **list);
 
 /* Like add_cmd, but no command function is specified.  */
 
-extern struct cmd_list_element *add_cmd (const char *, enum command_class,
-					 const char *,
-					 struct cmd_list_element **);
+extern struct cmd_list_element *add_cmd (const char *name,
+					 enum command_class theclass,
+					 const char *doc,
+					 struct cmd_list_element **list);
 
 extern struct cmd_list_element *add_cmd_suppress_notification
 			(const char *name, enum command_class theclass,
-- 
2.28.0