Re: A new strategy for internals documentation

[Doug Evans <dje at google dot com>]

On Tue, Aug 6, 2013 at 9:28 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Tue, 06 Aug 2013 15:26:34 -0700
>> From: Stan Shebs <stanshebs@earthlink.net>
>>
>> Although GDB has had an internals manual for many years, nobody has
>> been especially happy with it.  It is perennially out of date,
>> sometimes majorly so, and it is quite incomplete.  With the passage of
>> time, the whole idea of an internals manual has come to seem like a
>> throwback to the old days, when the prospective GDB hacker's
>> information had to come from either printed books, or tape archives
>> downloaded from an FTP site.
>>
>> Various ideas for how to fix have been floating around, generally with
>> the goal of improving the manual somehow, but nothing has developed
>> into action.
>>
>> I propose a two-pronged strategy, first migrating the internals manual
>> to the wiki, and then introducing Doxygen for source code
>> documentation.
>
> It is customary to save the important issues to the end, but I'd like
> to break that custom and ask this now: do we even want to document the
> internals?  This is a serious question: over the years, I've had my
> share of trying to convince the main contributors to improve the
> internals manual, and the result was always the same: people are
> generally happy with the commentary in the code and don't feel any
> need to go any further.
>
> So how just declaring gdbint.texinfo dead and deleting it altogether?
> Why should we waste any breath arguing about a creature that is not
> loved by anyone?

Well, there's deleting gdbint.texinfo and replacing it.
[just stating that for clarity's sake]

> Having said that (and I do suggest to discuss this main issue first),
> here are some comments about specific points of the proposal.
>
>> *** Migration of gdbint.texinfo to wiki
>
> Wiki is a bad idea, because there's virtually no control on the
> quality of the information there.

I don't see this as a deciding issue - the quality can be good enough.

>> * Cross-references to more info
>>
>> Much of this is redundant with information already on the GDB website
>> or in the wiki.
>
> If you renounce cross-references, you in effect are saying that
> hyperlinks, which IMO are one of the most important inventions in
> on-line docs, are useless and should not be considered important at
> all.  That is a strange opinion, indeed.

Are cross-references being renounced in their entirety?
A good question would be: what sufficiently important cross-references
will no longer be possible?

>> *** Doxygen
>>
>> As a second step, we should adopt Doxygen for the sources, and use it
>> to generate material for a new area of the website, which will be the
>> detailed documentation of GDB internals.
>
> AFAIK, Doxygen cannot generate an Info manual, only HTML.  If so, this
> would be a serious downside that you don't mention.
>
> If we want to keep the documentation in the sources, why not use the
> same system as libiberty?

Does any developer like that system? [honest question]

>> *** Upsides
>>
>> Having the narrative and descriptive material as a pile of wiki page
>> will make it easier to tinker with incrementally.  Changes won't go
>> through a formal patch review process, which is OK because the pages
>> are more informal and tutorial rather than authoritative.
>
> Not having a review process for documentation is an "upside"
> because?...
>
>> (Knowledgeable GDBers should still monitor edits and fix any serious
>> errors that creep in.)
>
> Why should "Knowledgeable GDBers" do the job of whoever submits the
> patch?  Do we have a lot of free time on our hands to do that?  Patch
> review is a well established process in GDB maintenance and
> development, and AFAICS it works reasonably well, certainly in the
> area of the documentation.  Why would we consider getting rid of it?

A good question to ask here is given that knowledgeable GDBers will
either review the doc and exchange several emails until it can be
checked in, or fix it after it's committed (e.g. to wiki), which is an
overall better use of time?

>> Conversely, Doxygen in the sources will bring additional rigor and
>> detail to a chronically weak aspect of GDB's code, namely, how the
>> different parts are supposed to work with each other.
>
> This is precisely the problem with documenting in comments, but (see
> above) people seem to be happy with it.  So I don't see how Doxygen
> will change any of that.

One real problem we have (IMHO) is knowing what the various "modules"
(for lack of a better word) of gdb are and what their *public* APIs
are.  Can Doxygen help with that?  E.g. can part of the generated
output be a chapter (or some such) on what the modules are and their
APIs?
[honest question]