Re: [RFC][python] Add support for commands implemented in Python

[Eli Zaretskii <eliz@gnu.org>]

> From: Thiago Jung Bauermann <bauerman@br.ibm.com>
> Date: Mon, 02 Feb 2009 11:13:25 -0200
> 
> gdb/doc/
> 2009-02-02  Tom Tromey  <tromey@redhat.com>
> 
> 	* gdb.texinfo (Python API): Add entry for Commands In Python.
> 	(Commands In Python): New node.

Approved, with comments:

> +The help text for the new command is taken from the Python
> +documentation string for the command's class, if there is one.  If
> +there is no documentation string, a default value is used.

Regarding the last sentence above: when I read this I asked myself
what was the default value for the doc string.  I suggest to state
that.

> +@defmethod Command complete text word
> +This method is called by @value{GDBN} when the user attempts @key{TAB}
> +completion on this command.

Only TAB, or the other completion-related keys? what about M-?, for
example?

> +@item COMMAND_RUN
> +The command is related to running the inferior.
> +
> +@findex COMMAND_VARS
> +@findex gdb.COMMAND_VARS
> +@item COMMAND_VARS
> +The command is related to variables.

I think it would be useful either to give a couple of examples of
existing CLI commands that belong to each class, or at least explain
how to use the "help" command to show commands in each class.  I
imagined myself sitting in front of this list and trying to figure out
to which class to assign some command I wrote, and I think I would
find these hints useful.  Please keep in mind that users who would
want to write new CLI commands are not necessarily GDB hackers privy
to the add_cmd function and its ilk.

> +@item COMMAND_FILES
> +This class is used for file-related commands.

Here's a case in point: many (most) GDB commands related to files
actually deal with _executable_ files.

> +@item COMMAND_SUPPORT

Another case in point: what is ``support facilities''?  Without an
example, it leaves me wondering.

Another question that was on my mind after reading this: what class is
for help commands?

> +A new command can use a predefined completion function, either by
> +specifying it via an argument at initialization, or by return it from
                                                          ^^^^^^
"returning"

> +@item COMPLETE_LOCATION
> +This constant means that location completion should be done.

A cross-reference to where "locations" are described would be a good
idea here.

Finally, I think we need a NEWS entry for this feature.