Re: Distributing C as headers.

From	"Pascal J. Bourguignon" <pjb@informatimago.com>
Newsgroups	comp.lang.c
Subject	Re: Distributing C as headers.
Date	2019-01-26 22:29 +0100
Organization	Informatimago
Message-ID	<m2zhrnds5z.fsf@despina.home> (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

Mateusz Viste <mateusz@wont.tell> writes:

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

You are considering proper header = comment + declarations.

This is a problem, because the compiler cannot validate the comments.

It would be better if the declarations alone would let you write a
program that can run without crashing.

-- 
__Pascal J. Bourguignon__
http://www.informatimago.com

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