Re: [tlug] linux@example.com How many widely can we do that?

["Stephen J. Turnbull" <stephen@example.com>]

Curt Sampson writes:

 > > Usually documented by an automatic tool that turns .h files
 > > into prose.  (I kid you not.)
 > 
 > Well, it's a step above separate documentation that never gets updated.

No, it's not -- in many cases the .h is easier to read (assuming you
can program in C, which almost goes without saying in this context).
But in most cases the separate documentation at least contains a
theory of operation section, and *omits internal interfaces*.

 > Documentation should come from code whenever possible.

I disagree.  The code should be written to implement the
documentation.  It's good to combine the source of the spec document
with the code as long as you're very disciplined about writing the
spec and then changing it only in a planned way, then filling in the
details in code.

But what's really bad about it is that if changing the .h
automatically updates the documentation, the developer of client code
is completely hung out to dry.  There is nothing left that can be
considered an independent specification of the behavior.  Even
backward compatibility can be immediately disposed of as "we changed
unspecified behavior, you really shouldn't be depending on that!" 
because *everything* is unspecified.

 > > (You certainly can find really horrible config files. sendmail.cf is a
 > > well-known example....)
 > 
 > Mitigating that is that sendmail.cf is really a special-purpose
 > programming language more than a "configuration file,"

Sure.  I'm just saying that although *nix is not exempt from opaque
configuration, it's considered a bug by most FLOSS developers.