Re: [PATCH v1 02/36] Guile extension language: doc additions

[Doug Evans <xdje42@gmail.com>]

On Sun, Jan 19, 2014 at 8:57 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Sat, 18 Jan 2014 12:53:11 -0800
>> From: Doug Evans <xdje42@gmail.com>
>> Cc: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
>>
>> On Sat, Jan 18, 2014 at 12:24 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> >> Date: Sat, 18 Jan 2014 12:06:46 -0800
>> >> From: Doug Evans <xdje42@gmail.com>
>> >> Cc: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
>> >>
>> >> >> +@value{GDBN} is not thread-safe.  If your Guile program uses multiple
>> >> >> +threads, you must be careful to only call @value{GDBN}-specific
>> >> >> +functions in the main @value{GDBN} thread.
>> >> >
>> >> > What is "the main GDB thread" here?
>> >>
>> >> I think the current wording is sufficient.
>> >
>> > My pointy was that GDB, AFAIK, is single threaded.  So talking about
>> > "the main GDB thread" creates an illusion that there are other "GDB
>> > threads", which I think don't exist.
>>
>> I could say "the main thread" since that's where GDB "lives".
>
> How about "the GDB thread"?

Done.

>> >> >> +A Scheme boolean is converted to @var{type} if provided, otherwise
>> >> >
>> >> > You already described how "type" is handled, no need to repeat that
>> >> > (here and elsewhere in this part).
>> >>
>> >> If a type is not provided I need to say what happens and it's
>> >> different for each kind of value.
>> >> It's not clear to me how to distinguish the two cases in prose without
>> >> having something like the text that is there now.
>> >> Suggestions?
>> >
>> > Which two cases?  (I've read the original way too long ago to
>> > remember.)
>>
>> case 1: the type is not provided and a default must be chosen
>>
>> case 2: the type is provided
>
> Case 2 was already explained before this text:
>
>   +@defun make-value value @r{[}#:type type@r{]}
>   +Many Scheme values can be converted directly to a @code{<gdb:value>} via
>   +with this procedure.  If @var{type} is specified, the result is a value
>   +of this type, and if @var{value} can't be represented with this type
>   +an exception is thrown.  Otherwise the type of the result is determined from
>   +@var{value} as described below.
>
> So all is left is to describe Case 1.  Therefore, I suggest to replace
>
>   +The following Scheme objects are accepted for @var{value}:
>
> with
>
>   Here's how Scheme values are converted when @var{type} argument to
>   @code{make-value} is not specified:
>
> and then rephrase the information about the specific types like this:
>
>   @table @asis
>   @item Scheme boolean
>   A Scheme boolean is converted to the boolean type of the current
>   language.
>
>   @item Scheme integer
>   A Scheme integer is converted to the first of a C @code{int}, ...
>
> etc., you get the idea.

Done.

>> >> >> +@findex TYPE_CODE_INTERNAL_FUNCTION
>> >> >> +@item TYPE_CODE_INTERNAL_FUNCTION
>> >> >> +A function internal to @value{GDBN}.  This is the type used to represent
>> >> >> +convenience functions.
>> >> >
>> >> > A cross-reference to where convenience functions are described would
>> >> > be nice here.
>> >>
>> >> Righto.  But that needs to wait until support for convenience
>> >> functions is implemented.
>> >
>> > I thought we already had them in GDB.
>>
>> GDB does, but there's no access to them yet from Guile.
>> When that is provided the cross-reference should point there.
>
> I meant a cross-reference to where GDB convenience functions are
> described, in case the reader isn't familiar with the concept, or
> wants to refresh her memory for some reason.

Done.