Re: CVS commit: src

[Klaus Klein <kleink%kleink.org@localhost>]

On Tue, Apr 12, 2011 at 09:21:29PM +0300, Jukka Ruohonen wrote:
> 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*.

I'm afraid you're missing the point I've attempted to make.  Said
interface's user should not care at all about the struct's verbatim
definition, yet the documentation is extended to needlessly cover just
that.  And, keeping standardization efforts aside, placing the struct
definition syntax in the documentation suggests an extension of the
ABI compatibility contract.  For the sake of an example, is "efficiently"
comparing two struct tm objects by memcmp(3)ing a continuous memory range
holding an apparently consecutive subset of their respective members ok?
(What about implicit structure padding, reusing it some day, or even
reordering the members?)

Your efforts to improve documentation deserve to be commended; the one
issue I'm concerned about is these structs being over-documented by
replicating the structure definition, possibly causing harm.



- Klaus