Generating Reference Documentation for APIs and SDKs.
-
Upload
daphne-edgett -
Category
Documents
-
view
240 -
download
3
Transcript of Generating Reference Documentation for APIs and SDKs.
Generating Reference
Documentation for APIs and
SDKs
Generating Reference
Documentation for APIs and
SDKsGenerating Reference
Documentation for APIs and SDKs
The Ultimate in Single Sourcing
Manuel Gordon+1 514 934-3274
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
OUR SOFTWARE
THEIR APPLICATION
OUR SOFTWARE
OUR API
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 andComments
BuildDocs
Edit andTest
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 orcopy-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 andGame 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 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.
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 = MeReferenceHeader.htm
HTML_FOOTER = 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, [email protected]
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 Wongemail
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