Documentation Generation Programs: doxygen demonstration Manuel Gordon (514) 934-3274 manuel@gordonandgordon.com www.gor

2. Documentation Generation Programs: doxygen demonstration Manuel Gordon (514) 934-3274 manuel@gordonandgordon.com www.gordonandgordon.com

3. 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

4. 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/

5. Vortex Helps Simulate Realistic Physical Behavior • You can download great demos...

6. Folders of HTML Reference documentation generated from doxygen pdf files of How-To documentation generated from FrameMaker files Framed by HTML Beta Documentation

7. 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

8. 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...

9. Finding doxygen • http://www.stack.nl/~dimitri/doxygen

10. 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).

11. 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

12. Dimitri van Heesch’s Log • 1985: Got my first computer:a Commodore 64! • 1989: Got my second computer:an Amiga 500 • 09/1992: Started studyingComputer Science at theTechnical University in Eindhoven. • 10/1997: Released version 0.1of doxygen • 11/1997: Accepted a job at Philips Research in the field of software architecture for embedded systems.

13. 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.”

14. 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]); }

15. Viewing Generated Doc void MEAPI MdtBodyGetPosition ( MdtBodyIDb, 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.

16. Generating a doxyfile • doxygen has a command-line interface • To generate a doxyfile (.ini file): doxygen -g yourdoxyfile

17. 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 =

18. 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

19. Generating Reference Doc • To generate doxygen output: doxygen yourdoxyfile • Output consists of HTML files in the output directory specified in doxyfiles

20. 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

21. 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, seehttp://sources.redhat.com/cygwin/ • Other tools for GUI,generating graphics

22. Summary of a Success Story • We produced hundreds of pages of documentation—really fast. • Tech writers did not write orcopy-edit one line of reference doc • We had to make do with programmers with graduate degrees from Oxford

23. 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 andGame Developer Magazine

24. Necessity Was the Mother • There was no alternative to generating documentation • Both MathEngine and Critical Mass Labs are still going strong with the product!

25. Questions?Discussion!