Automating API Documentation


Published on

Presentation made on behalf of Alok Sharma at the 2009 STC India Conference in Bangalore.

  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Automating API Documentation

  1. 1. Automating API Documentation STC India Conference, 2009 /** Alok Sharma Selvakumar T S Cadence Design Systems */
  2. 2. API Documentation Methods <ul><li>Maintain documentation in separate source files. </li></ul><ul><li>Maintain documentation in the source code using special markup, then use documentation generators and scripts to automatically generate the documentation from the markup. </li></ul>
  3. 3. Doxygen <ul><li>Documentation generator for C, C++, Java, and so on. </li></ul><ul><li>G enerates documentation directly from the structure and comments in the code. </li></ul><ul><li>Supports multiple output formats. </li></ul><ul><ul><li>HTML, Latex, CHM, Man pages, RTF, Postscript and XML </li></ul></ul><ul><li>Supports multiple platforms. </li></ul><ul><ul><li>Mac OS X, Windows, Linux and Unix </li></ul></ul>
  4. 4. Doxygen Process <ul><li>Create Doxygen configuration file for each project. </li></ul><ul><li>Use markup to document the source code. </li></ul><ul><li>Run Doxygen to create documentation from the source code. </li></ul>
  5. 5. Configuring and Running Doxygen <ul><li>Configure and run Doxygen using the: </li></ul><ul><li>doxygen command </li></ul><ul><li>Doxygen GUI </li></ul>
  6. 6. Using the doxygen Command <ul><li>Create a sample Doxygen config file: </li></ul><ul><ul><li>doxygen –g <configFilename> </li></ul></ul><ul><li>Modify the config file as required </li></ul><ul><li>Run Doxygen using the config file: </li></ul><ul><ul><ul><li>doxygen <configFilename> </li></ul></ul></ul>
  7. 7. Using Doxygen GUI Configure using Wizard or Expert tabs
  8. 8. Using Doxygen GUI Run Doxygen using the Run tab
  9. 9. Sample Configuration File <ul><li># The PROJECT_NAME tag is a single word(or a sequence of </li></ul><ul><li># words surrounded by quotes) that should identify the </li></ul><ul><li># project. </li></ul><ul><li>PROJECT_NAME = &quot;My First Doxygen Project&quot; </li></ul><ul><li># The OUTPUT_DIRECTORY tag is used to specify the </li></ul><ul><li># (relative or absolute) base path where the generated </li></ul><ul><li># documentation will be put. If a relative path is </li></ul><ul><li># entered, it will be relative to the location where </li></ul><ul><li># doxygen was started. If left blank the current </li></ul><ul><li># directory will be used. </li></ul><ul><li>OUTPUT_DIRECTORY = D:STCAPIDOXYGEN_DEMO </li></ul>
  10. 10. Main Configuration Settings <ul><li>Project: </li></ul><ul><li>PROJECT_NAME </li></ul><ul><li>INPUT </li></ul><ul><li>FILE_PATTERNS </li></ul><ul><li>RECURSIVE </li></ul><ul><li>OUTPUT_DIRECTORY </li></ul><ul><li>OUTPUT LANGUAGE </li></ul><ul><li>Documentation extraction </li></ul><ul><li>EXTRACT_ALL </li></ul><ul><li>EXTRACT_PRIVATE </li></ul><ul><li>EXTRACT_STATIC </li></ul><ul><li>GENERATE_TODO_LIST(@todo tag) </li></ul><ul><li>Messages: </li></ul><ul><li>WARNINGS </li></ul><ul><li>WARN_IF_ </li></ul><ul><li>Undocumented: </li></ul><ul><li>WARN_IF_DOC_ERROR </li></ul><ul><li>WARN_LOGFILE </li></ul><ul><li>HTML: </li></ul><ul><li>HTML_OUTPUT </li></ul><ul><li>HTML_FILE_EXTENSION </li></ul><ul><li>HTML_HEADER </li></ul><ul><li>HTML_FOOTER </li></ul><ul><li>HTML_STYLESHEET </li></ul><ul><li>GENERATE_HTMLHELP </li></ul>Latex : GENERATE_LATEX RTF: GENERATE_RTF MAN Pages: GENERATE_MANPAGES Class diagrams: CLASS_DIAGRAMS
  11. 11. Documenting Code <ul><li>Use brief and detailed comments to provide brief and detailed description of entities in your source code </li></ul><ul><li>Use special comments to specify annotations for entities and for formatting purposes </li></ul>
  12. 12. Brief and Detailed Comments <ul><li>/// JavaDoc style: brief </li></ul><ul><li>/** JavaDoc style: detailed </li></ul><ul><li>*/ </li></ul><ul><li>//! Qt style: brief </li></ul><ul><li>/*! Qt style: detailed </li></ul><ul><li>*/ </li></ul>
  13. 13. Special Comments <ul><li>@note to display content for a note </li></ul><ul><li>@a to italicize arguments in running text </li></ul><ul><li>@see to add See Also references. </li></ul><ul><li>@file to document a file </li></ul><ul><li>@todo to identify TBD items </li></ul><ul><li>@bug to identify bugs in code </li></ul><ul><li>And More … </li></ul>
  14. 14. Examples: Class <ul><li>/// Brief description of the MyParser class </li></ul><ul><li>/** </li></ul><ul><li>Detailed description of the MyParser class </li></ul><ul><li>*/ </li></ul><ul><li>class MyParser : public FileParser </li></ul><ul><li>( </li></ul><ul><li>public: </li></ul><ul><li><Member function and variable definition> </li></ul><ul><li>) </li></ul>
  15. 15. Example: Function and Parameter <ul><li>/** Use the WrtParsedFile function to create new input file with valid values in the ProtectData structure. </li></ul><ul><li>@param linestartno marks the starting point for file parsing. </li></ul><ul><li>@param buffer is a character array that stores the parsing output. </li></ul><ul><li>@return </li></ul><ul><li>-# FAIL. </li></ul><ul><li>- If function fails. </li></ul><ul><li>-# SUCCESS. </li></ul><ul><li>- If function succeeds. </li></ul><ul><li>*/ </li></ul><ul><li>UINT_STATUS WrtParsedFile(int linestartno, char buffer) </li></ul>
  16. 16. Example: Notes and Lists <ul><li>/** </li></ul><ul><li>@note Following is the parsing logic of the input file: </li></ul><ul><li>- 1. Validate path whether extension of file is correct or not. </li></ul><ul><li>- 2. Try to open specified file, if it fails return error. </li></ul><ul><li>- 3. Read one line at a time until file ends. </li></ul><ul><li>*/ </li></ul>
  17. 17. Example: Cross References <ul><li>/** </li></ul><ul><li>@see </li></ul><ul><li>- Programmers Guide </li></ul><ul><li>- API Cheat Sheet </li></ul><ul><li>*/ </li></ul>
  18. 18. Let’s See Doxygen @ Work
  19. 19. Creating PDF with HTMLDOC <ul><li>HTMLDOC converts HTML files into: </li></ul><ul><ul><li>PDF </li></ul></ul><ul><ul><li>Postscript </li></ul></ul><ul><li>Supports batch processing using htmldoc command. </li></ul>
  20. 20. Automation: Benefits for Writers <ul><li>Single source for code and documentation </li></ul><ul><li>Updated documentation with each build </li></ul><ul><li>Supports multiple output formats and languages </li></ul><ul><li>Automatically generates class diagrams </li></ul><ul><li>Automatic detection of errors </li></ul><ul><li>Better rapport with team </li></ul><ul><li>Avoid last minute surprises. </li></ul>
  21. 21. Automation: Benefits for R&D <ul><li>Maintain parity between the product code and its documentation </li></ul><ul><li>Ensure better organization of header files. </li></ul><ul><li>Ensure automatic cross referencing. </li></ul><ul><li>Minimize documentation re-work. </li></ul><ul><li>Save time by reducing the review cycles. </li></ul><ul><li>Stay in control of the project timelines (as it is a coordinated effort) </li></ul>
  22. 22. References <ul><li>Doxygen website </li></ul><ul><li>Doxygen page @ Wikipidia </li></ul><ul><li><HTML> DOC Website </li></ul>
  23. 23. Questions ?
  24. 24. Thank You!!!