Re: CVS commit: src

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

On Tue, Apr 12, 2011 at 09:25:06PM +0300, Jukka Ruohonen wrote:
> On Tue, Apr 12, 2011 at 09:24:00PM +0300, Jukka Ruohonen wrote:
> > On Tue, Apr 12, 2011 at 08:05:13PM +0200, Klaus Klein wrote:
> > > by being that specific, such documentation creates the obligation to
> > > keep the redundant definition in sync.
> > 
> PS.
> 
> If you look what I've written in, say, stdlib(3), unistd(3), or stddef(3) --
> all these have been written with minimum maintenance costs in mind.

Right; I had already, and no cause for unhappiness there. :-)

However, the quotation above omitted the beginning of the sentence,
which read:

> Those interested          
> in structure member poking will look at the header file anyway, and, 

Just to make it clear again, it's really just the structure
definitions being documented verbatim I'm taking issue with.
Those are appropriate for an ABI document, but as far as programmers'
documentation is concerned it seems to me like too much effort spent
to enable its readers to shoot themselves in their feet. :-)


- Klaus