Re: CVS commit: src

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

On Tue, Apr 12, 2011 at 08:05:13PM +0200, Klaus Klein wrote:
> This exhibits something particularly well that's been bugging me for
> quite a while about such documentation changes: I think documenting
> the implementation's structure layouts in section 3 is wrong, at least
> when supposedly portable interfaces are concerned.  Those interested
> in structure member poking will look at the header file anyway, and,
> by being that specific, such documentation creates the obligation to
> keep the redundant definition in sync.

This is wrong. To use a fully standardized library routine, no "poking
around" with source code should be required. This particular change was
actually prompted by having to look up the sources for something *trivial*.

> Please keep this a programmers' resource, don't make it an implementors'
> pseudo-resource.

Right. These must still appear somewhere. Either you gather them to some
consistent place (section 3) or you document these in the pages describing
the functions. The latter usually results a mess seen in ctime(3), especially
if the structure is shared among many standard library routines.

But as always, documentation patches and commits are welcomed,

Jukka.