A documentation generator, such as
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.
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
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
@ (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
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.
doxygen utility also understands a few simple HTML tags, so that
one could also write
<tt>foo</tt> to direct it to typeset
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
The user can choose or control many features of the documents that
doxygen constructs through a configuration file that
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
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
letter, and save this change.
Near the top of the standard Doxyfile you will find the
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.
To generate documentation according to the configuration described in Doxyfile, give the command
in the terminal window. With the current configuration,
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
spelvin and giving the full pathname to the file).
Explore the links.
In addition to the HTML version of the documentation,
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,
In the latex/ subdirectory, you'll find a Makefile.
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
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,
In your editor, find in the Doxyfile the line for the
OPTIMIZE_OUTPUT_FOR_C option. The default value is
change it to
YES, then save the change.
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
To further illustrate the kind of control that the programmer can apply
through the configuration file, edit Doxyfile to turn on the
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
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
reload the resulting document in your browser, and examine the HTML
documents at the “Classes” and “Files” links. What has
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
@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 (
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
Two of the comments in queue.c (one in the
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
@return commands, add
information about the
queue_size function to queue.c.
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.
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
@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
doxygen automatically converts anything that looks
sufficiently like a URL into a hyperlink if it occurs within a
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.
doxygen is available on line: