Re: "Documentation by paper"

[Ian Lance Taylor <ian at wasabisystems dot com>]

Phil Edwards <phil@codesourcery.com> writes:

> I'm going to regret getting into this discussion...

Yeah, me too....

> Blame the leading '*' on me.  I introduced doxygen into libstdc++, and
> all these comments have followed that initial style.

I would say that libstdc++ is a place where doxygen-style comments are
more useful, because the documentation for a library tends to be more
reference style anyhow.  There are relatively few specific cases where
different library functions must work together in interesting ways,
and thus require additional documentation.

Also, libstdc++, as an implementation of the C++ standard library, has
a variety of high quality API documentation written by other people.
Not to mention it starts from a high quality design, certainly a
design which has had much more thought put into it than the design of
the gcc internals.

> I have complaints about doxygen myself.  But IMO it's better than anything
> else that's been concretely suggested.  And -- undisputed fact -- it's
> better than what we habe right now, which is nothing.

Well, no, I think that fact is precisely what is being disputed.  If
you have something which makes it a bit harder to write source code,
and bit harder to read source code, and doesn't help otherwise, then
it is in fact better to have nothing.

Just to give you an alternate concrete suggestion, we could add
sections to the internals documentation for each major data structure,
and we could add sections to the internals documentation for each
compiler pass.  The initial versions of those docs could be pulled
from the source code and lightly edited.  We could rely on volunteers
to clean up the text over time, as already happens from time to time
with the current manuals.  We could demand good documentation for
future additions.

This is obviously a lot harder, but I think it's in the realm of the
possible.  I personally think it would be better than anything
extracted from the source code.  And I think it would be better than
nothing.

Ian