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

[Eli Zaretskii via Gdb-patches <gdb-patches@sourceware.org>]

> 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.