[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Socket API improvement, patch #6
From: |
Kevin Ryde |
Subject: |
Re: Socket API improvement, patch #6 |
Date: |
Thu, 03 Nov 2005 07:07:49 +1100 |
User-agent: |
Gnus/5.110004 (No Gnus v0.4) Emacs/21.4 (gnu/linux) |
address@hidden (Ludovic Courtès) 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 address@hidden
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.)