Re: [PATCH 5/5] gdb/python: document GDB/MI commands in Python

[Eli Zaretskii <eliz@gnu.org>]

> Date: Mon, 17 Jan 2022 12:44:25 +0000
> From: Jan Vrany via Gdb-patches <gdb-patches@sourceware.org>
> Cc: Jan Vrany <jan.vrany@labware.com>
> 
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -146,6 +146,8 @@ show debug lin-lwp
>    ** New function gdb.host_charset(), returns a string, which is the
>       name of the current host charset.
>  
> +  ** New GDB/MI commands can now be written in Python.

The "new" part here took me by surprise.  Why do we need it?

Or how about this rewording:

  ** It is now possible to add GDB/MI commands implemented in Python.

> +* GDB/MI Commands In Python::   Implementing new @sc{GDB/MI} commands in Python.
                                                    ^^^^^^^^^^^
The argument of @sc should be in lower case.

> +@cindex CLI commands in python
>  @cindex commands in python
>  @cindex python commands
>  You can implement new @value{GDBN} CLI commands in Python.  A CLI
> @@ -4092,6 +4095,71 @@ registration of the command with @value{GDBN}.  Depending on how the
>  Python code is read into @value{GDBN}, you may need to import the
>  @code{gdb} module explicitly.
>  
> +@node GDB/MI Commands In Python
> +@subsubsection @sc{GDB/MI} Commands In Python
> +
> +@cindex MI commands in python
> +@cindex commands in python
> +@cindex python commands

You've added a second copy of the last two index entries, without any
qualifier.  This will cause makeinfo to generate index entries
"commands in python" and "commands is python<2>", without giving the
reader any clue what is the difference between these two instances.

It is much better to qualify each instance with some unique
qualifier.  Here, I'd use ", CLI" and ", GDB/MI" as the qualifiers.

> +You can implement new @sc{GDB/MI} (@pxref{GDB/MI}) commands in Python.

Same comment as for the NEWS entry.  With a possibly similar solution.

> +@var{name} is the name of the command.  It must be a valid @sc{GDB/MI}
> +command and must start with hyphen (-).

What does "It must be a valid @sc{GDB/MI} command" mean here?  Did you
mean to say "It must be a valid @sc{GDB/MI} command name" instead?  If
so, I suggest

  It must be a valid name of a @sc{GDB/MI} command, and in particular
  must start with a hyphen (

> +@end defun
> +
> +@defun Command.invoke (arguments)
> +This method is called by @value{GDBN} when this command is invoked.
> +
> +@var{arguments} is a list of strings.  Note, that @code{--thread}
> +and @code{--frame} arguments are handled by @value{GDBN} itself therefore
> +they do not show up in @code{arguments}.
> +
> +If this method throws an exception, it is turned into a @sc{GDB/MI}
> +@code{^error} response.  Otherwise, the return value is converted
> +to @sc{GDB/MI} value (@pxref{GDB/MI Output Syntax}) as follows:
> +
> +@itemize
> +@item If the value is Python sequence or iterator, it is converted to
> +@sc{GDB/MI} @emph{list} with elements converted recursively.
> +
> +@item If the value is Python dictionary, it is converted to
> +@sc{GDB/MI} @emph{tuple}.  Keys in that dictionary must be strings.
> +Values are converted recursively.
> +
> +@item Otherwise, value is first converted to Python string using
> +@code{str ()} and then converted to @sc{GDB/MI} @emph{const}.
> +@end itemize
> +
> +@end defun
> +
> +The following code snippet shows how a trivial MI command can be
> +implemented in Python:
> +
> +@smallexample
> +class MIEcho(gdb.MICommand):
> +    """Echo parameters"""
> +
> +    def __init__ (self):
> +        super (MIEcho, self).__init__ ("-echo")
> +
> +    def invoke (self, argv):
> +        return @{'argv' : argv @}
> +
> +MIEcho ()
> +@end smallexample
> +
> +The last line instantiates the class, and is necessary to trigger the
> +registration of the command with @value{GDBN}.  Depending on how the
> +Python code is read into @value{GDBN}, you may need to import the
> +@code{gdb} module explicitly.
> +
>  @node Parameters In Python
>  @subsubsection Parameters In Python
>  
> @@ -4129,7 +4197,7 @@ If @var{name} consists of multiple words, and no prefix parameter group
>  can be found, an exception is raised.
>  
>  @var{command-class} should be one of the @samp{COMMAND_} constants
> -(@pxref{Commands In Python}).  This argument tells @value{GDBN} how to
> +(@pxref{CLI Commands In Python}).  This argument tells @value{GDBN} how to
>  categorize the new parameter in the help system.
>  
>  @var{parameter-class} should be one of the @samp{PARAM_} constants
> -- 
> 2.30.2
> 
>