Re: Socket API improvement, patch #6

[Ludovic Courtès]

Hi,

Kevin Ryde <address@hidden> writes:

> Beaut, I gave it a bit of a tweak and applied it.

Ok, I'm nitpicking: basically, for function descriptions, I prefer the
style that I used rather than your style.  For instance, I suggested:

  @deftypefn {C Function} {struct sockaddr *}scm_c_make_socket_address (SCM 
family, SCM address, SCM args, size_t *address_size)
  Return a newly-allocated @code{sockaddr} structure that reflects
  @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).  On success, a address@hidden
  pointer is returned and @var{address_size} is updated to the actual
  size (in bytes) of the returned address.  The returned structure must
  eventually be freed using @code{free ()}.
  @end deftypefn

while you preferred:

  @deftypefn {C Function} {struct sockaddr *} scm_c_make_socket_address (SCM 
family, SCM address, SCM args, size_t *outsize)
  Return a address@hidden @code{struct sockaddr} created from
  arguments like those taken by @code{scm_make_socket_address} above.

  The size (in bytes) of the @code{struct sockaddr} return is stored
  into @address@hidden  An application must call @code{free} to
  release the returned structure when no longer required.
  @end deftypefn

IMO, the style you used is "sploppier" and less concise.  The "formal"
declarative style I used is also more consistent with the rest of the
manual and other GNU manuals as well I think.

Ludovic.