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