• DoxygenForGDB

The GDB sources now include support for Doxygen, a tool for generating documentation from source code. (For info on Doxygen, see http://www.stack.nl/~dimitri/doxygen.)

Our use of Doxygen is entirely for the benefit of people developing GDB. We use Doxygen in two ways:

* To build browseable cross-reference listings

* To document GDB's internal "API", which basically means the set of functions and variables that are used widely in the code.

We do not need to write fancy Doxygen-style comments for every line of GDB! For most of the code, the normal commenting practices suffice.

Running Doxygen

Ensure that you have Doxygen installed. It is often preinstalled on Linux distros, or a prebuilt package, and is also easy to download sources and build.

In a configured GDB objdir, "cd gdb/doc", then "make doxy". This will produce a subdirectory "doxy" with an index.html file and several subdirectories, each of which contains a set of Doxygen-generated pages.

(Not all of the dependencies are enumerated in the Makefile - use "rm -r *oxy*" to ensure clean regeneration.)

Using Doxygen

The main doxy/index.html is a handwritten web page that links to the roots of each doxygen page collection.

In general you can just click around to find stuff. Note that Doxygen can be outsmarted by some of our tricky programming practices, so if something appears unreferenced, doublecheck the sources before concluding that it is really never used.

Adding Doxygen documentation

You can help improve the look of Doxygen-generated material by using its specially-supported syntax.

For instance, Doxygen takes a comment beginning with "/**" to be a description of the next function, variable, or class in the sources, and includes that text in its formatting for the construct. In addition, you can add additional syntax within the comment, such as "@param" to indicate the names of function parameters.

Unfortunately for us, the "/**" syntax does not place nice with GNU coding conventions, nor with Emacs' normal handling of comment blocks. Workarounds for us are to put the "/**" on a line by itself, or to start a comment with "/* * " - we have a prefiltering script that translates those into "/** " before handing to Doxygen.

To Do

As of this writing (Feb 2014) Doxygen is a new introduction to GDB process, and we will certainly evolve our usage as we develop experience (or decide that it's lame, and dump it).

Here are some changes that seem good to do:

* Set up GDB website scripts to generate Doxygen pages from snapshots.

* Add more API header files.

* Decide coding standards for header vs body comments.

* Add some quick links to the most interesting functions/pages.

* Find long theory-of-operation text blocks in sources, make Doxygen pages out of them.

Sign-up sheet

This section contains a sign-up sheet for those wanting to take claim of files they plan to doxygenate.