Re: [RFC] Use Doxygen for internals documentation

[Stan Shebs <stanshebs@earthlink.net>]

On 10/16/13 10:28 AM, Tom Tromey wrote:
>>>>>> "Stan" == Stan Shebs <stanshebs@earthlink.net> writes:
> 
> Stan> This patch is the third and final step in the transition away from the
> Stan> old GDB internals manual.
> 
> Thanks, Stan.
> 
> I applied your patch and built the docs locally.  This went smoothly.
> 
> 
> I don't have a problem with the new way of formatting comments, or with
> requiring them in review.
> 
> It seems to me that we should require docs for extern objects.  For
> static objects I think it's fine to use less formal comments; but I'm
> curious what others think.

That's my working assumption as well.

> I started by looking at the minsyms section.  I rearranged minsyms a
> while back to have the comments in the header and to try to make it act
> somewhat more like a self-contained module.  So, I was particularly
> curious how this would render.
> 
> Starting here it looks promising enough:
> 
>     http://stanshebs.github.io/gdb-doxy-test/gdb-api/pages.html
> 
> (When we have two dozen modules here will we be able to organize them
> somehow?)
> 
> Clicking through to the Minimal Symbols page, though, just gives some
> text about the header.  (As an aside it's clear that this paragraph
> needs a rewrite for Doxygen...)
> 
> However, there's nothing there about the module API, nor any link to
> minsyms.h.  Is the latter something we can add?

Doxygen includes a scheme that basically lets you generate arbitrary
pages from block comments, and the Minimal Symbols page was my
experiment with that.  It doesn't seem to auto-generate any sort of
linkage to header file, but as part of arbitrariness there is the
ability to add links.  So that might have to be part of our practice
for such pages.

> I can go to the files page:
> 
>     http://stanshebs.github.io/gdb-doxy-test/gdb-api/files.html
> 
> and click through to minsyms.h:
> 
>     http://stanshebs.github.io/gdb-doxy-test/gdb-api/minsyms_8h.html
> 
> This lays out the contents of the file -- but not any introductory
> text.  So that seems odd.

Yeah, there doesn't seem to be a way to do that.

> And, the contents are in an arbitrary order: Classes, Defines,
> Functions.  What if we arranged the file in a particular order to
> emphasize related things?  Could we reflect this in the docs somehow?

There is a configuration option to list these in file order rather than
alphabetical, and there is some grouping machinery that I don't quite
understand yet.  There are HTML/CSS tricks that one can do as well,
so we have some options.

> Finally, having to go to the Files page is sub-optimal just because it
> presumes that one knows the layout.  It would be better if we could
> start from some top-level view of "Modules of GDB" and click through to
> the modules to understand their details.

Yeah, I think real deployment entails some kind of top-level page that
is the overall guide.

Another, more incremental approach is to have the API doxyfile list only
the files that have doxygen-type documentation.  So one grows
the doxyfile as more files get documented, and if foo-tdep.h never
gets official documentation, it's never clutter in the listing.

Stan