Doxygen – An Overview Kausik Datta Interra Systems India Pvt. Ltd.

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/ )


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.


Getting Started

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>


Data flow model


Configuration file

190+ configuration parameters (Tag) INPUT FILE_PATTERNS OUTPUT_DIRECTORY STRIP_FROM_PATH SOURCE_BROWSER EXTRACT_ALL EXTRACT_PRIVATE EXTRACT_STATIC


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


Special documentation block C/C++ style comment

/* * */ //

Block for Doxygen Javadoc style

/** * */

QT style/*! * */

C++ Style/////!


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*/


Generated Output


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)**/


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);

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. */);

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.


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.


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.

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. */


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.


Preprocessing

Input#define VERSION 200

#define CONST_STRING const char *

#if VERSION >= 200

static CONST_STRING version = "2.xx";

#else


#endif

Generated Output#define VERSION

#define CONST_STRING



Preprocessing

ENABLE_PREPROCESSING = NO #define VERSION




MACRO_EXPANSION = YES#define VERSION


static const char *version = "2.xx";


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;};



/*! 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;};



ENABLE_PREPROCESSING = YESMACRO_EXPANSION = YESEXPAND_ONLY_PREDEF = YESPREDEFINED =

"DECLARE_INTERFACE(name)=class name" \ "STDMETHOD(result,name)=virtual result name" \ "PURE= = 0" \ THIS_= \ THIS= \ __cplusplus


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.

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>


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.*/


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. */

Nesting custom command

ALIASES += Bold{1}="\1" ALIASES += Emph{1}="\1"

/** This is a \Bold{bold \Emph{and} Emphasized} text fragment. */

/** This is a bold and Emphasized text fragment. */


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

Doxygen – An Overview Kausik Datta Interra Systems India Pvt. Ltd.

Documents

Transcript of Doxygen – An Overview Kausik Datta Interra Systems India Pvt. Ltd.