From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 20590 invoked by alias); 19 Jan 2014 21:01:38 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 20580 invoked by uid 89); 19 Jan 2014 21:01:37 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.4 required=5.0 tests=AWL,BAYES_00,FREEMAIL_ENVFROM_END_DIGIT,FREEMAIL_FROM,RCVD_IN_DNSWL_LOW,SPF_PASS autolearn=ham version=3.3.2 X-HELO: mail-wg0-f43.google.com Received: from mail-wg0-f43.google.com (HELO mail-wg0-f43.google.com) (74.125.82.43) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES128-SHA encrypted) ESMTPS; Sun, 19 Jan 2014 21:01:36 +0000 Received: by mail-wg0-f43.google.com with SMTP id y10so6296431wgg.10 for ; Sun, 19 Jan 2014 13:01:33 -0800 (PST) MIME-Version: 1.0 X-Received: by 10.181.13.40 with SMTP id ev8mr6360273wid.16.1390165293043; Sun, 19 Jan 2014 13:01:33 -0800 (PST) Received: by 10.194.17.104 with HTTP; Sun, 19 Jan 2014 13:01:32 -0800 (PST) In-Reply-To: <83y52bj4dk.fsf@gnu.org> References: <52b9da59.64ab440a.0b0b.7e1c@mx.google.com> <83ha9w68av.fsf@gnu.org> <83a9etjawt.fsf@gnu.org> <83y52bj4dk.fsf@gnu.org> Date: Sun, 19 Jan 2014 21:01:00 -0000 Message-ID: Subject: Re: [PATCH v1 02/36] Guile extension language: doc additions From: Doug Evans To: Eli Zaretskii Cc: "gdb-patches@sourceware.org" Content-Type: text/plain; charset=ISO-8859-1 X-IsSubscribed: yes X-SW-Source: 2014-01/txt/msg00724.txt.bz2 On Sun, Jan 19, 2014 at 8:57 AM, Eli Zaretskii wrote: >> Date: Sat, 18 Jan 2014 12:53:11 -0800 >> From: Doug Evans >> Cc: "gdb-patches@sourceware.org" >> >> On Sat, Jan 18, 2014 at 12:24 PM, Eli Zaretskii wrote: >> >> Date: Sat, 18 Jan 2014 12:06:46 -0800 >> >> From: Doug Evans >> >> Cc: "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{} 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.