[RFA] Allow to document user-defined aliases.

[RFA] Allow to document user-defined aliases.

[Philippe Waroquiers via Gdb-patches]

When using 'help ALIASNAME', GDB shows the help of the aliased command.
This is a good default behaviour.

However, GDB alias command allows to define aliases with arguments
possibly changing or tuning significantly the behaviour of
the aliased command.  In such a case, showing the help of the aliased
command might not be ideal.

This is particularly true when defining an alias as a set of
nested 'with' followed by a last command to launch, such as:
  (gdb) alias pp10 = with print pretty -- with print elements 10 -- print
Asking 'help pp10' shows the help of the 'with' command, which is
not particularly useful:
  (gdb) help pp10
  with, pp10, w
    alias pp10 = with print pretty -- with print elements 10 -- print
  Temporarily set SETTING to VALUE, run COMMAND, and restore SETTING.
  Usage: with SETTING [VALUE] [-- COMMAND]
  ....

Such an alias can now be documented by the user:
  (gdb) document pp10
  >Pretty printing an expressiong, printing 10 elements.
  >Usage: pp10 [PRINT-COMMAND-OPTIONS] EXP
  >See 'help print' for more information.
  >end
  (gdb) help pp10
  Pretty printing an expressiong, printing 10 elements.
  Usage: pp10 [PRINT-COMMAND-OPTIONS] EXP
  See 'help print' for more information.
  (gdb)

When a user-defined alias is documented specifically, help and apropos
use the provided alias documentation instead of the documentation of
the aliased command.

Such a documented alias is also not shown anymore in the help of the
aliased command, and the alias is not listed anymore in the help
of the aliased command.  In particular for cases such as pp10 example above,
indicating that pp10 is an alias of the 'with' command is confusing.
---
 gdb/NEWS                        | 10 ++++++
 gdb/cli/cli-decode.c            | 58 ++++++++++++++++++++++++---------
 gdb/cli/cli-script.c            | 35 +++++++++++++-------
 gdb/doc/gdb.texinfo             | 26 ++++++++++++++-
 gdb/testsuite/gdb.base/help.exp | 44 +++++++++++++++++++++++--
 5 files changed, 142 insertions(+), 31 deletions(-)

diff --git a/gdb/NEWS b/gdb/NEWS
index d2efe2a0a58..20b65860a41 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -93,6 +93,16 @@ show style disassembler symbol
 
 * Changed commands
 
+document user-defined
+  It is now possible to document user-defined aliases.
+  When a user-defined alias is documented, the help and apropos commands
+  use the provided documentation instead of the documentation of the
+  aliased command.
+  Documenting a user-defined alias is particularly useful when the alias
+  is a set of nested 'with' commands to avoid showing the help of
+  the with command for an alias that will in fact launch the
+  last command given in the nested commands.
+
 maintenance info line-table
   Add a PROLOGUE-END column to the output which indicates that an
   entry corresponds to an address where a breakpoint should be placed
diff --git a/gdb/cli/cli-decode.c b/gdb/cli/cli-decode.c
index fde554c7e6c..053a51eb4b7 100644
--- a/gdb/cli/cli-decode.c
+++ b/gdb/cli/cli-decode.c
@@ -1349,6 +1349,18 @@ fput_command_name_styled (const cmd_list_element &c, struct ui_file *stream)
 		  prefixname.c_str (), c.name);
 }
 
+/* True if ALIAS has a user-defined documentation.  */
+
+static bool
+user_documented_alias (const cmd_list_element &alias)
+{
+  gdb_assert (alias.is_alias ());
+  /* Alias is user documented if it has an allocated documentation
+     that differs from the aliased command.  */
+  return alias.doc_allocated
+    && strcmp (alias.doc, alias.alias_target->doc) != 0;
+}
+
 /* Print the definition of alias C using title style for alias
    and aliased command.  */
 
@@ -1364,20 +1376,22 @@ fput_alias_definition_styled (const cmd_list_element &c,
   gdb_printf (stream, " %s\n", c.default_args.c_str ());
 }
 
