Automating API Documentation

Automating API Documentation STC India Conference, 2009 /** Alok Sharma Selvakumar T S Cadence Design Systems */

API Documentation Methods
Maintain documentation in separate source files.
Maintain documentation in the source code using special markup, then use documentation generators and scripts to automatically generate the documentation from the markup.

Doxygen
Documentation generator for C, C++, Java, and so on.
G enerates documentation directly from the structure and comments in the code.
Supports multiple output formats.
HTML, Latex, CHM, Man pages, RTF, Postscript and XML
Supports multiple platforms.
Mac OS X, Windows, Linux and Unix

Doxygen Process
Create Doxygen configuration file for each project.
Use markup to document the source code.
Run Doxygen to create documentation from the source code.

Configuring and Running Doxygen
Configure and run Doxygen using the:
doxygen command
Doxygen GUI

Using the doxygen Command
Create a sample Doxygen config file:
doxygen –g <configFilename>
Modify the config file as required
Run Doxygen using the config file:
doxygen <configFilename>

Using Doxygen GUI Configure using Wizard or Expert tabs

Using Doxygen GUI Run Doxygen using the Run tab

Sample Configuration File
# The PROJECT_NAME tag is a single word(or a sequence of
# words surrounded by quotes) that should identify the
# project.
PROJECT_NAME = "My First Doxygen Project"
# 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 = D:STCAPIDOXYGEN_DEMO

Main Configuration Settings
Project:
PROJECT_NAME
INPUT
FILE_PATTERNS
RECURSIVE
OUTPUT_DIRECTORY
OUTPUT LANGUAGE
Documentation extraction
EXTRACT_ALL
EXTRACT_PRIVATE
EXTRACT_STATIC
GENERATE_TODO_LIST(@todo tag)
Messages:
WARNINGS
WARN_IF_
Undocumented:
WARN_IF_DOC_ERROR
WARN_LOGFILE
HTML:
HTML_OUTPUT
HTML_FILE_EXTENSION
HTML_HEADER
HTML_FOOTER
HTML_STYLESHEET
GENERATE_HTMLHELP
Latex : GENERATE_LATEX RTF: GENERATE_RTF MAN Pages: GENERATE_MANPAGES Class diagrams: CLASS_DIAGRAMS

Documenting Code
Use brief and detailed comments to provide brief and detailed description of entities in your source code
Use special comments to specify annotations for entities and for formatting purposes

Brief and Detailed Comments
/// JavaDoc style: brief
/** JavaDoc style: detailed
*/
//! Qt style: brief
/*! Qt style: detailed
*/

Special Comments
@note to display content for a note
@a to italicize arguments in running text
@see to add See Also references.
@file to document a file
@todo to identify TBD items
@bug to identify bugs in code
And More …

Examples: Class
/// Brief description of the MyParser class
/**
Detailed description of the MyParser class
*/
class MyParser : public FileParser
(
public:
<Member function and variable definition>
)

Example: Function and Parameter
/** Use the WrtParsedFile function to create new input file with valid values in the ProtectData structure.
@param linestartno marks the starting point for file parsing.
@param buffer is a character array that stores the parsing output.
@return
-# FAIL.
- If function fails.
-# SUCCESS.
- If function succeeds.
*/
UINT_STATUS WrtParsedFile(int linestartno, char buffer)

Example: Notes and Lists
/**
@note Following is the parsing logic of the input file:
- 1. Validate path whether extension of file is correct or not.
- 2. Try to open specified file, if it fails return error.
- 3. Read one line at a time until file ends.
*/

Example: Cross References
/**
@see
- Programmers Guide
- API Cheat Sheet
*/

Let’s See Doxygen @ Work

Creating PDF with HTMLDOC
HTMLDOC converts HTML files into:
PDF
Postscript
Supports batch processing using htmldoc command.

Automation: Benefits for Writers
Single source for code and documentation
Updated documentation with each build
Supports multiple output formats and languages
Automatically generates class diagrams
Automatic detection of errors
Better rapport with team
Avoid last minute surprises.

Automation: Benefits for R&D
Maintain parity between the product code and its documentation
Ensure better organization of header files.
Ensure automatic cross referencing.
Minimize documentation re-work.
Save time by reducing the review cycles.
Stay in control of the project timelines (as it is a coordinated effort)

References
Doxygen website http://www.stack.nl/~dimitri/doxygen
Doxygen page @ Wikipidia http://en.wikipedia.org/wiki/Doxygen
<HTML> DOC Website http://www.htmldoc.org

Questions ?

Thank You!!!

Automating API Documentation

by selvats

Accessibility

Upload Details

Usage Rights

2 Embeds 9

Statistics

Automating API Documentation Presentation Transcript

http://www.slideshare.net	5
http://www.linkedin.com	4