1 / 39

Abstract

Doxygen National University of Kaohsiung Department of Applied Mathematics Yu-Kai Hong , Chien-Hsiang Liu , Wei-Ren Chang February, 2008. Abstract. Source code documentation generator tool, Doxygen is a documentation system for C++, C, Java, Objective-C, Python,

myrrh
Download Presentation

Abstract

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. DoxygenNational University of Kaohsiung Department of Applied MathematicsYu-Kai Hong , Chien-Hsiang Liu , Wei-Ren ChangFebruary, 2008

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

  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 thecommand : doxygen filename

  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. 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. 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. The Comment Form in C++ • Single row comment : // … single row … • Multi-row comment : /* … row 1 … … row 2 … */

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

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

  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. The Comment Form in Doxygen • Multi-column comment : Type 1: /** *… text … */

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

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

  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. 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. The Brief and Detail Description • In Front of the program block ” { }” • … Comment … { … Program implementation … }

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

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

  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. 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. 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. 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. The Brief and Detail Description • Behind the program block ” { }” • { … Program implementation … } … Comment …

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

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

  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. 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. 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; /**< The multi-column comment. *>

  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. 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. 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. Some Commands (1) - File • @file: The comment of the file. • @author: Informations of the author. • @brief:Thecomment of function or class. • Example:     /** * @file myfile.h  * @brief A brief introduction of the file.    *        … complete information …          * @author Some informations of the author. */

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

  35. Some Commands (3) - Function • @return:Displayreturn 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. 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. 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. Complete C++ Example About this code, please refer to “C++ Language Tutorial, Juan Soulie, 2007.” 1. crectangle.h 2. set_values.h 3. crectangle.cpp 4. This is a complete html file.

  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

More Related