Re: Distributing C as headers.

From	David Brown <david.brown@hesbynett.no>
Newsgroups	comp.lang.c
Subject	Re: Distributing C as headers.
Date	2019-01-27 15:06 +0100
Organization	A noiseless patient Spider
Message-ID	<q2kdse$khs$1@dont-email.me> (permalink)
References	(4 earlier) <q2fli0$pb4$1@news.xmission.com> <1bh8dw2l5r.fsf@pfeifferfamily.net> <5c4c1691$0$21610$426a74cc@news.free.fr> <1bwomr17cp.fsf@pfeifferfamily.net> <5c4cca81$0$3535$426a74cc@news.free.fr>

Show all headers | View raw

On 26/01/2019 22:00, Mateusz Viste wrote:
> On Sat, 26 Jan 2019 13:39:34 -0700, Joe Pfeiffer wrote:
>> You really think
>>
>> /* Copy SRC to DEST.  */
>> extern char *strcpy (char *__restrict __dest, const char *__restrict
>> __src)
>>       __THROW __nonnull ((1, 2));
>>
>> is going to tell me more about strcpy than looking at the man page?
> 
> You picked a specific example. The libc documentation is awesomely
> accurate, and declarations tend to be messy. For such obviously standard
> things, documentation is the way to go. For anything less ubiquitous,
> looking at the header may provide very useful knowledge. This, for
> example, is an extract from the header file of the tinf library:
> 
> /**
>   * Decompress `sourceLen` bytes of deflate data from `source` to `dest`.
>   *
>   * The variable `destLen` points to must contain the size of `dest` on
>   * entry, and will be set to the size of the decompressed data on success.
>   *
>   * Reads at most `sourceLen` bytes from `source`.
>   * Writes at most `*destLen` bytes to `dest`.
>   *
>   * @param dest pointer to where to place decompressed data
>   * @param destLen pointer to variable containing size of `dest`
>   * @param source pointer to compressed data
>   * @param sourceLen size of compressed data
>   * @return `TINF_OK` on success, error code on error
>   */
> int TINFCC tinf_uncompress(void *dest, unsigned int *destLen,
> const void *source, unsigned int sourceLen);
> 
> Isn't it delicious?
> With proper headers, documentation becomes useless.
> 
> Mateusz
> 

With headers like that, documentation is still not useless - 
documentation can include overviews, examples, tutorials, etc., as well 
as the specifications of individual functions.  The code you quoted here 
looks like it is ready for doxygen, which is perhaps the ideal balance 
between headers and documentation.  Your headers have reasonable 
documentation in a convenient place, and you can automatically extract 
and generate fuller documentation in useful formats - guaranteed to be 
in sync with the actual code.

Thread

