Tools for API Documentation

1
Tools for API Documentation

• Swaminathan Moorthy

2
About Me

• Currently working with Sterling Commerce, an ATT
  Company
• Currently the Membership and Employment Manager
  of STC India Chapter
• Part of the Leadership Team of the International
  Technical Communication SIG of STC (Very Recent)

3
What is an API?

• According to Wikipedia
• An application programming interface (API) is a
  source code interface that an operating system or
  library provides to support requests for services
  to be made of it by computer programs.

4
What is an API Guide?

• An API guide is a manual that provides
  information on the code scripts used.

5
API Guide is used by

• Developers who write codes for the software
  product.
• Testers who test the code for the software
  product.

6
Contents of an API Guide

• An API guide contains information on
• Interfaces implemented for the software product.
• Classes defined for the software product.
• Possible Events that can be thrown from the
  software product.
• Errors that can arise from the software product.

7
Tools Available in the Market

• Doxygen
• Javadoc
• NDoc
• Sandcastle
• Epydoc
• Headerdoc
• RDoc
• RubyDoc

8
Dos and Donts

• Dos
• All the class files should be compiled before
  running the tools.
• The correct commenting structure has been used
  / ltSample Contentgt /

9
Dos and Donts

• Donts
• Do not use any other commenting structure. For
  example //

10
Tools Used for this presentation

• Doxygen
• Javadoc

11
Doxygen

• Helps you to generate API Guide for the following
  programming languages
• C
• C
• Java
• Python
• Fortran
• C
• Developed by an individual Dimitri van Heesch
• It was released under General Public License
  (GPL) and is a free software

12
Doxygen

• Doxygen UI enables users to generate
  documentation with few clicks.
• User specifies the source path directory,
  destination directory and the type of files.
• Output when generated, gives the corresponding
  description.

13
Doxygen
14
Doxygen

• Click Wizard. The doxywizard dialog box appears.

15
Doxygen

• Select the Project tab. (This tab is selected
  by default).
• Enter the Source Directory Path in Source code
  directory.
• Enter the Project Name and Project version or
  id values.
• Enter the Destination directory path.

16
Doxygen

• Select the Mode tab.

17
Doxygen

• Select the corresponding options.
• Select the programming language in which the
  source code is written.

18
Doxygen

• Select the Output tab.
• Select the required output formats.

19
Doxygen

• Select the Diagrams tab.
• Select the required options.

20
Doxygen

• Select the required options.
• Click OK to save the changes.

21
Doxygen
22
Doxygen

• Click Save. Save As dialog box opens.
• Enter the path and the filename to save the
  doxygen settings you have defined.

23
Doxygen
24
Doxygen

• Click Start to start the process of generating
  documents. The generated files are placed in the
  Destination directory provided in the Project
  tab of the doxywizard screen.

25
Doxygen
26
Doxygen
27
Javadoc

• Tool from Sun Microsystems
• Combined with packages such as JDK (both Standard
  and Enterprise Editions) and JRE

28
Javadoc

• Set the path variable. This path should point to
  the directory where Java is installed.
• Compile all the Java source files.
• Use the following command to generate javadoc
  output.
• javadoc sourcepath ltltpath of the input Java
  filesgtgt -d ltlt path for the output files gtgt

29
Javadoc Output
30
Javadoc Output
31
Javadoc Options

• Alternatively, you can provide the following
  options along with the Javadoc command
• -sourcepath the location of the sourcecode
  files.
• -d the location where to generated output needs
  to be stored.

32
Useful Resources

• http//api-writing.blogspot.com/
• http//java.sun.com/j2se/javadoc/writingdoccomment
  s/
• http//www.stack.nl/dimitri/doxygen/download.html
  latestsrc
• http//en.wikipedia.org/wiki/Comparison_of_documen
  tation_generators

33

• For more clarifications, please write to me at
• swami_at_mrmwrites.com

34
Thank You