Re: [RFC/RFA] Introduce new struct parse_context

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Fri, 21 Dec 2007 08:36:08 +0400
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: uweigand@de.ibm.com, gdb-patches@sourceware.org
> 
> I would tend to say that your suggestion is a good one, and we should
> request documentation when necessary. But I think that this should
> be evaluated on a case-by-case basis, because there are some times
> when external documents such as gdbint will be more useful, and other
> times when it will be more appropriate to leave the documentation
> as a comment embedded in the code.
> 
> Let's take the two patches of this thread as an example. Would you
> suggest to move the documentation to gdbint, or leave it in the
> code?  To me, it seems better to put keep the documentation with
> the code.

We had this discussion in the past, and I'm well aware that some of
the maintainers think that code comments are better than a manual that
documents the internals.  I can only reiterate what I wrote back then:
I think code comments are not a replacement for a good internals
manual.  Comments don't have a structure.  They lack good
cross-referencing facilities.  They don't have any efficient ways of
searching for text by a word or phrase that describes the topic or
subject we are looking for (something like index search in Info).

Comments also tend to describe details, but not the overall picture.

In sum, I think comments are not appropriate for someone who wants to
learn about a subject she knows next to nothing about.

> If we were to put some documentation in gdbint for this patch,
> what would you put?

Both.  This is a significant new feature, and at least its main
principles should be described in gdbint, enough to get the reader off
the ground with the knowledge she could use to find the parts of code
which implement this feature (and read the comments there ;-).