Re: [PATCH] Allow user-defined as a category for python gdb macros (resend)

[Doug Evans <dje at google dot com>]

Hi.  Sorry for the delay.  I recommend one documentation tweak, but
other than that this patch is ok with me.

On Wed, Feb 15, 2012 at 1:14 AM, Scott Goldman <scottjg@vmware.com> wrote:
> Hi Phil, Eli, Doug.
>
> Thanks for the feedback. I adjusted the changelog, added a test case, and updated the documentation as per your suggestions.
>
>> [Doug]
>> The documentation needs to make clear that "user" means "those
>> commands defined in class_user" and not any command defined by the
>> user.
>
> I think I understand what you're saying. I suppose the distinction is that `help user-defined` may now show python commands in addition to what are traditionally known as user-defined commands. I updated the documentation to reflect this. I no longer use the phrase "user-defined python commands", instead I refer to commands as "user-defined commands" or "python commands". I also clarified that `help user-defined` may also show python commands that were declared under COMMAND_USER. Hopefully that's what you had in mind. Any further suggestions on how you'd like the doc reworked are welcome.
>
> -sjg
>
>
> gdb/doc/ChangeLog
> 2012-02-15 ?Scott J. Goldman <scottjg@vmware.com>
>
> ? ? ? ?* gdb.texinfo (Commands In Python): Put example python macro in
> ? ? ? ?COMMAND_USER category rather than COMMAND_OBSCURE.
> ? ? ? ?(User-defined Commands) : Update documentation to clarify
> ? ? ? ?`set/show max-user-call-depth` and `show user` don't apply to python
> ? ? ? ? commands.
> ? ? ? ?(User-defined Commands) : Update documentation to clarify
> ? ? ? `help user-defined` may also include python commands defined as
> ? ? ? ?COMMAND_USER
>
> gdb/ChangLog
> 2012-02-15 ?Scott J. Goldman <scottjg@vmware.com>
>
> ? ? ? ?* cli/cli-cmds.c (show_user): Print error when used on a python command.
> ? ? ? ?(init_cli_cmds): Update documentation strings for `show user` and
> ? ? ? ?`set/show max-user-call-depth` to clarify that it does not apply to
> ? ? ? ?python commands.
> ? ? ? ?* python/py-cmd.c (cmdpy_init): Treat class_user as a valid class in error
> ? ? ? ?check
> ? ? ? ?(gdbpy_initialize_commands): Add COMMAND_USER as a constant in
> ? ? ? ?gdb python api.
> ? ? ? ?* top.c (execute_command): Only execute a user-defined command as a
> ? ? ? ?legacy macro if c->user_commands is set.
>
> gdb/testsuite/ChangeLog
> 2012-02-15 ?Scott J. Goldman <scottjg@vmware.com>
>
> ? ? ? ?* gdb.python/py-cmd.exp: Add test to verify that python commands can
> ? ? ? ?be put in the user-defined category and that the commands appear in
> ? ? ? `help user-defined`.
>
> diff --git a/gdb/cli/cli-cmds.c b/gdb/cli/cli-cmds.c
> index 983f017..49808b6 100644
> --- a/gdb/cli/cli-cmds.c
> +++ b/gdb/cli/cli-cmds.c
> @@ -1241,7 +1241,8 @@ show_user (char *args, int from_tty)
> ? ? ? char *comname = args;
>
> ? ? ? c = lookup_cmd (&comname, cmdlist, "", 0, 1);
> - ? ? ?if (c->class != class_user)
> + ? ? ?/* c->user_commands would be NULL if it's a python command */
> + ? ? ?if (c->class != class_user || !c->user_commands)
> ? ? ? ?error (_("Not a user command."));
> ? ? ? show_user_1 (c, "", args, gdb_stdout);
> ? ? }
> @@ -1912,7 +1913,7 @@ Two arguments (separated by a comma) are taken as a range of memory to dump,\n\
> ?Run the ``make'' program using the rest of the line as arguments."));
> ? set_cmd_completer (c, filename_completer);
> ? add_cmd ("user", no_class, show_user, _("\
> -Show definitions of user defined commands.\n\
> +Show definitions of non-python user defined commands.\n\
> ?Argument is the name of the user defined command.\n\
> ?With no argument, show definitions of all user defined commands."), &showlist);
> ? add_com ("apropos", class_support, apropos_command,
> @@ -1920,8 +1921,8 @@ With no argument, show definitions of all user defined commands."), &showlist);
>
> ? add_setshow_integer_cmd ("max-user-call-depth", no_class,
> ? ? ? ? ? ? ? ? ? ? ? ? ? &max_user_call_depth, _("\
> -Set the max call depth for user-defined commands."), _("\
> -Show the max call depth for user-defined commands."), NULL,
> +Set the max call depth for non-python user-defined commands."), _("\
> +Show the max call depth for non-python user-defined commands."), NULL,
> ? ? ? ? ? ? ? ? ? ? ? ? ? NULL,
> ? ? ? ? ? ? ? ? ? ? ? ? ? show_max_user_call_depth,
> ? ? ? ? ? ? ? ? ? ? ? ? ? &setlist, &showlist);
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index 9edc6ad..302c203 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -21054,14 +21054,16 @@ command should not be repeated when the user hits @key{RET}
> ?@kindex help user-defined
> ?@item help user-defined
> ?List all user-defined commands, with the first line of the documentation
> -(if any) for each.
> +(if any) for each. This may include python commands as well, if they were
> +defined under the COMMAND_USER class.

I would change this to something like:

List all user-defined commands and all python commands defined in
class COMMAND_USER.  For user-defined commands, the first line of the
documentation (if any) is included.