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

[Doug Evans]

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".
Though one can imagine an app dlopen'ing gdb itself and in such a case
it's not clear to me gdb has to be run in the "main" thread, just as
long as it is always run in the same thread (until gdb becomes
multithreaded of course).

Thus I'm not sure what to say that isn't equivalent to what's already there.
Suggestions are welcome of course.

>> >> +By default, any output produced by @var{command} is sent to
>> >> +@value{GDBN}'s standard output.
>> >
>> > What happens if logging has been turned on?
>>
>> It's handled no different than typing the command into gdb.
>> Do we need to say more here?
>
> I would add "(and to the log output if logging is turned on)".

Ok.

>> >> +@emph{Note:} @value{GDBN}'s value history is independent of Guile's.
>> >> +@code{$1} in @value{GDBN}'s value history is not @code{$1} from Guile's
>> >> +history, nor is the reverse true.
>> >
>> > See comment about this above.  Also, which history are you talking
>> > about here: the one from Guile evaluation or the one from GDB?
>>
>> Not sure I understand, the text refers to both.
>> $1 when used in a Scheme expression is not the same value as $1 used
>> in a GDB expression.
>> I'm happy to reword this as desired, I'm just not sure what.
>
> Instead of that $1 is NOT, I suggest to say what it IS.

How about this?

@emph{Note:} @value{GDBN}'s value history is independent of Guile's.
@code{$1} in @value{GDBN}'s value history contains the result of evaluating
an expression from @value{GDBN}'s command line and @code{$1} from Guile's
history contains the result of evaluating an expression from Guile's
command line (@dfn{repl})

>> >> +@defun data-directory
>> >> +Return a string containing @value{GDBN}'s data directory.
>> >
>> > Should we mention that this string is in UTF-8 (I think) encoding?
>>
>> Strings don't have an encoding per se, they're sequences of unicode code points.
>
> ??? Are you saying the data directory is returned as a wchar_t array?

Unicode strings have an internal and an external representation.
Internally, they are represented using "code points".
It is only when strings are represented in an external representation
(e.g. written to a file) that the encoding comes into play.

>> [One needs to specify an encoding when reading/writing them to a file
>> or whatever of course.]
>
> If characters in a string are represented as UTF-8 sequences, saying
> that is a useful piece of information.
>
>> >> +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

>
>> >> +A Scheme string is converted to a target string, using the current
>> >> +target encoding.
>> >
>> > What if target encoding doesn't support some of the characters in the
>> > string?
>>
>> An exception is thrown.  I've added more text.
>> [It would be nice to provide some control here, for now the
>> conversion is strict.]
>
> Why do you need it to be strict?  You could replace un-encodable
> characters with '?', or a blank, or even omit them.  I think this is
> nicer than an exception.

A future patch can add the possibility of letting the user choose, but
for a default I prefer being strict.

OTOH, I see the default for Guile's port conversion strategy is "substitute".
It's the wrong choice IMO, but I can live with it.

>> >> +A similar function @code{value-referenced-value} exists which also
>> >> +returns @code{<gdb:value>} objects corresonding to the values pointed to
>> >> +by pointer values (and additionally, values referenced by reference
>> >> +values).  However, the behavior of @code{value-dereference}
>> >> +differs from @code{value-referenced-value} by the fact that the
>> >> +behavior of @code{value-dereference} is identical to applying the C
>> >> +unary operator @code{*} on a given value.  For example, consider a
>> >> +reference to a pointer @code{ptrref}, declared in your C@t{++} program
>> >> +as
>> >> +
>> >> +@smallexample
>> >> +typedef int *intptr;
>> >> +...
>> >> +int val = 10;
>> >> +intptr ptr = &val;
>> >> +intptr &ptrref = ptr;
>> >> +@end smallexample
>> >
>> > Here and below you describe 2 related functions, and explain how they
>> > are different twice, each explanation is part of its @defun.  This in
>> > effect says the same things twice slightly differently, and is thus
>> > confusing.
>> >
>> > Instead, I suggest to provide a concise description of both functions,
>> > and then explain their differences only once.
>>
>> It doesn't feel confusing to me.
>
> That's because you wrote it.  I've read it, and it confused me enough
> to have to read it the whole thing twice, before I understood it.

Not wanting to take credit where it's not due, I just copied the text
from the python text.

>> Plus it's nice to have each function's docs relatively self-contained.
>> Can I keep it as is for now?
>
> If you insist.

Thanks.

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