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

[Eli Zaretskii <eliz at gnu dot org>]

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

> >> +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)".

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

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

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

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

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

If you insist.

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