"Documentation by paper"

[Zack Weinberg]

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.

zw