Re: Socket API improvement, patch #6

[Kevin Ryde]

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