Re: "Documentation by paper"

[Phil Edwards <phil at codesourcery dot com>]

Richard Kenner wrote:
>     The @param and @return and whatnot are not intended for humans
>
> But humans will be reading them.  Every time they look at the sources.

Then use a folding text editor.  /** is a clear marker to begin folding.


> I would *certainly* dispute that fact. It's far *worse* than "nothing".
> What we desperately need is well-written high-level documentation of
> methods and algorithms and how everything fits together.  Finding ways
> of automatically extracting low-level details from code and calling
> it "high-level documentation" *detracts* from that effort.

We're talking past each other.

I certainly never called it that.  I certainly don't dispute the need for
writing down what you're asking for.  But we also need useful API catalogs:

    http://www.jaj.com/space/phil/gccdoxy/struct___unwind___context.html

and cross-references:

    http://www.jaj.com/space/phil/gccdoxy/unwind-dw2-fde-glibc_8c__incl.png

and trying to do those by hand is just monstrously stupid.