Re: CVS commit: src

[Jukka Ruohonen <jruohonen%iki.fi@localhost>]

On Tue, Apr 12, 2011 at 09:58:24PM +0000, Christos Zoulas wrote:
> I think that what Klaus means is merely documenting the fields and
> types that the programmer needs to know in order to use the API, but
> leave ones that are implementation details out (and avoid saying that
> this is the complete structure) in a way similar to what ToG does:

As I already wrote, this is a good practice and I agree with it.

Just trying to improve things. At the other extreme, we have haphazard and
nearly useless documentation due to the terseness. A case study:

     qdiv_t
     qdiv(quad_t num, quad_t denom);

 DESCRIPTION
     The qdiv() function computes the value num/denom and returns the
     quotient and remainder in a structure named qdiv_t that contains
     two quad integer members named quot and rem.

What is a "quad"? We know that some "qdiv_t" contains "quot" and "rem", but
what type are these? I know the answer, but these are absolute minimum
requirements for any C programmer to know.

- Jukka.

PS.

Of course you can read the above also such that random things like this
should not appear in the libc, and care should be taken not to overburden
the standard library. But I guess most people agree with this.