Doxygen: Source Code Documentation Generator John Tully

Motivation Reminder – 2 main uses: Reminder – 2 main uses: Generating on-line documentation browsers / off-line reference manuals directly from source Generating on-line documentation browsers / off-line reference manuals directly from source Many languages: C, C++, Java, Python, PHP Many languages: C, C++, Java, Python, PHP Many output formats Many output formats All configurable with many format-specific options All configurable with many format-specific options Extracting source code structure from undocumented source files (various visualizations): Extracting source code structure from undocumented source files (various visualizations): Many useful ways to visualize source code Many useful ways to visualize source code Again, configurable with visualization-specific options Again, configurable with visualization-specific options

History Creator : Dimitri van Heesch; first release in 1997 Creator : Dimitri van Heesch; first release in 1997 Often used Qt widget toolkit, an application development framework (popular for creating GUIs) Often used Qt widget toolkit, an application development framework (popular for creating GUIs) Wrote docs by hand to look exactly like Qt’s (became a nightmare to maintain by hand) Wrote docs by hand to look exactly like Qt’s (became a nightmare to maintain by hand) Tried Doc++ to do this automatically; not configurable enough for liking Tried Doc++ to do this automatically; not configurable enough for liking Started writing own generator code… Doxygen born Started writing own generator code… Doxygen born

Environment & Setup Developed under Linux & OS X, but made to be highly portable – works on most Unix flavors; executables for Windows available Developed under Linux & OS X, but made to be highly portable – works on most Unix flavors; executables for Windows available Releases for all platforms can be found at doxygen.org (redirects to homepage of Dimitri van Heesch) Releases for all platforms can be found at doxygen.org (redirects to homepage of Dimitri van Heesch) Easy installation; short “getting started” manual page is enough learn all basic functionality Easy installation; short “getting started” manual page is enough learn all basic functionality

Features “Important” features depend on what user wants to do – most impressive part is ease of configuration of each “Important” features depend on what user wants to do – most impressive part is ease of configuration of each Documentation generation: for users who what to keep docs consistent with code Documentation generation: for users who what to keep docs consistent with code HTML, hyperlinked PDF HTML, hyperlinked PDF LaTex, RTF (for Word), PostScript, PDF, Unix man pages LaTex, RTF (for Word), PostScript, PDF, Unix man pages Source Code Visualization: for users to extract code structure from undocumented sources Source Code Visualization: for users to extract code structure from undocumented sources Dependency graphs Dependency graphs Inheritance diagrams Inheritance diagrams Collaboration diagrams Collaboration diagrams

Limitations / Extensions ‘Doxygen Wish List’ available for anyone interested in implementing more features ‘Doxygen Wish List’ available for anyone interested in implementing more features Huge list of languages Huge list of languages Database programming (SQL) Database programming (SQL) Scripting (Perl, Bash shell scripts; does support for PHP and Python) Scripting (Perl, Bash shell scripts; does support for PHP and Python) Hardware Description (VHDL, Verilog) Hardware Description (VHDL, Verilog) Many others -- Visual Basic, Fortran, MATLAB, etc….. Many others -- Visual Basic, Fortran, MATLAB, etc….. Many more output formats Many more output formats XHTML, SGML, DocBook, Framemaker XHTML, SGML, DocBook, Framemaker Better use of template files – Java Doclets apparently good for this Better use of template files – Java Doclets apparently good for this

Related Tools Several tools (ROBODoc, TwinText) support pretty much any programming language, but don’t seem as easy to use as Doxygen Several tools (ROBODoc, TwinText) support pretty much any programming language, but don’t seem as easy to use as Doxygen More importantly, Doxygen seems to be one of the only tools for useful diagram generation (most others are language-specific) More importantly, Doxygen seems to be one of the only tools for useful diagram generation (most others are language-specific) Others (Javadoc, CppDoc) only support specific languages Others (Javadoc, CppDoc) only support specific languages Generally up to user’s needs Generally up to user’s needs Importance of supporting different languages Importance of supporting different languages Configurability Configurability Ease of use Ease of use

Documentation Basics Doxygen Manual: documenting the code Doxygen Manual: documenting the code Several styles Several styles Javadoc /** my comment */ Javadoc /** my comment */ Qt /*! my comment */ Qt /*! my comment */ C/C++ single-line /// my comment C/C++ single-line /// my comment Others //! my comment Others //! my comment 1 brief (one line only), 1 detailed description allowed for each block 1 brief (one line only), 1 detailed description allowed for each block Discussion – why is this useful? Discussion – why is this useful? Getting Started (Demo 1) Getting Started (Demo 1) Brief vs. detailed descriptions Brief vs. detailed descriptions Commands inside of detailed descriptions Commands inside of detailed descriptions Descriptions after members of class vs. before Descriptions after members of class vs. before Questions on basics? Questions on basics?

Structural Commands In step 1, doc blocks in front of declarations or definitions of classes, or directly before/after its members. In step 1, doc blocks in front of declarations or definitions of classes, or directly before/after its members. With structural commands, we can put documentation blocks anywhere With structural commands, we can put documentation blocks anywhere This “duplicates” information in a way (not desirable – why not?) This “duplicates” information in a way (not desirable – why not?) Important : to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined Important : to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined Header file with structural commands (Demo 2) Header file with structural commands (Demo 2) These comment blocks could be moved anywhere These comment blocks could be moved anywhere But, now we have to change 2 things – do you really want this??? But, now we have to change 2 things – do you really want this???

More Useful Features Grouping (Demo 3) Grouping (Demo 3) Modules can be used to group files, classes, functions, variables, typedefs/defines, etc. (and other modules) Modules can be used to group files, classes, functions, variables, typedefs/defines, etc. (and other modules) Defined groups go in a separate modules section in documentation Defined groups go in a separate modules section in documentation Discussion: why is this useful? Discussion: why is this useful? Fairly simple to group with small set of commands Fairly simple to group with small set of commands /defgroup /defgroup /ingroup /ingroup /addtogroup /addtogroup Automatic Link Generation (Demo 4) Automatic Link Generation (Demo 4)

Diagram Generation With “dot” tool from GraphViz package: With “dot” tool from GraphViz package: Class diagrams Class diagrams Collaboration diagrams Collaboration diagrams Dependency graphs Dependency graphs Class hierarchy Class hierarchy Call graphs Call graphs Built-in diagram tool still pretty useful for inheritance diagrams (HTML only) (Demo 5) Built-in diagram tool still pretty useful for inheritance diagrams (HTML only) (Demo 5) Tools good for quicker understanding/navigation through undocumented source code (EXTRACT_ALL option in config file / GUI) Tools good for quicker understanding/navigation through undocumented source code (EXTRACT_ALL option in config file / GUI)

Questions / Discussion