Re: "Documentation by paper"

[Robert Dewar <dewar at gnat dot com>]

Andrew Sutton wrote:

> > There is a *big* difference between looking at interface comments in
> > a header and looking at the implementation!
>
>
> isn't that the _point_ of an interface? i sure as hell don't look at the libc 
> implementations of posix methods to figure out what the parameters do.
>
> sorry to keep extending this thread... it's late and i have some strong 
> feelings about the topic - especially since my masters thesis revolves around 
> the topics of program understanding, redocumentation and reverse engineering 
> (not reverse engineering like decss). maybe it's me, but it seems a bit odd 
> that people would argue against documentation extraction in favor of having 
> developers look at the implementation as a reference. but then again, i'm 
> only a software engin... i mean grad student.

You seem to be missing the point I made that you quoted above. Looking 
at interface documentation (in a C header or Ada spec) is not at ALL
the same thing as "look[ing] at the implementation". In the case of Ada,
it is universally understood that the spec of a package should act 
precisely as the documentation. There is no real point in "extracting"
this documentation, since the spec should contain exactly the needed
documentation and nothing more or less. The advantage of this approach
is that the spec is compiled by the compiler, so at least those parts
of it that are syntactic (argument types etc) are guaranteed to be
properly formed, and if not guaranteed to be correct, at least 
guaranteed to be consistent with the implementation. The comments in
a spec should be *exactly* the required interface documentation. Nothing
more and nothing else.

The GNAT library follows this style. In the reference manual, you find
for example that g-spipat.ads/adb provides Spitbol-like pattern matching.

That single sentence acts as a guidepost to where to look if you need
this kind of functionality. If you want to know the details of how to
use this package, you look in the spec file g-spipat.ads (you certainly
do NOT look in the (very complex) implementation in the body in the file
g-spipat.adb.

Now in the case of Java, there is no natural separation of specs and
implementation (for those of us of the Ada persuasion, this is one
of the serious deficiencies of the language). So you are most definitely
forced to use the approach of documentation extraction (assuming for
a moment that we are all agreeing on the merits of having the *source*
of the documentation reside with the source files).

In the case of C, we can go either way. If we want to follow the Ada
style, we treat C headers in exactly the same way as Ada programmers
would treat Ada specs, i.e. we put in these headers exactly the
required interface documentation, nothing more and nothing less,
formatted in a manner that makes it as easy to read as possible.

If you want to follow the Java style with C, you end up putting the
bare bones documentation into headers, and then extracting the
documentation from the implementation files.

There is nothing that says objectively that one of these approaches
in C is better than the other. Obviously the contrasting Ada and
Java designs show that there are strong proponents of the two
approaches. Furthermore, the opinions about which approach is
better are strongly held (Ada advocates for example consider
Ada's approach to separation of spec and body to be one of the
very important strong features of the language).

So it is quite natural that there be a significant argument about
which style is preferable when it comes to C. To me, as always,
consistency is the most important thing. That's especially true
when it comes to documentation, where unfortunately many programmers
seem to have to be lead kicking and screaming to this task :-)

I far prefer the fully documented header approach when it comes
to C, but I could live with an enforced and universal style of
annotations and document extraction. What is NOT a good idea is
to let individual programmers decide for themselves, since then
the third alternative (no good documentation at all) is far too
attractive to far too many programmers!