Re: "Documentation by paper"

[Ian Lance Taylor <ian at wasabisystems dot com>]

law@redhat.com writes:

> IMHO that's actually a huge long term liability as it actually discourages
> writing good API interfaces and documenting them, while at the same time
> encourages developers to actually look at the implementation to determine
> if the code in question actually does what they want.

I agree with you, but extracting documentation automatically from
source code comments, and from the source code itself, isn't API
documentation either.  It's just another way of reading the source
code.

Source code and documentation aren't the same thing.  The only case
where I've seen source code work as documentation is Web (that is, the
TeX implementation language), and Web is much harder to write than the
combined effort of writing source code and separate documentation.

The reason source code and documentation aren't the same thing is that
they serve different purposes.  Source code tells you what the
function does.  Documentation tells you how that fits into a larger
plan.  Documentation is organized for a human reader.  Source code is
organized for the compiler.

The advantage of Web is that it lets you split apart a single function
into different logical portions, and lets you group together the
logical portions of several different functions.  The most obvious use
is that you can pull the error cases out of the function, leaving the
reader looking only at the mainline case, which is generally much
easier to understand and to document.  Unfortunately, as noted, it's
very hard to program this way.

As I said, I'm not strongly opposed to extracting documentation from
the gcc sources.  But it's no substitute for actual documentation.

Ian