diff mbox

[3/3] python: Fix erroneous doc about gdb.objfiles()

Message ID 20180912193617.16523-3-simon.marchi@ericsson.com
State New, archived
Headers

Commit Message

Simon Marchi Sept. 12, 2018, 7:36 p.m. UTC 
  The code implementing gdb.objfiles() returns a list of objfiles for the
current program space (the program space of the selected inferior).  The
documentation for the gdb.objfiles() Python method, however, states:

    Return a sequence of all the objfiles current known to GDB.

That sounds wrong to me.  I tried to phrase to be more precise.

gdb/doc/ChangeLog:

	* python.texi (Objfiles In Python): Update gdb.objfiles() doc.
---
 gdb/doc/python.texi | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

Comments

Tom Tromey Sept. 12, 2018, 9:45 p.m. UTC | #1 
>>>>> "Simon" == Simon Marchi <simon.marchi@ericsson.com> writes:

Simon> +Return a sequence of objfiles for the current program space (and by extension,
Simon> +for the selected inferior) @xref{Objfiles In Python} and
Simon> +@pxref{Progspaces In Python}.

The 'by extension' text seems mildly confusing to me.
Maybe it could say something like:

    Return a sequence of all the objfiles referenced by this program
    space.  @xref{Objfiles In Python}.  Note that lThis is the same as the
    objfiles for the selected inferior.

Or something else equally direct?

Tom
Eli Zaretskii Sept. 13, 2018, 2:36 a.m. UTC | #2 
> From: Simon Marchi <simon.marchi@ericsson.com>
> CC: Simon Marchi <simon.marchi@ericsson.com>
> Date: Wed, 12 Sep 2018 15:36:17 -0400
> 
> diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
> index abda135e17d..a9de6bd815e 100644
> --- a/gdb/doc/python.texi
> +++ b/gdb/doc/python.texi
> @@ -4104,8 +4104,9 @@ this function returns @code{None}.
>  
>  @findex gdb.objfiles
>  @defun gdb.objfiles ()
> -Return a sequence of all the objfiles current known to @value{GDBN}.
> -@xref{Objfiles In Python}.
> +Return a sequence of objfiles for the current program space (and by extension,
> +for the selected inferior) @xref{Objfiles In Python} and
> +@pxref{Progspaces In Python}.
>  @end defun

"By extension" confuses me.  And there should be a period before @xref
and a comma after its closing brace.

Thanks.
Simon Marchi Sept. 13, 2018, 2:42 a.m. UTC | #3 
On 2018-09-12 22:36, Eli Zaretskii wrote:
>> From: Simon Marchi <simon.marchi@ericsson.com>
>> CC: Simon Marchi <simon.marchi@ericsson.com>
>> Date: Wed, 12 Sep 2018 15:36:17 -0400
>> 
>> diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
>> index abda135e17d..a9de6bd815e 100644
>> --- a/gdb/doc/python.texi
>> +++ b/gdb/doc/python.texi
>> @@ -4104,8 +4104,9 @@ this function returns @code{None}.
>> 
>>  @findex gdb.objfiles
>>  @defun gdb.objfiles ()
>> -Return a sequence of all the objfiles current known to @value{GDBN}.
>> -@xref{Objfiles In Python}.
>> +Return a sequence of objfiles for the current program space (and by 
>> extension,
>> +for the selected inferior) @xref{Objfiles In Python} and
>> +@pxref{Progspaces In Python}.
>>  @end defun
> 
> "By extension" confuses me.  And there should be a period before @xref
> and a comma after its closing brace.
> 
> Thanks.

Hi Eli,

This changed in the v2 I just sent 5 minutes ago :).

I stole the text from an old patch of Tom, which says

   This is identical to gdb.selected_inferior().progspace.objfiles() and 
is included for historical compatibility.

Which makes what I was trying to say here unnecessary.

Simon
diff mbox

Patch

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index abda135e17d..a9de6bd815e 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -4104,8 +4104,9 @@  this function returns @code{None}.
 
 @findex gdb.objfiles
 @defun gdb.objfiles ()
-Return a sequence of all the objfiles current known to @value{GDBN}.
-@xref{Objfiles In Python}.
+Return a sequence of objfiles for the current program space (and by extension,
+for the selected inferior) @xref{Objfiles In Python} and
+@pxref{Progspaces In Python}.
 @end defun
 
 @findex gdb.lookup_objfile