Presentation is loading. Please wait.

Presentation is loading. Please wait.

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

Similar presentations


Presentation on theme: "Doxygen – An Overview Kausik Datta Interra Systems India Pvt. Ltd."— Presentation transcript:

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

2 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/ )http://www.stack.nl/~dimitri/

3 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.

4 Interra Systems India Pvt. Ltd.4 Getting Started

5 Interra Systems India Pvt. Ltd.5 Getting Started Command line based tool GUI available for Win 32 Document code Generate Config file doxygen -g Edit Config File Run Doxygen doxygen

6 Interra Systems India Pvt. Ltd.6 Data flow model

7 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

8 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

9 Interra Systems India Pvt. Ltd.9 Special documentation block C/C++ style comment /* * */ // Block for Doxygen Javadoc style /** * */ QT style /*! * */ C++ Style /// //!

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

11 Interra Systems India Pvt. Ltd.11 Generated Output

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

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

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

15 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.

16 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.

17 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.

18 Interra Systems India Pvt. Ltd.18 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. */

19 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.

20 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";

21 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";

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

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

24 Interra Systems India Pvt. Ltd.24 Preprocessing - Example ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES PREDEFINED = "DECLARE_INTERFACE(name)=class name" \ "STDMETHOD(result,name)=virtual result name" \ "PURE= = 0" \ THIS_= \ THIS= \ __cplusplus

25 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.

26 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 "(" ")" "()" "::" ( "::") n "(" ")" ( "::") n "()" ( "::") n

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

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

29 Interra Systems India Pvt. Ltd.29 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. */

30 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


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

Similar presentations


Ads by Google