Source-Changes-D archive

[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'
> 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,


Home | Main Index | Thread Index | Old Index