1. Doxygen: Source Code Documentation Generator John Tully

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

3. History • Creator : Dimitri van Heesch; first release in 1997 • 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) • Tried Doc++ to do this automatically; not configurable enough for liking • Started writing own generator code… Doxygen born

4. Environment & Setup • 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) • Easy installation; short “getting started” manual page is enough learn all basic functionality

5. Features • “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 • HTML, hyperlinked PDF • LaTex, RTF (for Word), PostScript, PDF, Unix man pages • Source Code Visualization: for users to extract code structure from undocumented sources • Dependency graphs • Inheritance diagrams • Collaboration diagrams

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

7. Related Tools • 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) • Others (Javadoc, CppDoc) only support specific languages • Generally up to user’s needs • Importance of supporting different languages • Configurability • Ease of use

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

9. Structural Commands • 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 • 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 • Header file with structural commands (Demo 2) • These comment blocks could be moved anywhere • But, now we have to change 2 things – do you really want this???

10. More Useful Features • Grouping (Demo 3) • 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 • Discussion: why is this useful? • Fairly simple to group with small set of commands • /defgroup • /ingroup • /addtogroup • Automatic Link Generation (Demo 4)

11. Diagram Generation • With “dot” tool from GraphViz package: • Class diagrams • Collaboration diagrams • Dependency graphs • Class hierarchy • Call graphs • 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)

12. Questions / Discussion