From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <gdb-patches-return-74787-listarch-gdb-patches=sources.redhat.com@sourceware.org>
Received: (qmail 28123 invoked by alias); 6 Aug 2010 15:36:12 -0000
Received: (qmail 28056 invoked by uid 22791); 6 Aug 2010 15:36:10 -0000
X-SWARE-Spam-Status: No, hits=-0.7 required=5.0	tests=AWL,BAYES_00,SPF_SOFTFAIL
X-Spam-Check-By: sourceware.org
Received: from mtaout20.012.net.il (HELO mtaout20.012.net.il) (80.179.55.166)    by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Fri, 06 Aug 2010 15:35:33 +0000
Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0L6Q00K00LVBNM00@a-mtaout20.012.net.il> for gdb-patches@sourceware.org; Fri, 06 Aug 2010 18:34:06 +0300 (IDT)
Received: from HOME-C4E4A596F7 ([77.126.102.143]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0L6Q00KR0LWTC420@a-mtaout20.012.net.il>; Fri, 06 Aug 2010 18:34:06 +0300 (IDT)
Date: Fri, 06 Aug 2010 15:36:00 -0000
From: Eli Zaretskii <eliz@gnu.org>
Subject: Re: [patch] Add solib_address and decode_line Python functionality
In-reply-to: <4C5C1418.7030607@redhat.com>
To: Phil Muldoon <pmuldoon@redhat.com>
Cc: tromey@redhat.com, brobecker@adacore.com, gdb-patches@sourceware.org
Reply-to: Eli Zaretskii <eliz@gnu.org>
Message-id: <83hbj7wyaa.fsf@gnu.org>
References: <4C44728D.4040408@redhat.com> <20100727162545.GF13267@adacore.com> <4C5015E2.4000205@redhat.com> <m3fwz2ja5v.fsf@fleche.redhat.com> <4C5C1418.7030607@redhat.com>
X-IsSubscribed: yes
Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm
Precedence: bulk
List-Id: <gdb-patches.sourceware.org>
List-Subscribe: <mailto:gdb-patches-subscribe@sourceware.org>
List-Archive: <http://sourceware.org/ml/gdb-patches/>
List-Post: <mailto:gdb-patches@sourceware.org>
List-Help: <mailto:gdb-patches-help@sourceware.org>, <http://sourceware.org/ml/#faqs>
Sender: gdb-patches-owner@sourceware.org
X-SW-Source: 2010-08/txt/msg00069.txt.bz2

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