1. Generating Reference Documentation for APIs and SDKs

2. The Ultimate in Single Sourcing Manuel Gordon +1 514 934-3274 manuel@gordonandgordon.com www.gordonandgordon.com

3. Generating Reference Documentation for APIs and SDKs 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. Generating Reference Documentation for APIs and SDKs Co-Author Is Absent Today Greg Rakauskas, Veritas Software

5. Generating Reference Documentation for APIs and SDKs What’s Ahead What are APIs and SDKs, anyway? Documentation Generation Programs (DGPs) —JavaDoc —DOC++ —doxygen A DGP success story A Taste of doxygen One Commercial Package —Document! X Questions, answers?, and comments!

6. Generating Reference Documentation for APIs and SDKs What is an API? Application Programming Interface Greg’s definition: —A set of functions (or methods) that a program exposes to enable other programs to communicate with it. Manny’s definition —An interface used by programmers to build applications on top of your system —Consists of function declarations —Not a GUI!

7. Generating Reference Documentation for APIs and SDKs Where APIs Fit in THEIR APPLICATION OUR SOFTWARE THEIR APPLICATION OUR SOFTWARE OUR API

8. Generating Reference Documentation for APIs and SDKs What is an SDK? Software Development Kit —One or more documented APIs, packaged as a product SDK includes: —Libraries + —APIs (may be embodied by header files) + —Sample programs + —Documentation “No documentation, no SDK!”

9. Generating Reference Documentation for APIs and SDKs SDK Documentation Developer’s Guide —Overview & description —Installation procedure SDK requirements (OS, patches) Environment set up (compilers, libraries) —How to write applications using the API Usually based on code samples Reference Manual —For each function: Description Parameters Return codes or values Notes etc.

10. Generating Reference Documentation for APIs and SDKs Examples of SDKs HTML Help 3.1 APIs —http://msdn.microsoft.com/library/ default.asp?url=/library/en-us/htmlhelp/ html/vsconHH1Start.asp Java Development Kit (JDK) —http://java.sun.com/j2se/1.3/docs/api/index.html Windows SDK and.NET Enterprise Server SDKs —http://msdn.microsoft.com/library/en-us/ sdkintro/contents_49d7.asp?frame=true

11. Generating Reference Documentation for APIs and SDKs SDK Documentation: Greg’s Example

12. Generating Reference Documentation for APIs and SDKs SDK Documentation: Audience Software developers Know a lot about their application Know little about your API —And often care less! Want sample programs

13. Generating Reference Documentation for APIs and SDKs What Are DGPs? Documentation Generation Programs (Greg’s neologism) Programs that parse source code for embedded tags and comments Output comments into various formats such as HTML, LaTeX, RTF You can add one to the build script for your product, to automatically generate Reference Manual. Usually not very good for Developer’s Guide.

14. Generating Reference Documentation for APIs and SDKs DGP Output Examples— JavaDoc

15. Generating Reference Documentation for APIs and SDKs Doc++

16. Generating Reference Documentation for APIs and SDKs The Good News about DGPs Ideal for documenting public APIs for groups that must use each other’s code Ideal for high-volume, low-polish documentation Documentation source physically located next to code, as comments Easy to change documentation when code changes Many global changes to source code automatically update the doc Both developers and writers can modify the reference documentation

17. Generating Reference Documentation for APIs and SDKs The Bad News Ownership can be unclear Tweaking output format often required Your developers may not write well in English Perception of extra work for developers Incorrect information: quality control can be a problem

18. Generating Reference Documentation for APIs and SDKs In Balance, a “Win/Win” Situation Greater incentive for developers to comment code Accurate reference information: —Smaller communication gap —Automatic update Writers can put more focus on code samples, Developer’s Guide

19. Generating Reference Documentation for APIs and SDKs Sample Doc++ Output

20. Generating Reference Documentation for APIs and SDKs Sample Doc++ Input (in Source Code) /**Call this method to set all trap PDU information except * variable bindings. * @param bstrEnterprise [in] Type of object generating the trap.... * @return * * SIG_S_OK * The operation succeeded. * SIG_E_OUTOFMEMORY * Ran out of memory. * */ sig_result CTrapPdu::SetV1TrapInfo( const char* pEnterprise, TrapType genericTrap, sig_uint32 specificTrap, sig_uint32 timeStamp, const char* pAgentAddr )

21. Generating Reference Documentation for APIs and SDKs The DGP Routine

22. Generating Reference Documentation for APIs and SDKs JavaDoc Part of Java Development Kit —Now Java 2 Platform, Standard Edition (J2SE TM ) Output looks like Sun’s own SDK documentation Available at: http://java.sun.com/j2se/

23. Generating Reference Documentation for APIs and SDKs A DGP Success Story An SDK now called Vortex and Karma —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/

