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
