generating reference documentation for apis and sdks

Generating Reference

Documentation for APIs and

SDKs



SDKsGenerating Reference

Documentation for APIs and SDKs

The Ultimate in Single Sourcing

Manuel Gordon+1 514 934-3274

[email protected]



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



SDKs

Co-Author Is Absent Today

Greg Rakauskas, Veritas Software



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!



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!



SDKs

Where APIs Fit in

THEIR APPLICATION

OUR SOFTWARE

THEIR APPLICATION

OUR SOFTWARE

OUR API



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!”



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.



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



SDKs

SDK Documentation:Greg’s Example



SDKs

SDK Documentation: Audience

Software developers Know a lot about their application Know little about your API

—And often care less! Want sample programs



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.



SDKs

DGP Output Examples—JavaDoc



SDKs

Doc++



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



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



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



SDKs

Sample Doc++ Output



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 * <dl> * <dt>SIG_S_OK</dt> * <dd>The operation succeeded.</dd> * <dt>SIG_E_OUTOFMEMORY</dt> * <dd>Ran out of memory.</dd> * </dl>*/sig_result CTrapPdu::SetV1TrapInfo( const char* pEnterprise, TrapType genericTrap, sig_uint32 specificTrap, sig_uint32

timeStamp, const char* pAgentAddr )



SDKs

The DGP Routine

Add Tags andComments

BuildDocs

Edit andTest



SDKs

JavaDoc

Part of Java Development Kit—Now Java 2 Platform, Standard

Edition (J2SETM)

Output looks like Sun’s own SDK documentation

Available at:http://java.sun.com/j2se/



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/



SDKs

Vortex Helps Simulate Realistic Physical Behavior

You can download great demos...



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



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



SDKs

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 muddle through with

programmers with graduate degrees from Oxford University...



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



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!



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



SDKs

Let’s Look at doxygen

http://www.stack.nl/~dimitri/doxygen Free documentation system Open-source

—GNU General Public License



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



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



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



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



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

}



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.



SDKs

Generating a doxyfile

doxygen has a command-line interface

To generate a doxyfile (.ini file):

doxygen -g yourdoxyfile



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 =



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



SDKs

Generating Reference Doc

To generate doxygen output:

doxygen yourdoxyfile

Output consists of HTML files in the output directory specified in doxyfiles



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



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/



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



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



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, [email protected]

posted May 3, 2002



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 Wongemail

May 5, 2002



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



SDKs

Questions?

Discussion!

Manuel Gordon+1 514 934-3274

[email protected]

generating reference documentation for apis and sdks

Documents

reference documentation

apis http

sdks doc

public apis

documented apis

output slide

api slide

sdks coauthor