Generating Reference Documentation for APIs and SDKs

1
(No Transcript)
2

• Generating Reference Documentation for APIs and
  SDKs
• The Ultimate in Single Sourcing
• Manuel Gordon
• 1 514 934-3274
• manuel_at_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
Co-Author Is Absent Today

• Greg Rakauskas, Veritas Software

5
Whats 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
What is an API?

• Application Programming Interface
• Gregs definition
• A set of functions (or methods) that a program
  exposes to enable other programs to communicate
  with it.
• Mannys definition
• An interface used by programmers to build
  applications on top of your system
• Consists of function declarations
• Not a GUI!

7
Where APIs Fit in
OUR API
8
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
SDK Documentation

• Developers 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
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?frametrue

11
SDK DocumentationGregs Example
12
SDK Documentation Audience

• Software developers
• Know a lot about their application
• Know little about your API
• And often care less!
• Want sample programs

13
What Are DGPs?

• Documentation Generation Programs (Gregs
  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 Developers Guide.

14
DGP Output ExamplesJavaDoc
15
Doc
16
The Good News about DGPs

• Ideal for documenting public APIs for groups that
  must use each others 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
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
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,
  Developers Guide

19
Sample Doc Output
20
Sample Doc Input (in Source Code)

• /Call this method to set all trap PDU
  information except
• variable bindings.
• _at_param bstrEnterprise in Type of object
  generating the trap. ...
• _at_return
• ltdlgt
• ltdtgtSIG_S_OKlt/dtgt
• ltddgtThe operation succeeded.lt/ddgt
• ltdtgtSIG_E_OUTOFMEMORYlt/dtgt
• ltddgtRan out of memory.lt/ddgt
• lt/dlgt/
• sig_result CTrapPduSetV1TrapInfo( const char
  pEnterprise,
• TrapType genericTrap, sig_uint32
  specificTrap, sig_uint32 timeStamp, const char
  pAgentAddr )

21
The DGP Routine
22
JavaDoc

• Part of Java Development Kit
• Now Java 2 Platform, Standard Edition (J2SETM)
• Output looks like Suns own SDK documentation
• Available athttp//java.sun.com/j2se/

23
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
Vortex Helps Simulate Realistic Physical Behavior

• You can download great demos...

25
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
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
Summary of a Success Story

• We produced hundreds of pages of
  documentationreally 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...

28
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

29
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
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
Lets Look at doxygen

• http//www.stack.nl/dimitri/doxygen
• Free documentation system
• Open-source
• GNU General Public License

32
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
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
Dimitri van Heeschs Log

• 1985 Got my first computera Commodore 64!
• 1989 Got my second computeran 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.

35
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
Coding doxygen Comments

• /
• The body's position vector is returned in
• _at_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-gtbodyTM3)

37
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 a doxyfile

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

39
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
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 Doc

• To generate doxygen output
• doxygen yourdoxyfile
• Output consists of HTML files in the output
  directory specified in doxyfiles

42
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
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.c
  om/cygwin/

44
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
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
• Download 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
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_at_yahoogroups.composted
  May 3, 2002

47
I May Do Windows,But I Dont Do perl!

• Many technical writers will look at a tool
  with lots of programmer-y interfaces and say, no
  wayI'm a writer, not a programmer. I think
  Document X fits us well in part because of this.
• Lydia WongemailMay 5, 2002

48
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
Questions?Discussion!Manuel Gordon1 514
934-3274 manuel_at_gordonandgordon.comwww.gordon
andgordon.com