Re: CVS commit: src

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

On Tue, Apr 12, 2011 at 08:22:50AM +0000, Jukka Ruohonen wrote:
> Module Name:  src
> Committed By: jruoho
> Date:         Tue Apr 12 08:22:49 UTC 2011
> 
> Modified Files:
>       src/distrib/sets/lists/comp: mi
>       src/share/man/man3: Makefile
> Added Files:
>       src/share/man/man3: tm.3
> 
> Log Message:
> Add a small summary parge for struct tm from <time.h>. Cf. timeval(3).

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.

Please keep this a programmers' resource, don't make it an implementors'
pseudo-resource.


- Klaus