1 / 12

Doxygen: Source Code Documentation Generator

Doxygen: Source Code Documentation Generator. John Tully. 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

minerva-keith
Télécharger la présentation

Doxygen: Source Code Documentation Generator

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

More Related