-/* Print the definition of the aliases of CMD that have default args.  */
+/* Print the definition of CMD aliases not deprecated and having default args
+   and not specifically documented by the user.  */
 
 static void
 fput_aliases_definition_styled (const cmd_list_element &cmd,
 				struct ui_file *stream)
 {
   for (const cmd_list_element &alias : cmd.aliases)
-    if (!alias.cmd_deprecated && !alias.default_args.empty ())
+    if (!alias.cmd_deprecated
+	&& !user_documented_alias (alias)
+	&& !alias.default_args.empty ())
       fput_alias_definition_styled (alias, stream);
 }
 
-
-/* If C has one or more aliases, style print the name of C and
-   the name of its aliases, separated by commas.
+/* If C has one or more aliases, style print the name of C and the name of its
+   aliases not documented specifically by the user, separated by commas.
    If ALWAYS_FPUT_C_NAME, print the name of C even if it has no aliases.
    If one or more names are printed, POSTFIX is printed after the last name.
 */
@@ -1389,11 +1403,11 @@ fput_command_names_styled (const cmd_list_element &c,
 {
   /* First, check if we are going to print something.  That is, either if
      ALWAYS_FPUT_C_NAME is true or if there exists at least one non-deprecated
-     alias.  */
+     alias not documented specifically by the user.  */
 
   auto print_alias = [] (const cmd_list_element &alias)
     {
-      return !alias.cmd_deprecated;
+      return !alias.cmd_deprecated && !user_documented_alias (alias);
     };
 
   bool print_something = always_fput_c_name;
@@ -1474,11 +1488,11 @@ apropos_cmd (struct ui_file *stream,
   /* Walk through the commands.  */
   for (c=commandlist;c;c=c->next)
     {
-      if (c->is_alias ())
+      if (c->is_alias () && !user_documented_alias (*c))
 	{
-	  /* Command aliases/abbreviations are skipped to ensure we print the
-	     doc of a command only once, when encountering the aliased
-	     command.  */
+	  /* Command aliases/abbreviations not specifically documented by the
+	     user are skipped to ensure we print the doc of a command only once,
+	     when encountering the aliased command.  */
 	  continue;
 	}
 
@@ -1571,11 +1585,23 @@ help_cmd (const char *command, struct ui_file *stream)
      number of this class so that the commands in the class will be
      listed.  */
 
-  /* If the user asked 'help somecommand' and there is no alias,
-     the false indicates to not output the (single) command name.  */
-  fput_command_names_styled (*c, false, "\n", stream);
-  fput_aliases_definition_styled (*c, stream);
-  gdb_puts (c->doc, stream);
+  if (alias == nullptr || ! user_documented_alias (*alias))
+    {
+      /* Case of a normal command, or an alias not explictly
+	 documented by the user.  */
+      /* If the user asked 'help somecommand' and there is no alias,
+	 the false indicates to not output the (single) command name.  */
+      fput_command_names_styled (*c, false, "\n", stream);
+      fput_aliases_definition_styled (*c, stream);
+      gdb_puts (c->doc, stream);
+    }
+  else
+    {
+      /* Case of an alias explictly documented by the user.
+	 Only output the alias name and its explicit documentation.  */
+      fput_command_names_styled (*alias, false, "\n", stream);
+      gdb_puts (alias->doc, stream);
+    }
   gdb_puts ("\n", stream);
 
   if (!c->is_prefix () && !c->is_command_class_help ())
diff --git a/gdb/cli/cli-script.c b/gdb/cli/cli-script.c
index 5f81db418bc..926f5b960a9 100644
--- a/gdb/cli/cli-script.c
+++ b/gdb/cli/cli-script.c
@@ -1500,7 +1500,7 @@ define_command (const char *comname, int from_tty)
   do_define_command (comname, from_tty, nullptr);
 }
 
-/* Document a user-defined command.  If COMMANDS is NULL, then this is a
+/* Document a user-defined command or user defined alias.  If COMMANDS is NULL, then this is a
    top-level call and the document will be read using read_command_lines.
    Otherwise, it is a "document" command in an existing command and the
    commands are provided.  */
@@ -1508,31 +1508,41 @@ static void
 do_document_command (const char *comname, int from_tty,
                      const counted_command_line *commands)
 {
-  struct cmd_list_element *c, **list;
-  const char *tem;
+  struct cmd_list_element *alias, *prefix_cmd, *c;
   const char *comfull;
 
   comfull = comname;
-  list = validate_comname (&comname);
+  validate_comname (&comname);
 
-  tem = comname;
-  c = lookup_cmd (&tem, *list, "", NULL, 0, 1);
+  lookup_cmd_composition (comfull, &alias, &prefix_cmd, &c);
 
-  if (c->theclass != class_user)
-    error (_("Command \"%s\" is built-in."), comfull);
+  if (c->theclass != class_user
+      && (alias == nullptr || alias->theclass != class_alias))
+    {
+      if (alias == nullptr)
+	error (_("Command \"%s\" is built-in."), comfull);
+      else
+	error (_("Alias \"%s\" is built-in."), comfull);
+    }
+
+  /* If we found an alias of class_alias, the user is documenting this
+     user-defined alias.  */
+  if (alias != nullptr)
+    c = alias;
 
   counted_command_line doclines;
 
   if (commands == nullptr)
     {
-      std::string prompt 
+      std::string prompt
         = string_printf ("Type documentation for \"%s\".", comfull);
       doclines = read_command_lines (prompt.c_str (), from_tty, 0, 0);
     }
   else
     doclines = *commands;
 
-  xfree ((char *) c->doc);
+  if (c->doc_allocated)
+    xfree ((char *) c->doc);
 
   {
     struct command_line *cl1;
@@ -1553,6 +1563,7 @@ do_document_command (const char *comname, int from_tty,
       }
 
     c->doc = doc;
+    c->doc_allocated = 1;
   }
 }
 
@@ -1681,8 +1692,8 @@ _initialize_cli_script ()
      its prefixes.  */
   document_cmd_element = add_com ("document", class_support, document_command,
                                   _("\
-Document a user-defined command.\n\
-Give command name as argument.  Give documentation on following lines.\n\
+Document a user-defined command or user-defined alias.\n\
+Give command or alias name as argument.  Give documentation on following lines.\n\
 End with a line of just \"end\"."));
   set_cmd_completer (document_cmd_element, command_completer);
   define_cmd_element = add_com ("define", class_support, define_command, _("\
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 382df00ee7d..cd73b94d1e3 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -2265,11 +2265,20 @@ one or more aliases, @value{GDBN} will display a first line with
 the command name and all its aliases separated by commas.
 This first line will be followed by the full definition of all aliases
 having default arguments.
+When asking the help for an alias, the documentation for the aliased
+command is shown.
+
+A user-defined alias can optionally be documented using the @code{document} command
+(@pxref{Define, document}).
+@value{GDBN} then considers this alias as different of the aliased
+command: this alias is not listed in the aliased command help output and asking
+help for this alias will show the user provided alias documentation
+instead of the documentation of the aliased command.
 
 @kindex apropos
 @item apropos [-v] @var{regexp}
 The @code{apropos} command searches through all of the @value{GDBN}
-commands, and their documentation, for the regular expression specified in
+commands and aliases, and their documentation, for the regular expression specified in
 @var{args}.  It prints out all matches found.  The optional flag  @samp{-v},
 which stands for @samp{verbose}, indicates to output the full documentation
 of the matching commands and highlight the parts of the documentation
@@ -27967,6 +27976,13 @@ You may use the @code{document} command again to change the
 documentation of a command.  Redefining the command with @code{define}
 does not change the documentation.
 
+It is also possible to document user-defined aliases.  The alias documentation
+will then be used by the @code{help} and @code{apropos} commands
+instead of the documentation of the aliased command.
+Documenting a user-defined alias is particularly useful when defining
+an alias as a set of nested @code{with} commands
+(@pxref{Command aliases default args,}).
+
 @kindex define-prefix
 @item define-prefix @var{commandname}
 Define or mark the command @var{commandname} as a user-defined prefix
@@ -28641,6 +28657,14 @@ by the user.
 For more information about the @code{with} command usage,
 see @ref{Command Settings}.
 
+By default, asking the help for an alias shows the documentation of
+the aliased command.  When the alias is a set of nested commands, @code{help}
+of an alias shows the documentation of the first command.  This help
+is not particularly useful for an alias such as @code{pp10}.
+For such an alias, it is useful to give a specific documentation
+using the @code{document} command (@pxref{Define, document}).
+
+
 @c Python docs live in a separate file.
 @include python.texi
 
diff --git a/gdb/testsuite/gdb.base/help.exp b/gdb/testsuite/gdb.base/help.exp
index 74da29e3d36..c3972b3801b 100644
--- a/gdb/testsuite/gdb.base/help.exp
+++ b/gdb/testsuite/gdb.base/help.exp
@@ -128,8 +128,48 @@ gdb_test "apropos handle signal" "handle -- Specify how to handle signals\."
 gdb_test "apropos apropos" "apropos -- Search for commands matching a REGEXP.*"
 
 # Test apropos for commands having aliases.
+gdb_test_no_output "alias mybt = backtrace" "define mybt alias"
+gdb_test_no_output "alias mybt10 = backtrace 10" "define mybt10 alias"
+
 gdb_test "apropos Print backtrace of all stack frames, or innermost COUNT frames\." \
-    "backtrace, where, bt -- Print backtrace of all stack frames, or innermost COUNT frames\."
+    "backtrace, mybt10, mybt, where, bt -- Print backtrace of all stack frames, or innermost COUNT frames\.\[\r\n\]+  alias mybt10 = backtrace 10"
 
 # Test help for commands having aliases.
-gdb_test "help bt" "backtrace, where, bt\[\r\n\]+Print backtrace of all stack frames, or innermost COUNT frames\..*"
+gdb_test "help bt" "backtrace, mybt10, mybt, where, bt\[\r\n\]+  alias mybt10 = backtrace 10\[\r\n\]+Print backtrace of all stack frames, or innermost COUNT frames\..*"
+
+# Document the aliases.  The apropos and help commands should then consider them
+# as "standalone" commands.
+gdb_test_multiple "document mybt" "document alias: mybt" {
+    -re "Type documentation for \"mybt\".\r\nEnd with a line saying just \"end\".\r\n>$" {
+	gdb_test "An alias of command backtrace without any args.\nend" \
+	    "" \
+	    "document alias: mybt"
+    }
+}
+gdb_test_multiple "document mybt10" "document alias: mybt10" {
+    -re "Type documentation for \"mybt10\".\r\nEnd with a line saying just \"end\".\r\n>$" {
+	gdb_test "An alias of command backtrace with arg 10.\nend" \
+	    "" \
+	    "document alias: mybt10"
+    }
+}
+
+# As the aliases are now documented, they do not appear in apropos/help backtrace output anymore.
+gdb_test "apropos Print backtrace of all stack frames, or innermost COUNT frames\." \
+    "backtrace, where, bt -- Print backtrace of all stack frames, or innermost COUNT frames\." \
+    "apropos after documenting aliases"
+
+gdb_test "help bt" "backtrace, where, bt\[\r\n\]+Print backtrace of all stack frames, or innermost COUNT frames\..*" \
+    "help after documenting aliases"
+
+# Check apropos and help use the alias documentation.
+gdb_test "apropos An alias of command backtrace with arg 10" \
+    "mybt10 -- An alias of command backtrace with arg 10\." \
+    "apropos after documenting aliases showing mybt10 doc"
+
+gdb_test "help mybt" "An alias of command backtrace without any args\." \
+    "help mybt after documenting aliases showing mybt doc"
+
+# Check pre-defined aliases cannot be documented.
+gdb_test "document where" "Alias \"where\" is built-in.*" \
+    "documenting builtin where alias disallowed"
-- 
2.30.2

Re: [RFA] Allow to document user-defined aliases.

[Eli Zaretskii via Gdb-patches]

> Date: Mon, 25 Jul 2022 06:11:13 +0200
> From: Philippe Waroquiers via Gdb-patches <gdb-patches@sourceware.org>
> 
> When using 'help ALIASNAME', GDB shows the help of the aliased command.
> This is a good default behaviour.
> 
> However, GDB alias command allows to define aliases with arguments
> possibly changing or tuning significantly the behaviour of
> the aliased command.  In such a case, showing the help of the aliased
> command might not be ideal.

But it doesn't do much harm, either.  Moreover, it is useful to tell
the user that some handy aliases exist related to the command.

> This is particularly true when defining an alias as a set of
> nested 'with' followed by a last command to launch, such as:
>   (gdb) alias pp10 = with print pretty -- with print elements 10 -- print
> Asking 'help pp10' shows the help of the 'with' command, which is
> not particularly useful:
>   (gdb) help pp10
>   with, pp10, w
>     alias pp10 = with print pretty -- with print elements 10 -- print
>   Temporarily set SETTING to VALUE, run COMMAND, and restore SETTING.
>   Usage: with SETTING [VALUE] [-- COMMAND]
>   ....

Maybe help for an alias shouldn't show the original commands, but help
for "with" could usefully mention pp10.

Or maybe we should be smarter and show only the help for pp10 when
help for "print" was requested.

> Such an alias can now be documented by the user:
>   (gdb) document pp10
>   >Pretty printing an expressiong, printing 10 elements.
>   >Usage: pp10 [PRINT-COMMAND-OPTIONS] EXP
>   >See 'help print' for more information.
>   >end
>   (gdb) help pp10
>   Pretty printing an expressiong, printing 10 elements.
>   Usage: pp10 [PRINT-COMMAND-OPTIONS] EXP
>   See 'help print' for more information.
>   (gdb)
> 
> When a user-defined alias is documented specifically, help and apropos
> use the provided alias documentation instead of the documentation of
> the aliased command.
> 
> Such a documented alias is also not shown anymore in the help of the
> aliased command, and the alias is not listed anymore in the help
> of the aliased command.

When you say "such a documented alias", do you mean that by just
documenting the alias has this effect?  IMO, this could be too
far-fetched.  How about adding some specific attribute of the command
to that effect, instead of re-purposing the documentation attribute?

> +(@pxref{Command aliases default args,}).
                                       ^
That comma should be deleted.

The documentation parts are OK, assuming that the implementation is
accepted.

Thanks.

Re: [RFA] Allow to document user-defined aliases.

[Philippe Waroquiers via Gdb-patches]

On Mon, 2022-07-25 at 14:24 +0300, Eli Zaretskii wrote:
> > Date: Mon, 25 Jul 2022 06:11:13 +0200
> > From: Philippe Waroquiers via Gdb-patches <gdb-patches@sourceware.org>
> > 
> > When using 'help ALIASNAME', GDB shows the help of the aliased command.
> > This is a good default behaviour.
> > 
> > However, GDB alias command allows to define aliases with arguments
> > possibly changing or tuning significantly the behaviour of
> > the aliased command.  In such a case, showing the help of the aliased
> > command might not be ideal.
> 
> But it doesn't do much harm, either.  Moreover, it is useful to tell
> the user that some handy aliases exist related to the command.
The idea/reasoning is that if the user documents specifically the alias,
it means that the alias is not properly documented by the doc of the
aliased command.
It is for sure trivial to still show the alias definition in the 
list of aliases of the aliased command, but at work, this currently results
already in quite a long list of aliases for the with command, with little
value:
   (gdb) help btf
   with, Wmay-call-function, Wunlimited, Wada, Wc, scan-every-of-type, scan-args-of-type,
   scan-locals-of-type, btf, bts, btS, w
     alias Wmay-call-function = with may-call-functions --
     alias Wunlimited = with max-value-size unlimited -- with annotate 0 -- with print
   elements unlimited --
     alias Wada = with language ada -- with annotate 0 --
     alias Wc = with language c -- with annotate 0 --
     alias scan-every-of-type = with annotate 0 --     with print frame-info short-location 
   -- with print frame-arguments presence -- with print address off --       frame apply all
   -s info-args-and-locals-matching-type
     alias scan-args-of-type = with annotate 0 --     with print frame-info short-location  -
   - with print frame-arguments presence -- with print address off --       frame apply all -
   s info args -q -t
     alias scan-locals-of-type = with annotate 0 --     with print frame-info short-location
   -- with print frame-arguments presence -- with print address off --       frame apply all
   -s info local -q -t
     alias btf = with print address off -- with filename-display basename --     backtrace -
   full
     alias bts = with print address off -- with filename-display basename --     backtrace -
   entry-values no -frame-arguments presence -frame-info location
     alias btS = with print address off --     backtrace -entry-values no -frame-arguments
   presence -frame-info short-location
   Temporarily set SETTING to VALUE, run COMMAND, and restore SETTING.
   Usage: with SETTING [VALUE] [-- COMMAND]
   Usage: w SETTING [VALUE] [-- COMMAND]
   With no COMMAND, repeats the last executed command.
   
   SETTING is any setting you can change with the "set" subcommands.
   E.g.:
     with language pascal -- print obj
     with print elements unlimited -- print obj
   
   You can change multiple settings using nested with, and use
   abbreviations for commands and/or values.  E.g.:
     w la p -- w p el u -- p obj
   (gdb)
   

The long list of long aliases clutters the help of 'with' and confuses
the reader. E.g. btf is really doing a backtrace, but looks like it is a 'with command'.
The idea is that all these aliases will be documented, and then should not clutter anymore
the 'with' help.

Note that currently, when showing the help for a documented alias, the alias
definition is not shown. It would be easy to show the alias documentation
and its definition.

> 
> > This is particularly true when defining an alias as a set of
> > nested 'with' followed by a last command to launch, such as:
> >   (gdb) alias pp10 = with print pretty -- with print elements 10 -- print
> > Asking 'help pp10' shows the help of the 'with' command, which is
> > not particularly useful:
> >   (gdb) help pp10
> >   with, pp10, w
> >     alias pp10 = with print pretty -- with print elements 10 -- print
> >   Temporarily set SETTING to VALUE, run COMMAND, and restore SETTING.
> >   Usage: with SETTING [VALUE] [-- COMMAND]
> >   ....
> 
> Maybe help for an alias shouldn't show the original commands, but help
> for "with" could usefully mention pp10.
That is in fact the current behaviour, which I find confusing (see above the
help for 'btf' at work, showing in fact the help of 'with' with a bunch
of aliases that in reality are very different of a 'with' command.

> 
> Or maybe we should be smarter and show only the help for pp10 when
> help for "print" was requested.
Sadly, this seems not easy to do/not really doable. The problem is that GDB cli
is not cleanly implemented in a parsing phase followed by an execution phase.
Parsing a command is mixed with executing the command.
Also, more sadly, it is possible to define an alias that is using some other
not yet defined commands, for example:
   (gdb) alias thread-apply-all-foo = thread apply all foo
   (gdb) define foo
   Type commands for definition of "foo".
   End with a line saying just "end".
   >next
   >end

So, discovering the real command that an alias launches/will launch is IMO not doable
without significant/major rework of all the command parsing.


> 
> > Such an alias can now be documented by the user:
> >   (gdb) document pp10
> >   >Pretty printing an expressiong, printing 10 elements.
> >   >Usage: pp10 [PRINT-COMMAND-OPTIONS] EXP
> >   >See 'help print' for more information.
> >   >end
> >   (gdb) help pp10
> >   Pretty printing an expressiong, printing 10 elements.
> >   Usage: pp10 [PRINT-COMMAND-OPTIONS] EXP
> >   See 'help print' for more information.
> >   (gdb)
> > 
> > When a user-defined alias is documented specifically, help and apropos
> > use the provided alias documentation instead of the documentation of
> > the aliased command.
> > 
> > Such a documented alias is also not shown anymore in the help of the
> > aliased command, and the alias is not listed anymore in the help
> > of the aliased command.
> 
> When you say "such a documented alias", do you mean that by just
> documenting the alias has this effect?  IMO, this could be too
> far-fetched.  How about adding some specific attribute of the command
> to that effect, instead of re-purposing the documentation attribute?
Effectively, the idea is that giving a specific documentation to an alias
makes it a "first class/independent" command.
IIUC, what you suggest is to add e.g. an option -s (for standalone)
to the alias command. When -s is given, then the alias would not be
shown in the list of aliases of the aliased command.

That is another way to ensure e.g. that the 'help with' is not cluttered
with plenty of not relevant aliases.
But I found the indication given by the specific alias doc reasonable/simple enough
and intuitive.

I can for sure implement the alias -s option if there is an agreement
that this is better.

Thanks
Philippe


> 
> > +(@pxref{Command aliases default args,}).
>                                        ^
> That comma should be deleted.
Will fix in the next patch version.
> 
> The documentation parts are OK, assuming that the implementation is
> accepted.
> 
> Thanks.

Thanks for the (as usual) quick and good review.

Philippe

Re: [RFA] Allow to document user-defined aliases.

[Eli Zaretskii via Gdb-patches]

> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: gdb-patches@sourceware.org
> Date: Mon, 25 Jul 2022 22:35:45 +0200
> 
> > But it doesn't do much harm, either.  Moreover, it is useful to tell
> > the user that some handy aliases exist related to the command.
> The idea/reasoning is that if the user documents specifically the alias,
> it means that the alias is not properly documented by the doc of the
> aliased command.

I'm questioning the over-reaching validity of this assumption.  I
understand that this would be your logic, but I'm asking whether some
other GDB users could have a different perspective on this.

> I can for sure implement the alias -s option if there is an agreement
> that this is better.

Let's see what others think.  Mine is just one opinion.

Thanks.

Re: [RFA] Allow to document user-defined aliases.

[Tom Tromey]

>>>>> "Philippe" == Philippe Waroquiers via Gdb-patches <gdb-patches@sourceware.org> writes:

Philippe> When using 'help ALIASNAME', GDB shows the help of the aliased command.
Philippe> This is a good default behaviour.

Philippe> However, GDB alias command allows to define aliases with arguments
Philippe> possibly changing or tuning significantly the behaviour of
Philippe> the aliased command.  In such a case, showing the help of the aliased
Philippe> command might not be ideal.
[...]
Philippe> When a user-defined alias is documented specifically, help and apropos
Philippe> use the provided alias documentation instead of the documentation of
Philippe> the aliased command.

This makes sense to me.  My perspective is that the way a command is
defined (there are 4 or 5 ways now) isn't as important as what it does,
and users are normally interested in the latter.

One question I have is whether there is any way to see how the command
is defined, if it is documented.  For  commands  using "define" there is
"show user-defined"... perhaps that ought to be made to work with
aliases as well.

Tom

Re: [RFA] Allow to document user-defined aliases.

[Tom Tromey]

>>>>> "Philippe" == Philippe Waroquiers via Gdb-patches <gdb-patches@sourceware.org> writes:

Forgot to do the review bits.

Philippe> +  return alias.doc_allocated
Philippe> +    && strcmp (alias.doc, alias.alias_target->doc) != 0;

Needs parens.

Philippe> +  if (alias == nullptr || ! user_documented_alias (*alias))

No space after "!" in gdb.

Philippe> +/* Document a user-defined command or user defined alias.  If COMMANDS is NULL, then this is a

Line too long now.

Tom

Re: [RFA] Allow to document user-defined aliases.

[Philippe Waroquiers via Gdb-patches]

On Thu, 2022-08-04 at 13:12 -0600, Tom Tromey wrote:
> > > > > > "Philippe" == Philippe Waroquiers via Gdb-patches <gdb-patches@sourceware.org>
> > > > > > writes:
> 
> Philippe> When using 'help ALIASNAME', GDB shows the help of the aliased command.
> Philippe> This is a good default behaviour.
> 
> Philippe> However, GDB alias command allows to define aliases with arguments
> Philippe> possibly changing or tuning significantly the behaviour of
> Philippe> the aliased command.  In such a case, showing the help of the aliased
> Philippe> command might not be ideal.
> [...]
> Philippe> When a user-defined alias is documented specifically, help and apropos
> Philippe> use the provided alias documentation instead of the documentation of
> Philippe> the aliased command.
> 
> This makes sense to me.  My perspective is that the way a command is
> defined (there are 4 or 5 ways now) isn't as important as what it does,
> and users are normally interested in the latter.
Ok, let's start on this basis.
In any case, if one day, we really still want to make an alias appear
in the list of aliases of the aliased command, we can add an option
to the alias command such as:
  -l  list this alias in the aliased command help even if it has its own documentation.

> 
> One question I have is whether there is any way to see how the command
> is defined, if it is documented.  For  commands  using "define" there is
> "show user-defined"... perhaps that ought to be made to work with
> aliases as well.

The command 'help aliases' show the user defined aliases.
However, I think that when doing 'help for-a-user-documented-alias',
it would be better to still show the alias definition.

I will produce an RFA v2 with the above change, and also fixing the comments
you have given in the other mail.

Thanks for the review.

Philippe