1. 1 Doxygen National University of Kaohsiung Department of Applied Mathematics Yu-Kai Hong, Chien-Hsiang Liu, Wei-Ren Chang February, 2008

2. 2 Abstract Source code documentation generator tool, Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extend D.

3. 3 Installation For Linux, download the software from the web, then you can use it. For Windows, also download the software, and follow the indication, then you can use it. Link : http://www.stack.nl/~dimitri/ doxygen/ http://www.stack.nl/~dimitri/ doxygen/

4. 4 Procedure First, you have to generate a doxygen configuration-file. By using the command: doxygen –g filename Next, edit your configuration-file and annotations. Finally, create your doxygen-file. Using the command : doxygen filename

5. 5 Some Doxygen Configurations (1) PROJECT_NAME: The name of your project. PROJECT_VERSION : The version of your project. OUTPUT_DIRECTORY: Specify the path to output your file. INLINE_SOURCES : Decide if you want to embed your codes in the documents.

6. 6 Some Doxygen Configurations (2) INPUT: Specify the path to include your file.If you specify a directory, then all files under the directory will been handled.Moreover, you can include multiply files. For example, input=file1.c,file2.c,file3.c.

7. 7 Some Doxygen Configurations (3) GENERATE_HTML : Decide if you want to generate html-file. GENERATE_LATEX : Decide if you want to generate LATEX-file.

8. 8 The Comment Form in C++ Single row comment : // … single row … Multi-row comment : /* … row 1 … … row 2 … */

9. 9 The Comment Form in Doxygen Single column comment : Type 1 : /// /// … text … ///

10. 10 The Comment Form in Doxygen Single column comment : Type 2 : //! //! … text … //!

11. 11 The Comment Form in Doxygen Example 1: /// This is the single column comment void function1(void); Example 2: //! This is the single column comment void function1(void); Examples\1\index.html

12. 12 The Comment Form in Doxygen Multi-column comment : Type 1: /** * … text … */

13. 13 The Comment Form in Doxygen Multi-column comment : Type 2 : /*! * … text … */

14. 14 The Comment Form in Doxygen Multi-column comment : Type 2 : /*! … text … */

15. 15 The Comment Form in Doxygen Example 1: /** This is the multi-column comment\n * The second column. */ double* function2(int*,double); Examples\2\index.html

16. 16 The Comment Form in Doxygen Example 2: /*! This is the multi-column comment\n * The second column. */ double* function2(int*,double); Examples\2\index.html

17. 17 The Brief and Detail Description In Front of the program block ” { }” … Comment … { … Program implementation … }

18. 18 The Brief and Detail Description Type 1 : /// brief description. /** detail description. */

19. 19 The Brief and Detail Description Type 2 : //! brief description. //! detail description //! … text …

20. 20 The Brief and Detail Description Example 1: /// This is the brief description. /** This is the detail description. * */ double function3(double,double); Examples\3\index.html

21. 21 The Brief and Detail Description Example 2: //! This is the brief description. //! This is the detail description. //! double function3(double,double); Examples\3\index.html

22. 22 The Brief and Detail description Note1 : Only one brief and detail description are valid. Note2 : There is one brief description before a declaration and before a definition of a code item, only the one before the declaration will be used. Note3 : The situation for the detail description is adverse of the brief description.

23. 23 The Brief and Detail Description Example : /// (1)The brief description which is used. /// (1)The detail description which is not used double function4(double,double); /// (2)The brief description which is not used. /// (2)The detail description which is used. double function4(double var1,double var2) { return (var1+var2); }; Examples\4\index.html

24. 24 The Brief and Detail Description Behind the program block ” { }” { … Program implementation … } … Comment …

25. 25 The Brief and Detail Description Type 1 : ///< brief description. /**< detail description. */

26. 26 The Brief and Detail Description Type 2 : //!< brief description //!< detail description //!<... Text...

27. 27 The Brief and Detail Description Example 1: double function5(double,double); ///< This is the brief description. //!< This is the detail description. //!< Examples\5\index.html

28. 28 The Brief and Detail Description Example 2: double function5(double,double); //!< This is the brief description. /*!< This is the detail description. * */ Examples\5\index.html

29. 29 The Brief and Detail Description Note1 : Put additional mark < in the comment block Note2 : There blocks only used to document functions and the parameters. Example : int var; //!< The single column comment. int var; /**

30. 30 The Brief and Detail Description Note3 : They cannot used to document, files, classes, unions, structs, namespaces and enums …etc. Note4 : There is one brief description before a declaration and before a definition of a code item, only the one before the declaration will be used, the same situation is for the detail description.

31. 31 The Brief and Detail Description Example : double function6(double,double); ///< (1)The brief description which is used. //!< (1)The detail description which is used double function6(double var1,double var2) { return (var1+var2); }; ///< (2)The brief description which is not used. //!< (2)The detail description which is not used. Examples\6\index.html

32. 32 Special Syntax in Doxygen Put additional mark \ in the comment block \ + command Put the document at other places on the program, rather than in front of or behind the program block.

33. 33 Some Commands (1) - File @file: The comment of the file. @author: Informations of the author. @brief: The comment of function or class. Example: /** * @file myfile.h * @brief A brief introduction of the file. * … complete information … * @author Some informations of the author. */

34. 34 Some Commands (2) - Function @param: The comment of the parameter syntax : @param arg_name comment of arg_name e.g. @param mtxA Return the Laplacian matrix called A

35. 35 Some Commands (3) - Function @return: Display return value. @retval: The comment of return value. Example: /** * @brief A brief introduction of your function * … complete information … * @param a Some introduction of parametric a. * @return Some introduction of return value. */

36. 36 Some Commands (4) \b \c \e : set the next word to bold, italic, or courier, respectively. e.g. /// You can make things \b bold, \e italic, or set them in \c courier. results in: You can make things bold, italic, or set them in courier.

37. 37 Some Commands (4) \n: force a newline. \internal : starts a paragraph with "internal information" (such as implementaiton details). The paragraph will be included only if the INTERNAL_DOCS option is enabled.

38. 38 Complete C++ Example About this code, please refer to “C++ Language Tutorial, Juan Soulie, 2007.” 1. crectangle.hcrectangle.h 2. set_values.hset_values.h 3. crectangle.cppcrectangle.cpp 4. This is a complete html file.This is a complete html file.

39. 39 Reference : -Home http://www.stack.nl/~dimitri/doxygen/ - Manual http://www.stack.nl/~dimitri/doxygen/manual.html - Articles http://www.stack.nl/~dimitri/doxygen/articles.html - Chinese: http://www.stack.nl/%7Edimitri/doxygen/doxygen_in tro_cn.html http://www.stack.nl/~dimitri/doxygen/ http://www.stack.nl/~dimitri/doxygen/manual.html http://www.stack.nl/~dimitri/doxygen/articles.htmlhttp://www.stack.nl/%7Edimitri/doxygen/doxygen_in tro_cn.html