Re: FYI: minsyms documentation

[Stan Shebs <stanshebs@earthlink.net>]

On 12/21/11 6:34 PM, Tom Tromey wrote:
> I am checking this in on the trunk.
>
> Today I decided to try to document the minsyms API more or less the way
> I would like APIs to be documented in general.  This patch implements
> that; it move documentation from function definitions to minsyms.h, adds
> an introductory comment about minsyms there as well, and it rearranges
> the header into a more logical order.

I'm not liking this idea very much I'm afraid.

First, as you point out later, GDB is not really a library.  So internal 
APIs tend to be pretty fluid, depending on the needs of the moment.  But 
if you mandate that the documentation be in different places depending 
on function visibility, then the addition or removal of a static keyword 
must be accompanied by a move of the header comment block.  Even if one 
did nothing more than split an overly-large file (and I note we now have 
five source files > 10Kloc, long overdue for breakup), then there would 
have to be massive movement of comment blocks, even if none of the 
functions actually changed.  Plus we already have many functions 
declared in headers that really are intended to be private, and are only 
public because of C's limitations; we don't really want to document 
those as if they are stable API.

Second, this is potentially a very large change to the sources, but if 
it's incremental, then we get into a confusing situation where some 
files are changed, others are not, and some headers are half-changed 
because they service multiple source files.  I've been digging through 
the bowels of MI code lately, and am reminded of how many of Andrew's 
initiatives were never completed, generating all kinds of uncertainty 
about whether to try to finish them, or roll back, or what.  For things 
that are major stylistic changes, we should at least think about whether 
we can do some kind of automated transformation that brings all the code 
into a new consistent state.

> My view is that gdbint.texinfo should eventually hold a high-level
> overview of the different modules in GDB, but that each individual
> module should be documented in the relevant header files.  My reason for
> this is just that it is simpler to update documentation when it is in
> the form of comments.  I think gdbint.texinfo should also hold
> documentation on our procedures, coding styles, and other things that
> are not directly related to some piece of code.

Isn't that generally our working assumption now?

> In the past people have mentioned using something like Doxygen to
> extract an actual document from the sources.  I am not opposed to this,
> but I think that, as GDB is a program and not a library, such
> documentation is of limited value; and in any case there are known
> licensing issues with any such scheme -- see the archives of the GCC
> lists for details.

I agree, Doxygen is not very plausible.  It could even be misleading, as 
Doxygen output tends to make functions look more self-contained and 
well-defined than would actually be the case for most of GDB.

Stan