[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
Re: CVS commit: src
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'
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,
Main Index |
Thread Index |