Re: CVS commit: src

[christos%astron.com@localhost (Christos Zoulas)]

In article <20110412180513.GA9110%kleink.org@localhost>,
Klaus Klein  <kleink%kleink.org@localhost> wrote:
>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.

I think that what Klaus means is merely documenting the fields and
types that the programmer needs to know in order to use the API, but
leave ones that are implementation details out (and avoid saying that
this is the complete structure) in a way similar to what ToG does:

http://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/statvfs.h.html

christos