Re: FYI: minsyms documentation

Stan Shebs
2011-12-22T20:06:23Z

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