Manuel Gordon

+1 514 934-3274

Vortex, a DGP Success Story

Documentation Generation Programs (DGP) are programs that generate reference documentation for APIs and SDKs based on specially coded comments embedded in the source code of the API.

An SDK now called Vortex was developed at a company now called Critical Mass Labs (http://www.cm-labs.com/) and at MathEngine plc (http://www.mathengine.com/). The Alpha documentation, which was favorably reviewed in the trade press, consisted of:

· HTML Reference Manuals generated from doxygen, a DGP that is freely distributed under the GNU General Public License.

· PDF files of Developer’s Guides generated from FrameMaker files.

· Many example programs.

· An HTML frameset to organize and present the documentation set.

Alpha documentation was developed in five weeks starting from zero for a trade show deadline. Two more Alpha doc sets followed at eight-week intervals. The Beta, which shipped nine months later, retained the basic look of the first Alpha.

Introducing doxygen

You can download doxygen from http://www.stack.nl/~dimitri/doxygen

You can use doxygen to document C, C++, Java, IDL (Corba, COM/ActiveX, other). It generates or supports HTML, LaTeX, RTF (MS-Word), PostScript, hyperlinked PDF, compressed HTML, and man pages (Unix).

doxygen can extract the code structure even from undocumented code. It shows relations between various elements (functions, typedefs, structs, etc.) as hyperlinks. It can also generate inheritance diagrams and other diagrams.

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]);

}

Here is the Reference Documentation doxygen Generated

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.

Generating a doxyfile

doxygen has a command-line interface. To generate a doxyfile (.ini file):

doxygen -g yourdoxyfile

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 =

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 = MeReferenceHeader.htm

HTML_FOOTER = MeReferenceFooter.htm

HTML_STYLESHEET = MeDoxygen.css

For a Copy of the Slides

For more information, see the slides for this presentation
at www.gordonandgordon.com/downloads.html

Gordon & Gordon - 2 - www.gordonandgordon.com