Re: [PATCH, doc RFA]: Add guile progspace support

[Doug Evans <xdje42@gmail.com>]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Doug Evans <xdje42@gmail.com>
>> Date: Wed, 21 May 2014 12:22:20 -0700
>> 
>> This patch adds guile progspace support.
>
> Thanks.
>
>> +@deffn {Scheme Procedure} progspace-filename progspace
>> +Return the file name of @var{progspace} as a string.
>> +If the program space does not have an associated file name,
>> +then @code{#f} is returned.  This occurs, for example, when @value{GDBN}
>> +is started without a program to debug.
>
> I guess this is the file name of the executable program running in the
> progspace?  If so, why not tell that explicitly?  This text as written
> begs the question what file is named by that string.  Also, is the
> file absolute, relative, something else?  Is it just the value of
> argv[0] in that program?  Etc. etc.

How about this?

+@deffn {Scheme Procedure} progspace-filename progspace
+Return the file name of @var{progspace} as a string,
+as an absolute path.
+This is the name of file passed as the argument to the @code{file}
+or @code{symbol-file} commands.
+If the program space does not have an associated file name,
+then @code{#f} is returned.  This occurs, for example, when @value{GDBN}
+is started without a program to debug.
+
+A @code{gdb:invalid-object-error} exception is thrown if @var{progspace}
+is invalid.
+@end deffn

>> +A @code{gdb:invalid-object-error} exception is thrown if @var{PROGSPACE}
>> +is invalid.                                                   ^^^^^^^^^
>
> "progspace", in lower case.

Fixed.

>> +@deffn {Scheme Procedure} progspace-objfiles progspace
>> +Return the list of objfiles of @var{progspace}.
>> +The order of objfiles in the result is arbitrary.
>
> "Arbitrary" or in the same order they are stored in some symbol table?

Arbitrary.
gdb makes no promises to the user regarding the order.

>> +A @code{gdb:invalid-object-error} exception is thrown if @var{PROGSPACE}
>> +is invalid.                                                   ^^^^^^^^^
>
> "progspace" in lower case.

Fixed.