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.
