"Documentation by paper"

[Kai Henningsen]

zack@codesourcery.com (Zack Weinberg)  wrote on 09.02.04 in <87n07s13uf.fsf@egil.codesourcery.com>:

> kenner@vlsi1.ultra.nyu.edu (Richard Kenner) writes:
>
> >     Are you advocating that there should be no internals manual?  I can
> >     see an argument for "no internals manual is necessary, just use
> >     comments in the code", and I can see an argument for "every internal
> >     interface should at least be mentioned in the internals manual", but
> >     not for some limbo state where there's no way to know if something is
> >     in the manual or not.
> >
> > No.  I'm advocating that the *primary* documentation should be in the
> > source code and that any documenation (internal or external) should be
> > derived from there, not vice versa.
>
> Weird, I thought you didn't like extracting documentation from the
> source code.

The way I read him, as long as he gets his primary readable docs in the  
source, he's willing to have the rest of you extract something from there.

As for the internals manual -

A case *could* be made to reduce that to a sort of "Introduction to GCC  
internals for beginners", including a general introduction and a directory  
of what to find in which file (the latter presumably at least partly  
generated), and having all the rest in some source files.

Or, alternatively, having all the rest in those sourcefiles and extract it  
from there for the manual.

Of course, this then runs head-on into the GPL/GFDL incompatibility ...

Anyway, if one wants to go that way, presumably there'd have to be some  
sort of standard file preamble. Just for sake of illustration, not meant  
as a serious proposal:

----- start of file ----
/* <group> <one-line description>
<copyright/licence boilerplate>*/

/* <long
    description> */

#include ...
...
----- rest of file -----

where group is meant to sort this to the right place in a directory, say  
"c.parser" or whatever - meant to be sorted by <group>.<filename>. (This  
is actually mostly taken from a single look at c-decl.c - adding the  
group.)

MfG Kai