Doxygen: Source Doxygen: Source Code Code

Documentation Documentation GeneratorGenerator

John TullyJohn Tully

MotivationMotivation Reminder – 2 main uses:Reminder – 2 main uses:

Generating on-line documentationGenerating on-line documentation browsers / off-line reference manuals directly browsers / off-line reference manuals directly from sourcefrom source

Many languages: C, C++, Java, Python, PHPMany languages: C, C++, Java, Python, PHP Many output formatsMany output formats All configurable with many format-specific optionsAll configurable with many format-specific options

Extracting source code structureExtracting source code structure from from undocumented source files (various undocumented source files (various visualizations):visualizations):

Many useful ways to visualize source code Many useful ways to visualize source code Again, configurable with visualization-specific Again, configurable with visualization-specific

optionsoptions

HistoryHistory Creator : Dimitri van Heesch; first release in Creator : Dimitri van Heesch; first release in

19971997

Often used Qt widget toolkit, an application Often used Qt widget toolkit, an application development framework (popular for creating development framework (popular for creating GUIs)GUIs)

Wrote docs by hand to look exactly like Qt’s Wrote docs by hand to look exactly like Qt’s (became a nightmare to maintain by hand)(became a nightmare to maintain by hand)

Tried Doc++ to do this automatically; not Tried Doc++ to do this automatically; not configurable enough for likingconfigurable enough for liking

Started writing own generator code… Doxygen Started writing own generator code… Doxygen bornborn

Environment & SetupEnvironment & Setup Developed under Linux & OS X, but Developed under Linux & OS X, but

made to be highly portable – works on made to be highly portable – works on most Unix flavors; executables for most Unix flavors; executables for Windows availableWindows available

Releases for all platforms can be found Releases for all platforms can be found at doxygen.org (redirects to homepage of at doxygen.org (redirects to homepage of Dimitri van Heesch)Dimitri van Heesch)

Easy installation; short “getting started” Easy installation; short “getting started” manual page is enough learn all basic manual page is enough learn all basic functionalityfunctionality

FeaturesFeatures ““Important” features depend on what user Important” features depend on what user

wants to do – most impressive part is ease of wants to do – most impressive part is ease of configuration of eachconfiguration of each

Documentation generation: for users who Documentation generation: for users who what to keep docs consistent with codewhat to keep docs consistent with code HTML, hyperlinked PDFHTML, hyperlinked PDF LaTex, RTF (for Word), PostScript, PDF, Unix man LaTex, RTF (for Word), PostScript, PDF, Unix man

pagespages

Source Code Visualization: for users to extract Source Code Visualization: for users to extract code structure from undocumented sources code structure from undocumented sources Dependency graphsDependency graphs Inheritance diagramsInheritance diagrams Collaboration diagramsCollaboration diagrams

Limitations / ExtensionsLimitations / Extensions ‘‘Doxygen Wish List’ available for anyone Doxygen Wish List’ available for anyone

interested in implementing more featuresinterested in implementing more features

Huge list of languagesHuge list of languages Database programming (SQL)Database programming (SQL) Scripting (Perl, Bash shell scripts; does support for PHP Scripting (Perl, Bash shell scripts; does support for PHP

and Python)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 formatsMany more output formats XHTML, SGML, DocBook, Framemaker XHTML, SGML, DocBook, Framemaker

Better use of template files – Java Doclets Better use of template files – Java Doclets apparently good for thisapparently good for this

Related ToolsRelated Tools Several tools (ROBODoc, TwinText) support pretty Several tools (ROBODoc, TwinText) support pretty

much much anyany programming language, but don’t seem programming language, but don’t seem as easy to use as Doxygenas easy to use as Doxygen

More importantly, Doxygen seems to be one of the More importantly, Doxygen seems to be one of the only tools for useful diagram generation (most only tools for useful diagram generation (most others are language-specific)others are language-specific)

Others (Javadoc, CppDoc) only support specific Others (Javadoc, CppDoc) only support specific languageslanguages

Generally up to user’s needsGenerally up to user’s needs Importance of supporting different languagesImportance of supporting different languages ConfigurabilityConfigurability Ease of useEase of use

Documentation BasicsDocumentation Basics Doxygen Manual: Doxygen Manual: documenting the codedocumenting the code

Several stylesSeveral 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 commentOthers //! my comment

1 brief (one line only), 1 detailed description allowed for 1 brief (one line only), 1 detailed description allowed for each blockeach block

Discussion – why is this useful?Discussion – why is this useful?

Getting Started (Demo 1)Getting Started (Demo 1) Brief vs. detailed descriptionsBrief vs. detailed descriptions Commands inside of detailed descriptionsCommands inside of detailed descriptions Descriptions Descriptions afterafter members of class vs. before members of class vs. before Questions on basics?Questions on basics?

Structural CommandsStructural Commands In step 1, doc blocks In step 1, doc blocks in frontin front of declarations or of declarations or

definitions ofdefinitions of classes classes, or , or directly before/afterdirectly before/after its its membersmembers..

With With structural commandsstructural commands, we can put documentation , we can put documentation blocks anywhereblocks anywhere This “duplicates” information in a way (not desirable – why This “duplicates” information in a way (not desirable – why

not?)not?)

Important : to document global objects (functions, Important : to document global objects (functions, typedefs, enum, macros, etc), you typedefs, enum, macros, etc), you mustmust document the document the file in which they are defined 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 anywhereThese comment blocks could be moved anywhere But, now we have to change 2 things – do you But, now we have to change 2 things – do you reallyreally want want

this???this???

More Useful FeaturesMore Useful Features Grouping (Demo 3)Grouping (Demo 3)

Modules can be used to group files, classes, Modules can be used to group files, classes, functions, variables, typedefs/defines, etc. (and functions, variables, typedefs/defines, etc. (and other modules)other modules)

Defined groups go in a separate modules section Defined groups go in a separate modules section in documentationin documentation

Discussion: why is this useful?Discussion: why is this useful?

Fairly simple to group with small set of Fairly simple to group with small set of commandscommands /defgroup/defgroup /ingroup/ingroup /addtogroup/addtogroup

Automatic Link Generation (Demo 4)Automatic Link Generation (Demo 4)

Diagram GenerationDiagram Generation With “dot” tool from GraphViz package:With “dot” tool from GraphViz package:

Class diagramsClass diagrams Collaboration diagramsCollaboration diagrams Dependency graphsDependency graphs Class hierarchyClass hierarchy Call graphsCall graphs

Built-in diagram tool still pretty useful for Built-in diagram tool still pretty useful for inheritance diagrams (HTML only) (Demo 5)inheritance diagrams (HTML only) (Demo 5)

Tools good for quicker Tools good for quicker understanding/navigation through understanding/navigation through undocumented source code (EXTRACT_ALL undocumented source code (EXTRACT_ALL option in config file / GUI)option in config file / GUI)

Questions / DiscussionQuestions / Discussion