Doxygen-Tutorial. Wer sich schon einmal in ein umfangreiches Software-Projekt einarbeiten musste, sei es zur Fehlersuche oder zwecks Änderung/Erweiterung, kann ein Lied davon singen, was es heißt ohne gute Dokumentation den Überblick über das Projekt zu bekommen. Entwickler neigen ja gerne dazu schnell mal eine Änderung am Quellcode auszuprobieren, die bei Erfolg allenfalls irgendwo zwischen den Codezeilen mit einem knappen Kommentar dokumentiert wird und ansonsten für den Rest der Welt unbekannt bleibt. Doxygen ist ein bekanntes Open-Source-Dokumentationstool, welches an dieser Stelle ansetzt und Sourcecode automatisch dokumentieren kann. Dazu werden im Sourcecode spezielle Kommentare zu Methoden, Klassen, Variablen oder anderen Programmteilen geschrieben, aus denen Doxygen eine recht übersichtliche Dokumentation erstellt.
Im Doxygen-Fenster wählen wir "Expert... " und hangeln uns zum Reiter "Dot" durch (vorletzter). Achtung! Das war's dann auch schon an nötigen Einstellungen. Geschafft! So. Doxygen C++ inline template documentation. Doxygen. All commands in the documentation start with a backslash (\) or an at-sign (@). If you prefer you can replace all commands starting with a backslash below by their counterparts that start with an at-sign.
Some commands have one or more arguments. Each argument has a certain range: If <sharp> braces are used the argument is a single word. If in addition to the above argument specifiers [square] brackets are used the argument is optional. Here is an alphabetically sorted list of all commands with references to their documentation: The following subsections provide a list of all commands that are recognized by doxygen. --- Structural indicators --- Defines a group just like \defgroup, but in contrast to that command using the same <name> more than once will not result in a warning, but rather one group with a merged documentation and the first title found in any of the commands. /*! See Also page Grouping, sections \defgroup, \ingroup, and \weakgroup. Note section \callergraph. section \callgraph. Simple Doxygen templates « JustChecking's Weblog On All.
This is a follow-up to previous tutorial, Simple guide to basic Doxygen usage. Here are few simple templates that you might use for documenting your source; easiest use is with e.g. Visual Assist X, or any other tool that allows you to add predefined templates to your source code. I use these template with VAX and shortcut set to “/*!” , with short descriptive names, thus I don’t need to remember many shortcuts and have all at reach of 3 key-clicks. And we finish off with a small list of simple tips. General Doxygen comment block This is a simple comment block, with both brief and detailed sections: In VAX, you can use following template: //! File header comment block This is a simple comment block to use as a file header: /*! In VAX: /*! Class comment block /*!
/*! Function comment block /*! /*! “Paired commands” What you have to pay attention to are the paired commands. So, here’s a list of commands that you should use carefully, more precisely you should always “close them”! Section commands. How to document your code using doxygen - FLC Wiki. Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP and C#. For details, see Here only some basic suggestions of how to document your code will be given. In order to generate doxygen based documentation, you need to follow four steps: have the doxygen executable installed on your computer (this is already done on our DESY machines) document your code create a configuration file run doxygen to create the documentation (HTML or LaTeX based).
All these steps will be explained in the following. How to document your code It is highly recommended that you document your code. Note that the actual documentation consists in comments you write in the header file What you should in any case document is: Bellow is an example of a dummy class: Have a look at the doxygen output. Basically, C-style comments are used, e.g. /** Commenting something /** My function doing something... \f$x_0 + y^3\f$ Doxygen - gkw - How write code comments compatible with the doxygen parser - Gyro-kinetic simulation code for the study of turbulence in magnetised plasmas. A tool for fusion energy research. GKW has a reference dictionary that is automatically generated and updated using Doxygen. Comments in GKW should be written in such a way as to be parsable by Doxygen. For variables can have either leading comments, or trailing comments on same line Example 1 !
Example 2 logical :: coriolis ! Functions must have their description preceding the declaration To keep it simple, only use the ! Example 3 ! Alternatively, comments preceding a function can be written as a formatted block which will retain its layout through the parser (Example 4). Latex math mode can be used if enclosed within two \texttt{\\f\$} groups. Example 4 ! Which should be part of the StyleGuidelines All modules, functions and (module level) variable declarations have a useful doxy comment Input variables are labeled as such with default values listed if applicable at declaration comment Allocatable arrays should have their size noted at declaration comment. Doxygen. This chapter covers two topics: How to put comments in your code such that doxygen incorporates them in the documentation it generates. This is further detailed in the next section.Ways to structure the contents of a comment block such that the output looks good, as explained in section Anatomy of a comment block.
A special comment block is a C or C++ style comment block with some additional markings, so doxygen knows it is a piece of structured text that needs to end up in the generated documentation. The next section presents the various styles supported by doxygen. For Python, VHDL, Fortran, and Tcl code there are different commenting conventions, which can be found in sections Comment blocks in Python, Comment blocks in VHDL, Comment blocks in Fortran, and Comment blocks in Tcl respectively.
Comment blocks for C-like languages (C/C++/C#/Objective-C/PHP/Java) There are several ways to mark a comment block as a detailed description: As you can see doxygen is quite flexible. //! Or public: ! Documenting the code (using Doxygen) During an application development writing documentation is a tedious work. In effect when you are writing the code all is clear, at this moment the code seems to document itself.
But time pass, and one day you open an ancient project, look the code, ant the self documenting code now is cripted. For documenting the code I use doxygen. Using this tool I am forced to write good documentation, and "at the same price" I can get documentation in HTML format. Writing comments For documenting the code just need to use the correct syntax in the comment block, like: /** * This is the documentation */ If you use Eclipse with CDT the editor recognize you are writing documentation after the first "/**" line and automatically add "*" when you add a new line...nice.
Usually the documentation of a class member can include: Word preceded by "@" are command interpreted by doxygen (in effect doxygen can understand different syntax, but I prefer this). For a more detailed description look at the Doxygen manual. C++-Programmierung: Dokumentation mit Doxygen. Das von Dimitri van Heesch entwickelte Werkzeug Doxygen erstellt aus den Quelltextdateien eine übersichtliche Dokumentation der Dateien, Klassen und Funktionen eines Softwareprojekts. Doxygen ist unter der GPL lizenziert und für die Betriebssysteme Linux, Microsoft Windows und Mac OS verfügbar. Neben C/C++ unterstützt Doxygen weitere Programmiersprachen, z.B.
Java und Python. Die Ausgabe kann in den Formaten HTML, LaTeX, Unix-Manpage u.a. erfolgen. Auf der Doxygen-Homepage finden Sie eine ausführliche Anleitung, so dass wir uns hier auf die wesentlichen Aspekte beschränken können. Installation[Bearbeiten] Zusätzliche Tools[Bearbeiten] Um alle Funktionen von Doxygen verwenden zu können sind unter allen Plattformen zusätzliche Tools notwendig. Windows[Bearbeiten] Doxygen ist in vielen Shells implementierbar, zB Cygwin.
MikTeX[Bearbeiten] GraphViz[Bearbeiten] Linux[Bearbeiten] Aufruf[Bearbeiten] doxygen -g doxygen.config erzeugt eine Konfigurationsdatei doxygen.config. Doxygen doxygen.config doxygen.