Adam Huječek NSWI126

Size: px

Start display at page:

Download "Adam Huječek NSWI126"

Darrell Arnold
6 years ago
Views:

1 Adam Huječek NSWI126

2 Tool for generating documentation from annotated sources Supported languages: C, C++, Java, Objective-C, Python, IDL, Fortran, VHDL, PHP, C#, D Doxywizard : GUI front-end for configuring and running doxygen

4 Generating config file (default name Doxyfile) doxygen -g <config file> Tags are commented Generating documentation doxygen <config_file> Config file = = my_config_dir TAG_NAME = "property \ value" LIST_TAG += $(ENV_VARIABLE_NAME) "sideeffect=\par Side Effects:\n"

5 HTML (GENERATE_HTML = YES) LATEX (GENERATE_LATEX = YES) Man pages (GENERATE_MAN = YES) RTF (GENERATE_RTF = YES) XML (GENERATE_XML = YES)

6 Compiled HTML Help (HTML Help workshop a GENERATE_HTMLHELP = YES) Qt Compressed Help (qhelpgenerator a GENERATE_QHP = YES) Eclipse Help (GENERATE_ECLIPSEHELP = YES) XCode DocSets (GENERATE_DOCSET = YES) PostScript (LATEX: make ps, recommended PDF_HYPERLINKS = NO) PDF (LATEX: make pdf, recommended USE_PDFLATEX = YES)

7 INPUT (list of files and directories) FILE_PATTERNS (default many common source files extensions) RECURSIVE (YES/NO) EXCLUDE, EXCLUDE_PATTERNS

8 Element documentation consists of: Brief description Detailed description in body Documentary comments inside functions merged with Detailed description (HIDE_IN_BODY_DOCS)

9 /** *... text... */ /// ///... text... /// /*! *... text... */ //! //!... text... //! /*!... text... */ /**... text... */

10 /*! \brief Brief description. * Brief description continued. * * Detailed description starts here. */ Brief description. * Brief description continued. * * Detailed description starts here. */

11 //! Brief description. //! Detailed description //! starts here. /// Brief description. /** Detailed description. */ //! Brief description, which is //! really a detailed description since it spans multiple //! lines. /*! Another detailed description! */

12 JAVADOC_AUTOBRIEF = YES /** Brief desc.\ which ends at this dot. Details * follow here. */ /// Brief description which ends at this dot. Details /// follow here.

13 QT_AUTOBRIEF = YES /*! Brief description which ends at this dot. Details * follow here. */

14 In front of the element s declaration or definition Header files can be small After members and parameters using < Anywhere else (except inside functions and ordinary comments) using structural commands (not recommended): \file, \def, \enum, \package, \fn, \class, \var, \property, \typedef

15 To document members the class must be documented To document global objects, the file they are defined in must be documented (at least /*! \file */ ) functions, typedefs, enum, macros, etc