Distributing C as headers. Malcolm McLean <malcolm.arthur.mclean@gmail.com> - 2019-01-25 07:23 -0800
  Re: Distributing C as headers. Thiago Adams <thiago.adams@gmail.com> - 2019-01-25 07:31 -0800
    Re: Distributing C as headers. Malcolm McLean <malcolm.arthur.mclean@gmail.com> - 2019-01-25 07:33 -0800
      Re: Distributing C as headers. Mateusz Viste <mateusz@wont.tell> - 2019-01-25 15:42 +0000
      Re: Distributing C as headers. gazelle@shell.xmission.com (Kenny McCormack) - 2019-01-25 17:40 +0000
        Re: Distributing C as headers. Thiago Adams <thiago.adams@gmail.com> - 2019-01-25 09:59 -0800
          Re: Distributing C as headers. Thiago Adams <thiago.adams@gmail.com> - 2019-01-25 10:01 -0800
          Re: Distributing C as headers. David Brown <david.brown@hesbynett.no> - 2019-01-25 22:17 +0100
            Re: Distributing C as headers. Bart <bc@freeuk.com> - 2019-01-25 21:33 +0000
        Re: Distributing C as headers. Mateusz Viste <mateusz@wont.tell> - 2019-01-25 18:07 +0000
          Re: Distributing C as headers. gazelle@shell.xmission.com (Kenny McCormack) - 2019-01-25 18:46 +0000
            Re: Distributing C as headers. Joe Pfeiffer <pfeiffer@cs.nmsu.edu> - 2019-01-25 19:43 -0700
              Re: Distributing C as headers. Mateusz Viste <mateusz@wont.tell> - 2019-01-26 08:13 +0000
                Re: Distributing C as headers. Joe Pfeiffer <pfeiffer@cs.nmsu.edu> - 2019-01-26 13:39 -0700
                Re: Distributing C as headers. Mateusz Viste <mateusz@wont.tell> - 2019-01-26 21:00 +0000
                Re: Distributing C as headers. "Pascal J. Bourguignon" <pjb@informatimago.com> - 2019-01-26 22:29 +0100
                Re: Distributing C as headers. nobody@example.org (Scott) - 2019-01-27 04:56 +0000
                Re: Distributing C as headers. Dan Purgert <dan@djph.net> - 2019-01-27 11:36 +0000
                Re: Distributing C as headers. Tim Rentsch <tr.17687@z991.linuxsc.com> - 2019-02-25 12:26 -0800
                Re: Distributing C as headers. "Jason C. McDonald" <indeliblebluepen@gmail.com> - 2019-02-28 19:52 +0000
                Re: Distributing C as headers. Lew Pitcher <lew.pitcher@digitalfreehold.ca> - 2019-02-28 15:04 -0500
                Re: Distributing C as headers. "Pascal J. Bourguignon" <pjb@informatimago.com> - 2019-02-28 21:40 +0100
                Re: Distributing C as headers. James Kuyper <jameskuyper@alumni.caltech.edu> - 2019-02-28 13:57 -0800
                Re: Distributing C as headers. Jorgen Grahn <grahn+nntp@snipabacken.se> - 2019-01-27 13:33 +0000
                Re: Distributing C as headers. David Brown <david.brown@hesbynett.no> - 2019-01-27 15:06 +0100
                Re: Distributing C as headers. luser droog <luser.droog@gmail.com> - 2019-01-26 13:01 -0800
                Re: Distributing C as headers. "Pascal J. Bourguignon" <pjb@informatimago.com> - 2019-01-26 22:30 +0100
                Re: Distributing C as headers. Jorgen Grahn <grahn+nntp@snipabacken.se> - 2019-02-02 09:27 +0000
                Re: Distributing C as headers. "Pascal J. Bourguignon" <pjb@informatimago.com> - 2019-01-26 22:23 +0100
                Re: Distributing C as headers. Keith Thompson <kst-u@mib.org> - 2019-01-26 13:39 -0800
                Re: Distributing C as headers. "Pascal J. Bourguignon" <pjb@informatimago.com> - 2019-01-26 22:47 +0100
                Re: Distributing C as headers. Keith Thompson <kst-u@mib.org> - 2019-01-26 14:33 -0800
                Re: Distributing C as headers. "Pascal J. Bourguignon" <pjb@informatimago.com> - 2019-01-26 23:37 +0100
                Re: Distributing C as headers. Keith Thompson <kst-u@mib.org> - 2019-01-26 15:09 -0800
                Re: Distributing C as headers. David Brown <david.brown@hesbynett.no> - 2019-01-27 15:11 +0100
                Re: Distributing C as headers. James Kuyper <jameskuyper@alumni.caltech.edu> - 2019-01-27 16:12 -0500
                Re: Distributing C as headers. "Pascal J. Bourguignon" <pjb@informatimago.com> - 2019-01-28 00:51 +0100
                Re: Distributing C as headers. Bart <bc@freeuk.com> - 2019-01-28 00:06 +0000
                Re: Distributing C as headers. Bart <bc@freeuk.com> - 2019-01-28 00:18 +0000
                Re: Distributing C as headers. Ben Bacarisse <ben.usenet@bsb.me.uk> - 2019-01-28 01:12 +0000
                Re: Distributing C as headers. Bart <bc@freeuk.com> - 2019-01-28 01:35 +0000
                Re: Distributing C as headers. Ben Bacarisse <ben.usenet@bsb.me.uk> - 2019-01-28 02:19 +0000
                Re: Distributing C as headers. Bart <bc@freeuk.com> - 2019-01-28 10:40 +0000
                Re: Distributing C as headers. "Pascal J. Bourguignon" <pjb@informatimago.com> - 2019-01-28 12:22 +0100
                Re: Distributing C as headers. "Pascal J. Bourguignon" <pjb@informatimago.com> - 2019-01-28 12:21 +0100
                Re: Distributing C as headers. Malcolm McLean <malcolm.arthur.mclean@gmail.com> - 2019-01-28 04:03 -0800
                Re: Distributing C as headers. David Brown <david.brown@hesbynett.no> - 2019-01-28 13:23 +0100
                Re: Distributing C as headers. Keith Thompson <kst-u@mib.org> - 2019-01-28 11:16 -0800
                Re: Distributing C as headers. David Brown <david.brown@hesbynett.no> - 2019-01-28 21:08 +0100
                Re: Distributing C as headers. "Pascal J. Bourguignon" <pjb@informatimago.com> - 2019-01-28 01:19 +0100
                Re: Distributing C as headers. Keith Thompson <kst-u@mib.org> - 2019-01-27 16:59 -0800
                Re: Distributing C as headers. Keith Thompson <kst-u@mib.org> - 2019-01-27 16:33 -0800
                Re: Distributing C as headers. "Pascal J. Bourguignon" <pjb@informatimago.com> - 2019-01-28 01:35 +0100
                Re: Distributing C as headers. Keith Thompson <kst-u@mib.org> - 2019-01-27 17:20 -0800
                Re: Distributing C as headers. James Kuyper <jameskuyper@alumni.caltech.edu> - 2019-01-27 22:50 -0500
                Re: Distributing C as headers. David Brown <david.brown@hesbynett.no> - 2019-01-28 06:52 +0100
                Re: Distributing C as headers. Bart <bc@freeuk.com> - 2019-01-28 10:55 +0000
                Re: Distributing C as headers. "Pascal J. Bourguignon" <pjb@informatimago.com> - 2019-01-28 12:26 +0100
                Re: Distributing C as headers. David Brown <david.brown@hesbynett.no> - 2019-01-28 13:27 +0100
                Re: Distributing C as headers. David Brown <david.brown@hesbynett.no> - 2019-01-28 13:26 +0100
                Re: Distributing C as headers. "Pascal J. Bourguignon" <pjb@informatimago.com> - 2019-01-28 14:03 +0100
                Re: Distributing C as headers. Keith Thompson <kst-u@mib.org> - 2019-01-28 11:12 -0800
                Re: Distributing C as headers. "Pascal J. Bourguignon" <pjb@informatimago.com> - 2019-01-28 12:25 +0100
                Re: Distributing C as headers. David Brown <david.brown@hesbynett.no> - 2019-01-28 13:33 +0100
                Re: Distributing C as headers. Keith Thompson <kst-u@mib.org> - 2019-01-28 11:20 -0800
                Re: Distributing C as headers. David Brown <david.brown@hesbynett.no> - 2019-01-28 21:11 +0100
                Re: Distributing C as headers. scott@slp53.sl.home (Scott Lurndal) - 2019-01-28 21:12 +0000
                Re: Distributing C as headers. David Brown <david.brown@hesbynett.no> - 2019-01-28 23:06 +0100
                Re: Distributing C as headers. David Brown <david.brown@hesbynett.no> - 2019-01-27 15:02 +0100
    Re: Distributing C as headers. "Pascal J. Bourguignon" <pjb@informatimago.com> - 2019-01-25 17:51 +0100
    Re: Distributing C as headers. fir <profesor.fir@gmail.com> - 2019-01-25 14:28 -0800

csiph-web