doxygen documentation generator
A documentation generator, such as doxygen or javadoc,
processes the files containing source code for a project and automatically
constructs documents listing the identifiers defined in each file and
providing whatever information it can derive about the entities that the
identifiers denote. It obtains some of this information (such as the types
of variables) by parsing the source code files. Usually, however, the
programmer supplements this minimal information by adding documentation comments to the source code. These comments conventionally
signal additional information to the documentation generator, which
incorporates it into the documents it constructs.
The doxygen utility distinguishes ordinary C comments, which it
ignores, from documentation comments, which it studies carefully. There
are several equally valid conventions for signalling to doxygen that
a comment is a documentation comment. The one that we'll use is that a
documentation comment begins with the character sequence /** -- that
is, with an extra star after the comment starter. (Documentation comments
are terminated by */, just as other C comments are.)
Within documentation comments, a word that is prefixed with the whorl
character @ (or, equivalently, with a backslash character, but we'll
use the whorl) initiates one of doxygen's special commands. A command directs
doxygen to give some kind of special treatment to the next word, or
to the rest of the line, or to the rest of the paragraph (that is, to
everything up to the next blank line). For instance, the @c command
directs doxygen to typeset the next word in a monospace font,
indicating that it is an identifier used in the source code, and the @return command directs doxygen to treat the text that follows as a
description of the return value of a function or method.
The doxygen utility also understands a few simple HTML tags, so that
one could also write <tt>foo</tt> to direct it to typeset foo
in a monospace font.
I have revised the files queue.h, queue.c, and
test-queues.c in the /home/stone/courses/software-design/code/ directory on MathLAN to include
documentation comments and doxygen commands. Create a directory
named doxygen-lab within your home directory on MathLAN, copy
these three files into it, and inspect them to get a sense of how the basic
conventions work. As a sample of doxygen's work, see the on-line version of the document that I had it build from
these files.
doxygen
The user can choose or control many features of the documents that doxygen constructs through a configuration file that doxygen reads
in before it begins to process the source-code files. This file is
conventionally called Doxyfile, although you can give it
another name if necessary. Doxyfile is a plain text file, and
one can create it with any editor. Alternatively, we can ask doxygen to create a standard Doxyfile that lists all the
configuration options, with explanatory comments, and then edit the file to
tweak the values of any options that we want to change.
In a terminal window, in your doxygen-lab directory, give
the command
to direct doxygen to create a standard Doxyfile. Load
that file into your editor and examine its structure. Find the line in
which the value of the PAPER_TYPE option is set, replace the default
value (a4 or a4wide) with letter, and save this change.
Near the top of the standard Doxyfile you will find the
configuration option PROJECT_NAME. In the standard Doxyfile, this option defaults to the null string, but it is bad practice
to leave it that way. Think of a suitable name for the queues library and
set the options accordingly. Don't forget to put quotation marks around
the value if it is more than one word long.
doxygen
To generate documentation according to the configuration described in Doxyfile, give the command
in the terminal window. With the current configuration, doxygen
constructs an HTML version of the document for on-line use, storing the
supporting files in a newly created subdirectory called html/.
Run this command and examine the results.
To view the documents, start a browser and give it the URL file:///home/spelvin/doxygen-lab/html/index.html (substituting your
username for spelvin and giving the full pathname to the file).
Explore the links.
In addition to the HTML version of the documentation, doxygen
generates a LaTeX version, which can be typeset and printed in hard copy or
converted to Portable Document Format (PDF). The files supporting this
second version of the document are in another newly created directory,
latex/.
In the latex/ subdirectory, you'll find a Makefile.
Running make in that subdirectory causes the document to be typeset
and generates PDF a version of the document, in a file called refman.pdf. Once you have constructed this file, you can view it by
typing
in the terminal window.
Typeset the LaTeX version of the queues document and use evince to look through it.
The default configuration for doxygen is designed for C++ rather
than C, and the difference shows up in a lot of small ways. For instance,
most C++ programs consist mainly of class definitions containing fields and
methods, and so doxygen uses that terminology in describing
user-defined data structures, even when they are introduced, as in C,
through struct declarations.
In your editor, find in the Doxyfile the line for the
OPTIMIZE_OUTPUT_FOR_C option. The default value is NO;
change it to YES, then save the change.
Now re-run doxygen to regenerate the document. Reload the URL in
the browser (you may need to hold down the Shift key while you click on the
reload icon, in order to make sure that you don't get a cached version) and
note how the structure of the document and the terminology it uses have
changed.
To further illustrate the kind of control that the programmer can apply
through the configuration file, edit Doxyfile to turn on the
INLINE_SOURCES and LATEX_SOURCE_CODE options, then re-run
doxygen to regenerate the document. Reload the document in your
browser and note once more how it has changed.
The file /home/stone/courses/software-design/code/array-queue.c contains my array implementation of the queue data type, but contains no documentation comments. Let's replace the linked-list implementation of queues that is currently in queue.c with this array implementation and rewrite the documentation comments as we go.
Create a subdirectory called archive in your doxygen-lab
directory and move the linked-list version of queue.c into it.
Then copy /home/stone/courses/software-design/code/array-queue.c into the doxygen-lab directory itself, renaming it as queue.c.
Add a star to each of the comments in the queue.c file,
converting them all into documentation comments. Re-run doxygen,
reload the resulting document in your browser, and examine the HTML
documents at the “Classes” and “Files” links. What has
changed?
The reference page about struct queue_structure objects clearly
reflects the fact that doxygen has examined the array implementation
in queue.c, but queue.c is no longer included in
the list of files. And queue.c defines a function, queue_size, that is not mentioned anywhere in the document.
One reason for these differences is that doxygen does not fully
process a file unless it sees a documentation comment containing the
special command @file. In particular, it does not process the
definitions of functions defined in the file unless that command is
present. The references to the other functions (make_queue, enqueue, and so on) in queue.h, which already has a @file command in it, suggested to doxygen that it should look up
the definitions in the corresponding .c file and process them,
but it had no such hint for queue_size and so just left it out.
Add the command @file to the opening documentation comment
in queue.c, re-run doxygen, and observe the resulting
changes.
Two of the comments in queue.c (one in the make_queue
function and the other in enqueue are located between executable
code statements and make sense only in that context. If you converted
these into documentation comments, you may have discovered that doxygen adds such comments to the headers it constructs. Remove the extra
star in each of those two comments, re-run doxygen, and observe the
consequences.
Using the @brief, @param, and @return commands, add
information about the queue_size function to queue.c.
(Look at archive/queue.c for examples, or consult the special
commands page in the
Doxygen manual for descriptions and more examples.) Re-run
doxygen and observe the changes in the on-line document.
Since the LATEX_SOURCE_CODE option is still turned on, doxygen is creating new versions of the LaTeX files each time you run
it. However, the PDF file won't change until you run make in the
latex/ directory, to have LaTeX typeset the most recent
version of the document. Do this now and examine the current version of
the PDF. Describe its structure and contents.
doxygen -- a few extras
As usual, this lab covers only a few of the many features of doxygen. You may want to experiment with others:
The output formats page of the manual describes
how to configure doxygen so as to generate Rich Text Format (RTF)
documents, man pages, etc.
To generate content that will appear the index.html page itself, use
the @mainpage command in a documentation comment. In the LaTeX
version, it will appear as an initial chapter.
You can embed arbitrary hyperlinks in documentation comments by writing
them out in HTML (as a elements with href attributes). In
addition, doxygen automatically converts anything that looks
sufficiently like a URL into a hyperlink if it occurs within a
documentation comment.
If you want a documentation comment to contain some code that should be
displayed exactly as it occurs in the source-code file, with line breaks
and indentation preserved, put the command @verbatim on the line
above the code and the commend @endverbatim on the line after it.
Documentation for doxygen is available on line: