doxygen – an overview kausik datta interra systems india pvt. ltd
TRANSCRIPT
Doxygen – An Overview
Kausik Datta
Interra Systems India Pvt. Ltd.
Interra Systems India Pvt. Ltd. 2
What is Doxygen?
Doxygen is a documentation system for different languages like C++, C, Java, Python, Fortran, VHDL, PHP, C#
Developed by Dimitri van Heesch
( http://www.stack.nl/~dimitri/ )
Interra Systems India Pvt. Ltd. 3
Use Model
Generate an on-line documentation browser and/or an off-line reference manual from a set of documented source files. The documentation is extracted directly from the
sources. The documentation is consistent with the source code.
Extract the code structure from undocumented source files by automatically generating dependency graphs, inheritance diagrams, and collaboration diagrams.
Interra Systems India Pvt. Ltd. 4
Getting Started
Interra Systems India Pvt. Ltd. 5
Getting Started
Command line based tool GUI available for Win 32
Document code Generate Config file
doxygen -g <config_file> Edit Config File Run Doxygen
doxygen <config_file>
Interra Systems India Pvt. Ltd. 6
Data flow model
Interra Systems India Pvt. Ltd. 7
Configuration file
190+ configuration parameters (Tag) INPUT FILE_PATTERNS OUTPUT_DIRECTORY STRIP_FROM_PATH SOURCE_BROWSER EXTRACT_ALL EXTRACT_PRIVATE EXTRACT_STATIC
Interra Systems India Pvt. Ltd. 8
Code documentation
Introduce source file with meaningful comments
Introduce a class with a well-defined comment header
Introduce a function with a well-defined comment header
Interra Systems India Pvt. Ltd. 9
Special documentation block C/C++ style comment
/* * */ //
Block for Doxygen Javadoc style
/** * */
QT style/*! * */
C++ Style/////!
Interra Systems India Pvt. Ltd. 10
Introduce source file with meaningful comments/************************************ MODULE : Verilog Parser* FILE : 122.cpp* AUTHOR : Kausik Datta * DATE : 18-May-2009* DESCRIPTION : Detailed description of the
file* MODIFIED : 1.1 (20-May-2009)** Interra Systems Inc.* Copyright (C) 2003********************************/
/** @defgroup module1 Verilog Parser * Defining a module */
/*** \file 122.cpp* \ingroup module1* \brief Defines the base class of all Object
Classes.* \author Kausik Datta * \date 18-May-2009* \version 1.1 (20-May-2009)* * Detailed description of the file* * Interra Systems Inc.* * Copyright (C) 2003*/
Interra Systems India Pvt. Ltd. 11
Generated Output
Interra Systems India Pvt. Ltd. 12
Introduce a class with a well-defined comment header/***************************************** MODULE : Verilog Parser* CLASS : baseObject* AUTHOR : Kausik Datta* DATE : 18-May-2009* DESCRIPTION : This class contains the
Object Type field which should be an unique id for a class.
* MODIFIED : 1.1 (20-May-2009)*****************************************/
/*** \ingroup module1* \class baseObject* \brief Class to represent the base class of all objects* \author Kausik Datta* \date 18-May-2009** This class contains the Object Type field which should be an unique id for a class.** \version 1.1 (20-May-2009)**/
Interra Systems India Pvt. Ltd. 13
Introduce a function with a well-defined comment header/****************************************** FUNCTION NAME : populate** AUTHOR : Kausik Datta** DATE : 18-May-2009** ARGUMENTS : uiObjTypeAndFlagsP
an unsigned integer argument; initial value of uiObjTypeAndFlags
** RETURN VALUE : Error code** DESCRIPTION : Detailed description
of the function.** MODIFICATION : 1.1 (20-May-2009)** ************************************/
/*!\author Kausik Datta\date 18-May-2009\param uiObjTypeAndFlagsP an unsigned integer argument; initial value of uiObjTypeAndFlags\return Error code
Detailed description of the function.
\version 1.1 (20-May-2009)\sa baseObject()*/
virtual UINT32_T populate(UINT32_T uiObjTypeAndFlagsP);
Interra Systems India Pvt. Ltd. 14
Direction attribute
//! This variable is used to store object type.
UINT32_T uiObjTypeAndFlags;
UINT32_T uiObjTypeAndFlags; /*!< This variable is used to store object type */
void foo(int v /**< [in] docs for input parameter v. */);
Interra Systems India Pvt. Ltd. 15
Code documentation
Blank line indicates start/end of paragraph By default the brief descriptions become the first
sentence of the detailed descriptions direction attribute “<“ can only be used to document
members and parameters Documentation blocks are usually placed in front of
the declaration or definition of a file, class or namespace or in front or after one of its members.
Doxygen allows to put documentation blocks anywhere in the code Structural command is required inside the
documentation block.
Interra Systems India Pvt. Ltd. 16
Some strucrural commands
\struct to document a C-struct. \union to document a union. \enum to document an enumeration type. \fn to document a function. \var to document a variable or typedef or enum value. \def to document a #define. \typedef to document a type definition. \file to document a file. \namespace to document a namespace.
Interra Systems India Pvt. Ltd. 17
List
/*! * A list of events: * - mouse events * -# mouse move event * -# mouse click event\n * More info about the
click event. * -# mouse double click
event * - keyboard events * -# key down event * -# key up event * * More text here. */
A list of events: mouse events
a. mouse move event b. mouse click event
More info about the click event.
c. mouse double click event
keyboard events a. key down event b. key up event
More text here.
Interra Systems India Pvt. Ltd. 18
List
/*! * A list of events: * <ul> * <li> mouse events * <ol> * <li>mouse move event * <li>mouse click event\n * More info about the click event. * <li>mouse double click event * </ol> * <li> keyboard events * <ol> * <li>key down event * <li>key up event * </ol> * </ul> * More text here. */
Interra Systems India Pvt. Ltd. 19
List/** * Text before the list * - list item 1 * - sub item 1 * - sub sub item 1 * - sub sub item 2 * . * The dot above ends the sub sub item
list. * More text for the first sub item * . * The dot above ends the first sub item. * More text for the first list item * - sub item 2 * - sub item 3 * - list item 2 * . * More text in the same paragraph. * * More text in a new paragraph. */
Text before the list list item 1
sub item 1 sub sub item 1 sub sub item 2
The dot above ends the sub sub item list. More text for the first sub item
The dot above ends the first sub item. More text for the first list item
sub item 2 sub item 3
list item 2
More text in the same paragraph.
More text in a new paragraph.
Interra Systems India Pvt. Ltd. 20
Preprocessing
Input#define VERSION 200
#define CONST_STRING const char *
#if VERSION >= 200
static CONST_STRING version = "2.xx";
#else
static CONST_STRING version = "1.xx";
#endif
Generated Output#define VERSION
#define CONST_STRING
static CONST_STRING version = "2.xx";
Interra Systems India Pvt. Ltd. 21
Preprocessing
ENABLE_PREPROCESSING = NO #define VERSION
#define CONST_STRING
static CONST_STRING version = "2.xx";
static CONST_STRING version = "1.xx";
MACRO_EXPANSION = YES#define VERSION
#define CONST_STRING
static const char *version = "2.xx";
Interra Systems India Pvt. Ltd. 22
Preprocessing - Example
/*! A reference to an IID */#ifdef __cplusplus#define REFIID const IID &#else#define REFIID const IID *#endif
/*! The IUnknown interface */DECLARE_INTERFACE(IUnknown){ STDMETHOD(HRESULT,QueryInterface) (THIS_ REFIID iid, void **ppv) PURE; STDMETHOD(ULONG,AddRef) (THIS) PURE; STDMETHOD(ULONG,Release) (THIS) PURE;};
Interra Systems India Pvt. Ltd. 23
Preprocessing - Example
/*! A reference to an IID */#define REFIID
/*! The IUnknown interface */class IUnknown{ virtual HRESULT QueryInterface ( REFIID iid, void **ppv) = 0; virtual ULONG AddRef () = 0; virtual ULONG Release () = 0;};
Interra Systems India Pvt. Ltd. 24
Preprocessing - Example
ENABLE_PREPROCESSING = YESMACRO_EXPANSION = YESEXPAND_ONLY_PREDEF = YESPREDEFINED =
"DECLARE_INTERFACE(name)=class name" \ "STDMETHOD(result,name)=virtual result name" \ "PURE= = 0" \ THIS_= \ THIS= \ __cplusplus
Interra Systems India Pvt. Ltd. 25
Automatic Link Generation
Links to web pages and mail addresses automatically replace any URLs and mail
addresses found in the documentation by links (in HTML).
Links to classes All words in the documentation that
correspond to a documented class will automatically be replaced by a link to the page containing the documentation of the class.
To prevent this behavior put a % in front of the word.
Interra Systems India Pvt. Ltd. 26
Automatic Link Generation
Links to files All words that contain a dot (.) that is not the last
character in the word are considered to be file names. Links to functions
<functionName>"("<argument-list>")" <functionName>"()" "::"<functionName> (<className>"::")n<functionName>"("<argument-
list>")" (<className>"::")n<functionName>"("<argument-
list>")"<modifiers> (<className>"::")n<functionName>"()" (<className>"::")n<functionName>
Interra Systems India Pvt. Ltd. 27
Automatic Link Generation/*! \file autolink.cpp Testing automatic link generation. A link to a member of the Test class: Test::member, More specific links to the each of the overloaded members: Test::member(int) and Test#member(int,int)
A link to a protected member variable of Test: Test#var,
A link to the global enumeration type #GlobEnum. A link to the define #ABS(x). A link to the destructor of the Test class: Test::~Test, A link to the typedef ::B. A link to the enumeration type Test::EType A link to some enumeration values Test::Val1 and ::GVal2*/
/*! Since this documentation block belongs to the class Test no link to Test is generated.
Two ways to link to a constructor are: #Test and Test().
Links to the destructor are: #~Test and ~Test(). A link to a member in this class: member().
More specific links to the each of the overloaded members: member(int) and member(int,int). A link to the variable #var.
A link to the global typedef ::B.
A link to the global enumeration type #GlobEnum. A link to the define ABS(x). A link to a variable \link #var using another text\endlink as a link. A link to the enumeration type #EType.
A link to some enumeration values: \link Test::Val1 Val1 \endlink and ::GVal1.
And last but not least a link to a file: autolink.cpp. \sa Inside a see also section any word is checked, so EType, Val1, GVal1, ~Test and member will be replaced by links in HTML.*/
Interra Systems India Pvt. Ltd. 28
Alias
Simple aliases ALIASES += sideeffect="\par Side Effects:\n“
Aliases with arguments ALIASES += l{1}="\ref \1“ /** See \l{SomeClass} for more information. */ /** See \ref SomeClass for more information. */ ALIASES += l{2}="\ref \1 \"\2\"" /** See \l{SomeClass,Some Text} for more information.
*/ /** See \ref SomeClass "Some Text" for more
information. */
Interra Systems India Pvt. Ltd. 29
Nesting custom command
ALIASES += Bold{1}="<b>\1</b>" ALIASES += Emph{1}="<em>\1</em>"
/** This is a \Bold{bold \Emph{and} Emphasized} text fragment. */
/** This is a <b>bold <em>and</em> Emphasized</b> text fragment. */
Interra Systems India Pvt. Ltd. 30
Reference
Tools doxywizard (Win 32)
Download http://www.stack.nl/~dimitri/doxygen/index.htm
Examples The KDevelop API Documentation The Xerces-C++ Documentation D-Bus documentation Visualization Toolkit IBM's International Components for Unicode