24. Generating Reference Documentation for APIs and SDKs Vortex Helps Simulate Realistic Physical Behavior You can download great demos...

25. Generating Reference Documentation for APIs and SDKs Beta Documentation Folders of HTML Reference documentation generated from doxygen pdf files of How-To documentation generated from FrameMaker files Many sample programs Presented in HTML frameset

26. Generating Reference Documentation for APIs and SDKs 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

27. Generating Reference Documentation for APIs and SDKs 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 muddle through with programmers with graduate degrees from Oxford University...

28. Generating Reference Documentation for APIs and SDKs Thunderous Applause In a review, our Alpha documentation was rated higher 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

29. Generating Reference Documentation for APIs and SDKs Necessity Was the Mother There was no alternative to generating documentation Both MathEngine and Critical Mass Labs are still going strong with the product!

30. Generating Reference Documentation for APIs and SDKs 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...

31. Generating Reference Documentation for APIs and SDKs Let’s Look at doxygen http://www.stack.nl/~dimitri/doxygen Free documentation system Open-source —GNU General Public License

32. Generating Reference Documentation for APIs and SDKs 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).

33. Generating Reference Documentation for APIs and SDKs 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

34. Generating Reference Documentation for APIs and SDKs 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.

35. Generating Reference Documentation for APIs and SDKs A Unix-Flavored Tool Supports many flavors of Unix Long descriptions of how to compile on various Unix flavors For Windows (until recently) : —“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. ”

36. Generating Reference Documentation for APIs and SDKs 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]); }

37. Generating Reference Documentation for APIs and SDKs 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.

38. Generating Reference Documentation for APIs and SDKs Generating a doxyfile doxygen has a command-line interface To generate a doxyfile (.ini file): doxygen -g yourdoxyfile

39. Generating Reference Documentation for APIs and SDKs 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 =

40. Generating Reference Documentation for APIs and SDKs 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

41. Generating Reference Documentation for APIs and SDKs Generating Reference Doc To generate doxygen output: doxygen yourdoxyfile Output consists of HTML files in the output directory specified in doxyfiles

42. Generating Reference Documentation for APIs and SDKs Generating a Documentation 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

43. Generating Reference Documentation for APIs and SDKs 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/

44. Generating Reference Documentation for APIs and SDKs UNIX Culture and Open Source Culture Bring Benefits “If you are using Microsoft's Developer Studio... DoxBar [can] run doxygen from within Developer Studio.” “Pascal Binggeli is working on an integrated development environment for Doxygen called DoxygenStudio. It will be for Windows only.” “If VIM is your favourite editor (it is mine!), then Ralf Schandl has a some macros and syntax highlighting files for you.” “If you are using the Emacs editor, take a look at Tom Emerson's page for a lisp script to simplify writing doxygen comments.” “VXL project produced some code to manage documentation production for multiple doxygen runs over 10s of libraries...” —http://www.stack.nl/~dimitri/doxygen/download.html#helpers

45. Generating Reference Documentation for APIs and SDKs Even Technical Writers Get Into The Act “Glenn Maxey has released has released The TechPubs Tools (TPT) which wraps around any number of mini-HTML systems and creates a comprehensive HTML system complete with table of contents and an auto-generated index/concordance.” —http://www.stack.nl/~dimitri/doxygen/download.html#helpers “[D]ownload www.voyanttech.com/tp_tools.zip (1.8 MB). Unzip and launch tp_tools/_start_here.html... “The docs are at ***ALPHA*** level. Since cranking them out in a hurry over Christmas, I've discovered many embarrassing mistakes for a tech writer.” —Glenn Maxey, email, May 5 2002

46. Generating Reference Documentation for APIs and SDKs What about Commercial Packages? “We chose [Document! X from Innovasys] because it provides.NET and MSHelp2 support AND because it lets us work in very flexible ways with the documentation generation.” “Using Document! X, we can use [developers’] information when appropriate, and override their information with our own writing where we think it's best.” —Lydia Wong, nettechwriters@yahoogroups.com posted May 3, 2002

47. Generating Reference Documentation for APIs and SDKs I May Do Windows, But I Don’t Do perl! “[Many technical writers will] look at a tool with lots of programmer-y interfaces and say, ‘no way—I'm a writer, not a programmer.’ I think Document X fits us well in part because of this.” —Lydia Wong email May 5, 2002

48. Generating Reference Documentation for APIs and SDKs Where Do I Get More Information? Here is an incomplete list of DGPs: —http://www.stack.nl/~dimitri/doxygen/links.html For a discussion group on APIs and SDKs: —http://groups.yahoo.com/group/nettechwriters/ —Low volume, high quality —Lydia and Glenn are frequent contributors

49. Generating Reference Documentation for APIs and SDKs Questions? Discussion! Manuel Gordon +1 514 934-3274 manuel@gordonandgordon.com www.gordonandgordon.com