16 /*! A test class. Detailed desc here. */ class Test { public: /** An enum type. * The documentation block cannot be put after the enum! */ enum EnumType { int EVal1, /**< enum value 1 */ int EVal2 /**< enum value 2 */ }; void member(); //!< a member function. void foo(int v /**< [in] docs for input parameter v. */); protected: int value; ///< description ///< after the integral member };

18 /*! \file test.h \brief A Documented file. Details. */ /*! \def MIN(a,b) \brief A macro that returns the minumum of \a a and \a b. Details. */ /*! \def MAX(a,b) \brief A macro that returns the maximum of \a a and \a b. Details. */ #define MIN(a,b) (((a)>(b))?(b):(a)) #define MAX(a,b) (((a)>(b))?(a):(b))

19 fnc.cpp */ /** Example function. * This is detailed description of the function. [in] dummy Input parameter. [out] outpar Output parameter. [in,out] IOpar In and out parameter. Whether the function succeeds. TRUE Success. FALSE Failure. exception If its Friday. * * Example Usage: * int* arr; * int inout = 5; * if (example(3, arr, inout)) { //example usage * report_success(); * delete outpar; * } */ boolean example(int dummy, int[]& outpar, int& IOpar);

21 Using -, + or * Nested using indentation (if tabbed, TAB_SIZE sets width) Numbered using -# or 1. / 2. /etc. Dot on empty line ends the list

$/*! * A list of events: * - mouse events * -# mouse move event * -# mouse click event\n * More info about the click$

22 /*! * 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 * 1. key down event * 2. key up event * * More text here. */

23 Using HTML tags ul, ol, li /*! * A list of events: * <ul> * <li> mouse events * <ol> * <li>mouse move event * <li>mouse click event<br> * 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. */

24 Commands \arg and \li for compatibility with qdoc and KDoc Only simple non-nested lists /*! \arg \c AlignLeft left alignment. \arg \c AlignCenter center alignment. \arg \c AlignRight right alignment No other types of alignment are supported. */

25 To structure the documentation Group can contain: files, namespaces, classes, functions, variables, enums, typedefs, macros and other groups Definition \defgroup <one_word_name> (group title) \addtogroup <one_word_name> (group title) The same, only the name do not have to be unique Place element to group \ingroup <one_word_name> >

26 ///\file group.cpp group1 The First Group * This is the first group */ class C1 in group 1 */ class C1 {}; /** group2 class C2 in group 1 and 2 */ class C2 {}; /** function in group 1 */ void func() {} */ // end of group1 group2 The Second Group group1 * This is the second group. */

28 If default grouping (by type and protection) is not suitable Can be named, but not to the class for no nesting of member groups into visibility groups

29 /** A class. Details */ class Test { public: //@{ /** Same documentation for both members (if DISTRIBUTE_GROUP_DOC is YES). Details */ void func1ingroup1(); void func2ingroup1(); //@} void Test::func1InGroup1() {} void Test::func2InGroup1() {} Group2 * Description of group 2. */ ///@{ /** Function 2 in group 2. Details. */ void Test::func2InGroup2() {} /** Function 1 in group 2. Details. */ void Test::func1InGroup2() {} ///@} /** Function without group. Details. */ void ungroupedfunction(); void func1ingroup2(); protected: void func2ingroup2(); };

31 Built in support or dot tool from graphviz (HAVE_DOT) Maximal size (DOT_GRAPH_MAX_NODES a MAX_DOT_GRAPH_DEPTH)

32 CLASS_DIAGRAM Inheritance of classes

33 HAVE_DOT = YES, MAX_DOT_GRAPH_DEPTH = 3 and TEMPLATE_RELATIONS = YES

34 Usage of classes in others

35 shows the functions that each documented function directly or indirectly calls

36 Shows the functions that the function is directly or indirectly called by

37 By default only partial preprocessing evaluates conditional compilation statements (#if, ) and macro definitions No macro expansion Can be disabled entirely ENABLE_PREPROCESSING = NO Full expansion MACRO_EXPANSION = YES

38 #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 default MACRO_EXPANSION = YES #define VERSION #define CONST_STRING static CONST_STRING version = "2.xx"; #define VERSION #define CONST_STRING static const char * version = "2.xx";

39 EXPAND_ONLY_PREDEF, PREDEFINED, EXPAND_AS_DEFINED extern "C" void declspec(dllexport) ErrorMsg( String amessage,...); ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES PREDEFINED = declspec(x)=

40 Substitute something without other expansion #define QList QListT class QListT { }; PREDEFINED = QListT:=QList #define QList class QList { };

41 Output sources after preprocessing doxygen -d Preprocessor recommended: QUIET = YES WARNINGS = NO

Very automated Manually @sa, @ref and html links //!

$\param a an integer argument. \param s a constant character pointer.$

42 Very and html links //! A normal member taking two arguments and returning an integer value. /*! \param a an integer argument. \param s a constant character pointer. \return The test results \sa Test(), ~Test(), testmetoo() and publicvar() */ int testme(int a,const char *s);

43 URL a addresses Automatically replaced by links manually <a href="linkurl">link text</a> Classes links Automatically all words corresponding to documented classes with at least one uppercase letter Prevented by % in front of the word Manually \ref <name> ["(text)"] Files links Automatically all words with dot on non-last position corresponding with documented file

44 Functions <functionname>"("<argument-list>")" <functionname>"()" "::"<functionname> (<classname>"::") n <functionname>"("<argument-list>")" (<classname>"::") n <functionname>"("<argument-list>")"<modifiers> (<classname>"::") n <functionname>"()" (<classname>"::") n <functionname> Eg. fun(const std::string&,bool) const Non-overloaded does not require parameters :: can be replaced by #, but sometimes different meaning Inside class ::foo global, #foo member

45 Other The same as functions, but recommended: "::"<name> (<classname>"::") n <name>

Can be structured using @mainpage, @section,

46 Can be @page

47 /*! \mainpage A simple manual Some general info. * \section intro_sec Introduction * * This is the introduction. * * \section install_sec Installation * * \subsection step1 Step 1: Opening the box * * \subsubsection step1a Step 1a: Get something to open the box /*! \page intro Introduction This page introduces the user to the topic. Now you can proceed to the \ref advanced "advanced section". */ /*! \page advanced Advanced Usage This page is for advanced users. Make sure you have first read \ref intro "the introduction". */ This manual is divided in the following sections: - \subpage intro - \subpage advanced "Advanced usage" */

49 The End

ODD Documentation Tool Tutorial

ODD Documentation Tool Tutorial For TRAMP Bernhard Zaun December 10 th 2001 Agenda / Overview of ODD / Why to document source code / Doxygen / What is Doxygen / Config file / Documentation blocks / Special