doxygen
DEMO
doxygen
DEMO
Documentation Generation
Programs:
doxygen
demonstration
Manuel Gordon
(514) 934-3274
manuel@gordonandgordon.com
www.gordonandgordon.com
doxygen
DEMO
Manuel Gordon








Worked in computers for 25+ years
Programmer: statistics, MIS, graphics
Professor of Computer Science at Vanier
College
High-tech and business journalism
High-tech corporate communications
Teaching and training: McGill,
Concordia, U of T, corporate clients
Past president of STC Montreal chapter
Technical writing consultant since 1990
doxygen
DEMO
A doxygen Success Story

An SDK now called Vortex
—Rigid-body dynamics
—Collision detection

Developed at a company now
called Critical Mass Labs...
—http://www.cm-labs.com/

And at MathEngine plc
—http://www.mathengine.com/
doxygen
DEMO
Vortex Helps Simulate
Realistic Physical Behavior

You can download great demos...
doxygen
DEMO
Beta Documentation

Folders of HTML
Reference
documentation
generated from
doxygen

pdf files of HowTo documentation
generated from
FrameMaker files

Framed by HTML
doxygen
DEMO
Alpha 0.0.1 Documentation


Developed from zero in five weeks
Looks surprisingly like the Beta
—Beta shipped nine months later
—Many, many, many changes, major
and minor, in the SDK
—Several Alpha versions of SDK,
usually including revised
documentation
doxygen
DEMO
Why We Chose doxygen

We did a quick comparison
between doxygen and DOC++
—DOC++ looked tidier
—doxygen gave more useful info

doxygen actually a company
standard!
—Not that we knew that when we
started...
doxygen
DEMO
Finding doxygen

http://www.stack.nl/~dimitri/doxygen
doxygen
DEMO
doxygen Features

Documents C, C++, Java, IDL
(Corba, COM/ActiveX, other)

Generates or supports
—HTML
—latex
—RTF (MS-Word)
—Postscript
—hyperlinked PDF
—compressed HTML
—man pages (Unix).
doxygen
DEMO
doxygen Can Document
Undocumented Source Files!

Can extract the code structure
from undocumented source files.

Shows relations between the
various elements (functions,
typedefs, structs, etc.) as
hyperlinks

Can generate inheritance
diagrams and other diagrams
doxygen
DEMO
Dimitri van Heesch’s Log

1985: Got my first computer:
a Commodore 64!

1989: Got my second computer:
an Amiga 500

09/1992: Started studying
Computer Science at the
Technical University in Eindhoven.

10/1997: Released version 0.1
of doxygen

11/1997: Accepted a job at Philips
Research in the field of software
architecture for embedded systems.
doxygen
DEMO
A Unix-Flavored Tool



Supports many flavors of Unix
Long descriptions of how to
compile on various Unix flavors
For Windows:
—“There is no fancy installation
procedure at the moment (If anyone
wants to add it please let me know).
—“To install doxygen, just copy the
binaries from the bin directory to a
location somewhere in the path[, or]
include the bin directory of the
distribution to the path.”
doxygen
DEMO
Coding doxygen Comments
/**
* The body's position vector is returned in
* @a p.
* The position is of the bodies
* center of mass, and is given in the
* world reference frame.
*/
void MEAPI MdtBodyGetPosition
(const MdtBodyID b, MeVector3 p)
{
MdtCHECKBODY(b,"MdtBodyGetPosition");
MeVector3Copy( p, b->bodyTM[3]);
}
doxygen
DEMO
Viewing Generated Doc
void MEAPI MdtBodyGetPosition
( MdtBodyID b,
MeVector3 p )
The body's position vector is
returned in p.
The position is of the bodies center
of mass, and is given in the world
reference frame.
doxygen
DEMO
Generating a doxyfile


doxygen has a command-line
interface
To generate a doxyfile (.ini file):
doxygen -g yourdoxyfile
doxygen
DEMO
Raw doxyfile with comments
# The PROJECT_NAME tag is a single word (or a
# sequence of words surrounded
# by quotes) that should identify the project.
PROJECT_NAME
#
#
#
#
#
#
#
=
The OUTPUT_DIRECTORY tag is used to specify
the (relative or absolute) base path where
the generated documentation will be put.
If a relative path is entered, it will be
relative to the location where doxygen was
started. If left blank the current directory
will be used.
OUTPUT_DIRECTORY
=
doxygen
DEMO
Some Keywords We Used
PROJECT_NAME
= "MathEngine Dynamics Toolkit”
OUTPUT_DIRECTORY
= ../release
INPUT
= ../../Mst/include \
../../Mst/src
FILE_PATTERNS
= *.h *.c *.hpp *.cpp
HTML_OUTPUT
= simulation_ref
HTML_HEADER
HTML_FOOTER
= MeReferenceHeader.htm
= MeReferenceFooter.htm
HTML_STYLESHEET
= MeDoxygen.css
doxygen
DEMO
Generating Reference Doc

To generate doxygen output:
doxygen yourdoxyfile

Output consists of HTML files in
the output directory specified in
doxyfiles
doxygen
DEMO
Generating a Doc Set

Use batch files, command files, or
(best of all) makefiles:
all:
doxygen Doxyfile1
doxygen Doxyfile2
cp -a here there
cp -a also_here there
rm -rf there/crap
rm -rf there/also_crap
clean:
rm -rf there
doxygen
DEMO
Related Technologies

doxygen is written in, and
available in, Perl:
—http://www.perl.com

GNU tools, such as make:
—http://www.gnu.org/
—For a Windows version, see
http://sources.redhat.com/cygwin/

Other tools for GUI,
generating graphics
doxygen
DEMO
Summary of a Success Story


We produced hundreds of pages of
documentation—really fast.
Tech writers did not write or
copy-edit one line of reference doc
—We had to make do with
programmers with graduate degrees
from Oxford
doxygen
DEMO
Thunderous Applause

In a review, our Alpha
documentation was better than
our competitors Gold:
“MathEngine's documentation is the
best of the three packages. The
manual is very thorough with both a
user's guide and complete reference
to all the classes in the architecture.”
– Gamasutra.com
and
Game Developer Magazine
doxygen
DEMO
Necessity Was the Mother


There was no alternative to
generating documentation
Both MathEngine and Critical Mass
Labs are still going strong with the
product!
doxygen
DEMO
Questions?
Discussion!