Generating
Reference
Documentation
for APIs and
SDKs
Generating
Reference
Documentation
for APIs and
SDKs
Generating Reference
Documentation for APIs
and SDKs
The Ultimate in Single Sourcing
Manuel Gordon
+1 514 934-3274
manuel@gordonandgordon.com
www.gordonandgordon.com
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
Generating
Reference
Documentation
for APIs and
SDKs
Co-Author Is Absent Today
Greg Rakauskas,
Veritas Software
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!
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!
Generating
Reference
Documentation
for APIs and
SDKs
Where APIs Fit in
THEIR
APPLICATION
THEIR
APPLICATION
OUR API
OUR
SOFTWARE
OUR
SOFTWARE
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!”
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.
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
Generating
Reference
Documentation
for APIs and
SDKs
SDK Documentation:
Greg’s Example
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
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.
Generating
Reference
Documentation
for APIs and
SDKs
DGP Output Examples—
JavaDoc
Generating
Reference
Documentation
for APIs and
SDKs
Doc++
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
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
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
Generating
Reference
Documentation
for APIs and
SDKs
Sample Doc++ Output
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
* <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 )
Generating
Reference
Documentation
for APIs and
SDKs
The DGP Routine
Add Tags and
Comments
Edit and
Test
Build
Docs
Generating
Reference
Documentation
for APIs and
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/
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/
Generating
Reference
Documentation
for APIs and
SDKs
Vortex Helps Simulate
Realistic Physical Behavior

You can download great demos...
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
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
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...
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
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!
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...
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
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).
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
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.
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.”
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]);
}
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.
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
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
=
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
HTML_FOOTER
= MeReferenceHeader.htm
= MeReferenceFooter.htm
HTML_STYLESHEET
= MeDoxygen.css
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
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
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/
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
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
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
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
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
Generating
Reference
Documentation
for APIs and
SDKs
Questions?
Discussion!
Manuel Gordon
+1 514 934-3274
manuel@gordonandgordon.com
www.gordonandgordon.com