From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Kevin Ryde Newsgroups: gmane.lisp.guile.devel Subject: Re: Socket API improvement, patch #6 Date: Thu, 03 Nov 2005 07:07:49 +1100 Message-ID: <87sluedd9m.fsf@zip.com.au> References: <87oecutxox.fsf@laas.fr> <87vf58cxxq.fsf@zagadka.de> <87k6kwopv5.fsf@laas.fr> <87fysk7ady.fsf@zagadka.de> <87mzmpmcm2.fsf@laas.fr> <87aci6u6f4.fsf@laas.fr> <87psr22c2p.fsf@zip.com.au> <87irwtqkop.fsf@laas.fr> <87slvog9sd.fsf@zip.com.au> <87wtkt9xyq.fsf_-_@laas.fr> <87hdbg4dl7.fsf@laas.fr> <87br1nakge.fsf@zip.com.au> <87hdbfnu9n.fsf@laas.fr> <87d5m2twaf.fsf@uni-dortmund.de> <878xwjb123.fsf@laas.fr> <874q76h9rh.fsf@zip.com.au> <87hdb5qogp.fsf@zagadka.de> <87zmovn4y5.fsf@zip.com.au> <87fyqn1gzy.fsf@laas.fr> <87br196yd8.fsf@zip.com.au> <8764rbz5lt.fsf@laas.fr> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: quoted-printable X-Trace: sea.gmane.org 1130962180 23242 80.91.229.2 (2 Nov 2005 20:09:40 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 2 Nov 2005 20:09:40 +0000 (UTC) Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Wed Nov 02 21:09:38 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1EXOuH-0006kC-6f for guile-devel@m.gmane.org; Wed, 02 Nov 2005 21:08:25 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1EXOuF-0000QK-Fr for guile-devel@m.gmane.org; Wed, 02 Nov 2005 15:08:23 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1EXOuB-0000Pw-26 for guile-devel@gnu.org; Wed, 02 Nov 2005 15:08:19 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1EXOu9-0000Pk-0f for guile-devel@gnu.org; Wed, 02 Nov 2005 15:08:18 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1EXOu8-0000Ph-TX for guile-devel@gnu.org; Wed, 02 Nov 2005 15:08:16 -0500 Original-Received: from [61.8.0.84] (helo=mailout1.pacific.net.au) by monty-python.gnu.org with esmtp (Exim 4.34) id 1EXOu8-0001Nh-Gw for guile-devel@gnu.org; Wed, 02 Nov 2005 15:08:17 -0500 Original-Received: from mailproxy1.pacific.net.au (mailproxy1.pacific.net.au [61.8.0.86]) by mailout1.pacific.net.au (8.13.4/8.13.4/Debian-3) with ESMTP id jA2K8ALK028460 for ; Thu, 3 Nov 2005 07:08:10 +1100 Original-Received: from localhost (ppp22C6.dyn.pacific.net.au [61.8.34.198]) by mailproxy1.pacific.net.au (8.13.4/8.13.4/Debian-3) with ESMTP id jA2K89oJ024904 for ; Thu, 3 Nov 2005 07:08:09 +1100 Original-Received: from gg by localhost with local (Exim 3.36 #1 (Debian)) id 1EXOth-0000yQ-00; Thu, 03 Nov 2005 07:07:49 +1100 Original-To: guile-devel@gnu.org Mail-Copies-To: never In-Reply-To: <8764rbz5lt.fsf@laas.fr> (Ludovic =?iso-8859-1?Q?Court=E8s's?= message of "Wed, 02 Nov 2005 11:50:06 +0100") User-Agent: Gnus/5.110004 (No Gnus v0.4) Emacs/21.4 (gnu/linux) X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.devel:5372 Archived-At: ludovic.courtes@laas.fr (Ludovic Court=E8s) writes: > > Ok, I'm nitpicking: My rationale below. > structure that reflects "reflects" is not a good word. > @var{address}, an address of family @var{family}, with the > family-specific parameters @var{args} (see the description of > @var{make-socket-address} for details). I felt all this could be left as a ref to scm_make_socket_address. > On success, a non-@code{NULL} It's always non-NULL, no need to say that. > @var{address_size} is updated I changed the name and tried to make it clearer that it's an output. "updated" might make you think it was some value then changed to another. > The returned structure must eventually be freed using > @code{free ()}. I thought "eventually" was a clumsy expression. What I replaced it with might stand further polish though. > "formal" declarative style A manual is not a specification (fortunately), so there's no need to be overly formal. A manual, even a reference manual, is essentially a teaching tool, you want a programmer reading it to learn what a func does, or refresh their memory of what it does. On that basis some informality in expression is fine, though you definitely need the ideas presented in a nice logical sequence. (Which for me means the key point or points first, followed by gory details or exceptions.) _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://lists.gnu.org/mailman/listinfo/guile-devel