Re: What's an annex? stratum?

[Eli Zaretskii <eliz@gnu.org>]

> Date: Mon, 25 Jun 2007 15:38:07 -0400
> From: Robert Dewar <dewar@adacore.com>
> 
> On Mon, Jun 25, 2007 at 03:19:32PM -0400, Paul Koning wrote:
> > That's really unfortunate.  Comments in code are useful but they are
> > no substitute for properly written internals documentation.
> 
> I disagree, properly arranged comments in the code can most
> certainly serve as internals documentation

Code comments lack good provisions for such important aspects of
documentation as cross-references, indices, and hierarchical
structure.  Without these, all comments can present is an unstructured
collection of unrelated notes.

> I am opposed to having separate internals documentation, I think it
> is much better to have this in the source files.

That's not surprising: programmers don't like writing documentation as
much as they like writing code.  That is one reason why gdbint.texinfo
is in such poor shape.

In any case, if people here believe comments are a reasonable
substitute for documentation, perhaps I should from now on reject code
patches that do not explain themselves clearly, and do not contain
enough references to other related portions of GDB.