This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: FYI: minsyms documentation


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]