Re: [patch] Add solib_address and decode_line Python functionality

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Fri, 06 Aug 2010 14:54:32 +0100
> From: Phil Muldoon <pmuldoon@redhat.com>
> CC: Joel Brobecker <brobecker@adacore.com>,        gdb-patches ml <gdb-patches@sourceware.org>
> 
> +@findex gdb.decode_line
> +@defun decode_line @r{[}expression@r{]}
> +Decode the optional argument @var{expression} the way that
> +@value{GDBN}'s inbuilt @code{break} or @code{edit} commands do
> +(@pxref{Specify Location}).  This function returns a Python tuple
> +containing two elements.  The first element contains a string holding
> +any unparsed section of @var{expression} (or @code{None} if the
> +expression has been fully parsed).  The second element contains either
> +@code{None} or another tuple that contains all the locations that
> +match the expression represented as @code{gdb.Symtab_and_line} objects
> +(@pxref{Symbol Tables In Python}).  If @var{expression} is not
> +provided, the current location is returned.

This is okay, but I would suggest to explain what happens without the
argument first.  Readers shouldn't need to read all the description of
how the argument is parsed if they don't want to pass it.

Something like

  @findex gdb.decode_line
  @defun decode_line @r{[}expression@r{]}
  Return location of the line specified by @var{expression}, or of the
  current line if no argument was given.  This function returns a Python
  tuple containing two elements.  The first element contains a string
  holding any unparsed section of @var{expression} (or @code{None} if
  the expression has been fully parsed).  The second element contains
  either @code{None} or another tuple that contains all the locations
  that match the expression represented as @code{gdb.Symtab_and_line}
  objects (@pxref{Symbol Tables In Python}).  If @var{expression}
  provided, it is decoded the way that @value{GDBN}'s inbuilt
  @code{break} or @code{edit} commands do (@pxref{Specify Location}).

Thanks.