Re: comments in getdelim.h

[Simon Josefsson]

Bruno Haible <address@hidden> writes:

> Hi Simon,
>
> May I add comments to getdelim.h?

Hi!  There is one in getdelim.c already.  Maybe remove it?  I'm not
sure what the policy is on placing function documentation, although I
usually keep them with the actual function.

Or we could have two function descripts, one in getdelim.c and one in
getdelim.h, I don't mind.

Perhaps we could discuss this generally, agree on a principle on
document it?  My preference is as above, but it is not a strong one.

(The reason for my preference is GTK-DOC blocks, they are pretty
complete and discuss return values and stuff, somewhat more formally
than the current gnulib-style docstrings, and I've find that it makes
more sense to have them with the function, or else you'll wonder what
the function does every time you read the code.)

> Bruno
>
>
> *** gnulib-20060430/lib/getdelim.h    2005-08-02 11:33:30.000000000 +0200
> --- gnulib-20060430-modified/lib/getdelim.h   2006-05-01 17:07:54.000000000 
> +0200
> ***************
> *** 1,5 ****
>   /* getdelim.h --- Prototype for replacement getdelim function.
> !    Copyright (C) 2005 Free Software Foundation, Inc.
>   
>      This program is free software; you can redistribute it and/or
>      modify it under the terms of the GNU General Public License as
> --- 1,5 ----
>   /* getdelim.h --- Prototype for replacement getdelim function.
> !    Copyright (C) 2005-2006 Free Software Foundation, Inc.
>   
>      This program is free software; you can redistribute it and/or
>      modify it under the terms of the GNU General Public License as
> ***************
> *** 19,28 ****
>   /* Written by Simon Josefsson. */
>   
>   /* Get size_t, FILE, ssize_t.  And getdelim, if available.  */
> ! # include <stddef.h>
> ! # include <stdio.h>
> ! # include <sys/types.h>
>   
>   #if !HAVE_DECL_GETDELIM
> ! ssize_t getdelim (char **lineptr, size_t *n, int delimiter, FILE *stream);
> ! #endif /* !HAVE_GETDELIM */
> --- 19,35 ----
>   /* Written by Simon Josefsson. */
>   
>   /* Get size_t, FILE, ssize_t.  And getdelim, if available.  */
> ! #include <stddef.h>
> ! #include <stdio.h>
> ! #include <sys/types.h>
>   
>   #if !HAVE_DECL_GETDELIM
> ! /* Read input, up to (and including) the next occurrence of DELIMITER, from
> !    STREAM, store it in *LINEPTR (and NUL-terminate it).
> !    *LINEPTR is a pointer returned from malloc (or NULL), pointing to 
> *LINESIZE
> !    bytes of space.  It is realloc'd as necessary.
> !    Return the number of bytes read and stored at *LINEPTR (not including the
> !    NUL terminator), or -1 on error or EOF.  */
> ! extern ssize_t getdelim (char **lineptr, size_t *linesize, int delimiter,
> !                      FILE *stream);
> ! #endif /* !HAVE_DECL_GETDELIM */