"Documentation by paper"

[Richard Kenner]

    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.

    Your original patches don't contain much in the way of documentation,
    either.

What happened here was that the original implementation had few enough
functions that there wasn't a need for anything other than the localized
documentation, but then things grew to the point where it was indeed needed
and I never went back and added it.  I will do so soon.