Re: "Documentation by paper"

[Bernd Schmidt <bernds at redhat dot com>]

On Tue, 27 Jan 2004, Phil Edwards wrote:

> 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 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:

I guess this debate is mainly about people's differing habits.  Personally,
I like uncluttered comments in my source code.  Cluttering them and then
hiding them with a folding editor isn't my idea of an improvement.
I don't see a need for external documentation duplicating these comments; I
don't see what is gained by having to look at two different files instead of
just one when you're working with the source.

>      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

I've looked at these, and I can't say I find this information useful.  But
that's probably because I'm not used to working with it.

But this is all offtopic.  FWIW, I agree with Kenner's observation that
just citing a paper isn't good enough to document an algorithm.

Bernd