How do you exclude directories in Doxygen

Documentation tool Doxygen 1

Transcript

1 Doxygen documentation tool 1 David Damm July 12th This document is based on [DvH04], Dimitri van Heesch, manual for the Doxygen documentation tool (see

2 Table of Contents 1 Introduction 2 2 Installation Windows Linux Configuration Project Settings Options for Creating Documentation Defining Input Files Creating Documentation Configuration Example Documentation Main Page Classes and Files Functions and Variables Graphs and Diagrams Lists Links HTML Commands Special Characters Mathematical Formulas Summary

3 Chapter 1 Introduction Doxygen is an open source documentation tool for documenting within source code. All C-based programming languages ​​can be used with the program, i.e. C ++ in the case of the XCTL project. In contrast to JavaDoc, Doxygen supports not only HTML documentation but also the generation of LATEX code, RTF files or manual pages. Doxygen can be customized with the help of a configuration file in which you can set a variety of options. This configuration file can be modified with any text editor, or you can use the supplied Doxywizard program. 2

4 Chapter 2 Installation 2.1 Windows You can choose between two variants for installing Doxygen under Windows. Either you download the file doxygen-vvv-setup.exe from [, where vvv indicates the version number, and start the self-extracting archive with a double-click, or you select the zip file doxygen-vvvwindows.bin.zip and unzip it the files in the desired installation directory (e.g. C: \ Programs \ Doxygen). The EXE file also contains the Doxywizard for modifying the Doxygen settings. 2.2 Linux To install Doxygen on Linux, you need the Linux distribution from [which can be downloaded from the download area. The documentation tool is located in the archive doxygen-v.v.v.linux.bin.tar.gz, where v.v.v indicates the version number. If you also want to use the Doxywizard, you have to download another archive doxywizard-v.v.v.linux.bin.tar.gz, which only contains this one. In order to install Doxygen in a local user directory, you have to unzip the files in the home directory. To do this, first unzip the files and unpack the archives with shell> tar -xzf doxygen-v.v.v.linux.bin.tar.gz shell> tar -xzf doxywizard-v.v.v.linux.bin.tar.gz in the automatically created directory doxygen-v.v.v. (The files can of course also be copied to any other folder.) The doxygen-vvv / bin / folder now contains the programs doxygen, for creating the documentation, doxywizard, for conveniently setting the options for Doxygen and doxytag, for compiling various documentations. 3rd

5 CHAPTER 2. INSTALLATION 4 Figure 2.1: Doxywizard under Windows The first two tools are sufficient for the XCTL project, since documentation is to be generated for the entire project. Doxygen can now be called with the help of a shell shell> doxygen-v.v.v / bin / doxygen or within Doxywizard (with the gear button from the menu bar) after the configuration file has been created and customized.

6 Chapter 3 Configuration In order to be able to use Doxygen, a configuration file must first be created. This is done with the call doxygen -g setup.dox within a shell (under Linux) or in the command prompt (under Windows). You can also start the Doxywizard and save the configuration file under the name setup.dox (or any other name). The generated file setup.dox now contains all default values ​​for Doxygen. These values ​​can now be changed either with a text editor or with the supplied Doxywizard tool and the call. doxywizard setup.dox Then you should link all * .dox files with the Doxywizard, so that all configuration files for Doxygen can be opened with the Doxywizard with a double click (under Windows) or a single click (under Linux). Only the most important parameters are mentioned in the next sections (for a detailed description of the parameters see [3.1 Project settings When you start the Doxywizard, the Project tab is activated. In this you can make general settings for the project. There you will find a text field To define the project name (PROJEKT_NAME). In the case of the XCTL project, XCTL32 should be entered there. The path for the generated documentation is specified in the OUTPUT_DIRECTORY field so that all files created by Doxygen are saved in this directory Option CREATE_SUBDIRS, the files are divided into subdirectories. This option should remain deactivated for the XCTL project. Furthermore, the language for the documentation can be set with OUTPUT_LANGUAGE. Since German is predominantly used in the XCTL project, German should be set here. 5

7 CHAPTER 3. CONFIGURATION 6 The last project option that should be mentioned is JAVADOC_AUTOBLETTER. Activating this option means that each comment block always begins with a short description (see Chapter 4 on page 8). This option is activated for the XCTL project. 3.2 Options for creating the documentation If you activate the second tab Build in the Doxywizard, you can change numerous options that influence the creation of the documentation. Here we only consider the EXTRACT_ALL option. If this option is activated, all documents are parsed in the specified path and documentation is therefore created for all classes, functions or variables, even if these have not yet been documented with Doxygen. If you deactivate the option, only those files are parsed in which Doxygen instructions actually appear. Both variants are suitable for the XCTL project, depending on whether you want a complete overview of all classes (EXTRACT_ALL activated) or whether you want to find out which classes still need to be documented (EXTRACT_ALL deactivated). 3.3 Defining input files The settings for the input files are defined in the Input tab. Various sources can be specified under INPUT, which are then parsed later by Doxygen when creating the documentation. The simplest solution for the XCTL project is to specify the XCTL32 root directory and then additionally activate the RECURSIVE option so that all subdirectories in the XCTL32 directory are also searched. Then the file extensions (FILE_PATTERNS) of the files that are to be parsed must be specified, i.e. * .cpp and * .h in the case of the XCTL project. (Files with these endings are also parsed automatically if no pattern has been specified.) If you do not want to parse some files or directories, you can specify them explicitly in EXCLUDE. 3.4 Generating documentation The settings for generating the documentation can then be specified separately for each individual documentation type (HTML, LATEX, RTF, MAN, XML). Only the HTML and LATEX documentation are important for the XCTL project. Therefore GENERATE_HTML and GENERATE_LATEX should be activated. If you also want to generate RTF documentation or manual pages, GENERATE_RTF or GENERATE_MAN must be activated in the respective tab windows. The generated documentation is saved in the directory specified for HTML_OUTPUT or LATEX_OUTPUT (as a subdirectory in the OUTPUT_DIRECTORY directory, see project settings). The file extension for the generated HTML files can be specified with HTML_FILE_EXTENSION (e.g. * .html or * .htm).

8 CHAPTER 3. CONFIGURATION Configuration example The following excerpt comes from the example file Setup.dox, which was first generated with Doxygen and then modified with Doxywizard and adapted to the XCTL project. The particularly important settings have been highlighted. # Doxyfile # Project related configuration options PROJECT_NAME = XCTL32 PROJECT_NUMBER = OUTPUT_DIRECTORY = / u / ddamm / disk / doxygen / doxygenbeispiel / CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = German ... JAVADOC_AUTOBRIEF = YES ... # Build related configuration options EXTRACTALL = YES ... # Build related configuration options EXTRACTALL = YES ... # Build related configuration options . # configuration options related to the input files INPUT = / u / ddamm / disk / doxygen / doxygenbeispiel / FILE_PATTERNS = RECURSIVE = YES EXCLUDE = ... # configuration options related to the HTML output GENERATE_HTML = YES HTML_OUTPUT = html HTML_FILE_EXTENSION = .html HTML_HEADER = HTML_FOOTER = ... # configuration options related to the LaTeX output GENERATE_LATEX = YES LATEX_OUTPUT = latex LATEX_CMD_NAME = latex ... # Configuration :: additions related to the search engine SEARCHENGINE = NO

9 Chapter 4 Documentation The documentation style for the XCTL32 project should be based on JavaDoc, i.e. all comments are written in JavaDoc style. Comments to be processed by Doxygen must have the following structure: A C ++ comment block with two asterisks must be used at the beginning. /** A documentation. * Detailed documentation ... * ... * / In the first line of the comment a short description of the class (or method, variable, ...) is given. This brief description ends with the first point followed by a space or the end of a line (if the JAVADOC_AUTOBRIEF variable has been set). Then the detailed documentation is given. If you only want to add a short comment in one line, // * a short comment is sufficient to create it. The comment then goes to the end of the line and is interpreted as a new paragraph. If you insert several short comments one after the other, each line is displayed as a new paragraph in the documentation. All comments may contain HTML code, which Doxygen will also interpret accordingly. For example, HTML comments can also be inserted, which are then included in the source code in the generated documentation, but are not displayed in the documentation itself. // * Doxygen comment 8

10 CHAPTER 4. DOCUMENTATION Main page Figure 4.1: Documentation start page with Doxygen The main page is displayed first when you open the created documentation (html / index.html). It should give an overview of the entire project. In the case of the XCTL project, a general description of the project and a brief description of the subsystems are suitable. The following can be used to display the text in formatted form. The first command signals that the comment block contains a description for the main page of the project. Normally this description takes place in a file separate from the implementation (e.g. Project.h) in the root directory of the project. The heading of the start page is specified in the <title>. Chapters can now be specified, where <title> indicates the title of the chapter and <name> serves as an anchor for a reference. Reference can be made to the corresponding chapter elsewhere. XCTL * sec1 Introduction * Here follows a brief introduction ... * sec2 Subsystems sec2_1 Motor control sec2_2 Sequence control * / The associated documentation generated by Doxygen is shown in Figure 4.1.</p><p>11 CHAPTER 4. DOCUMENTATION Classes and files It is possible to use the <name> to describe the content of the file specified with <name>. It makes sense to place this command at the beginning of every documented file. The description of the file takes place in an extra comment block, whereby the first line up to the point is reserved for a short description if JAVADOC_AUTOBRIEF is activated. This is followed by a detailed description of the file content. Doxygen then generates a table in which all files are listed with their short descriptions. Each class should normally be in its own document (* .h, * .cpp). The general documentation of the class then belongs in the header file (* .h), while special implementation details should be described in the appropriate places in the source code (* .cpp). In the head of each header file, the authors of the source text, the date of the last modification and the document version should be written. Doxygen provides the following commands for this. <name> the authors of the document can be specified. Multiple authors can be specified by adding. The names then appear in the respective classes when the documentation is created. The <date> defines the date on which the file was last worked on. It is sufficient if the date is only used once in the header of the file and not for each individual method, otherwise you will lose track of things. The version of the document is recorded with the <version number>. After this instruction you should also briefly describe what has changed since the previous version in order to be able to understand the development of the source code. A header file could thus contain the following header: / ** Class realized example2. * David Damm * 0.2</p><p>12 CHAPTER 4. DOCUMENTATION 11 Figure 4.2: Class description with Doxygen * dead code removed. * 0.1 * Comments added (Doxygen). * / class Example2 {} Doxygen then generates the documentation shown in Figure 4.2 for the class Example2. It is noticeable that they were grouped together. The version numbers appear as a new paragraph.</p><p>13 CHAPTER 4. DOCUMENTATION Functions and Variables Figure 4.3: Class diagram in Doxygen In any case, all variables and functions should be documented, regardless of whether they are private, protected or public. Doxygen does not produce documentation for the protected attributes or functions, but the description is useful for the overall understanding of developers who later want to make changes to a subsystem (or a class) or add new features. In addition, a class diagram is automatically created for each class, provided that this class has been derived from another or has its own derivatives. The classes shown in the diagram are then linked to the respective documentation of the class so that easy and quick navigation is possible. Figure 4.3 shows such a class diagram using the example of the detectors. The currently displayed class documentation is hidden behind the white box. Yellow boxes indicate classes documented by Doxygen, while classes with a gray background are not documented (and therefore not linked). A solid dark blue arrow indicates that the inheritance is public. If the arrow is dashed and dark green, then it is a protected (protected) inheritance, and if it is dotted and dark green, then a private (private) inheritance takes place. Doxygen provides various commands to document a function. <identifier> <description> all parameters of a function can be described. With [in] you indicate that it is an input and with [out] that it is an output parameter. If the parameter is used for input and output, [in, out] must be specified. The <identifier> corresponds to the name of the parameter in the function header. The <description> specifies what the parameter is used for. The return value of a function is documented <description>. If the function does not have a return value, this command can be omitted. Further useful commands to describe functions or variables are in the following <testcase></p><p>14 CHAPTER 4. DOCUMENTATION 13 Figure 4.4: Documentation of member functions The first command can be used to create references to other functions or variables that are related to the function or variable just described (see example 3). activities that still need to be carried out can be recorded. This is used to document detected errors. From this, Doxygen generates a to-do list and an error list. an incorrect use of the function or variable can be pointed out. You can specify later test cases at. / ** Class realized example3. * David Damm * / class Example3 {public: / ** Adds two whole numbers. a The first number. b The second number. The sum of the two numbers a and b. Add (double, double) * / int add (int a, int b); double add (double a, double b); } An excerpt from the generated documentation is shown in Figure 4.4.</p><p>15 CHAPTER 4. DOCUMENTATION Graphs and diagrams Figure 4.5: Graphs and diagrams with Dot Doxygen can automatically create class diagrams for C ++ classes. However, if you want to access other graphs and diagrams, you also need the Dot tool. Dot is also an open source tool and can be downloaded from [. For Linux you can download the source code graphviz-v.v.tar.gz and install it in a local directory. To do this, unpack the file shell> tar -xzf graphviz-v.v.tar.gz shell> configure --prefix = <path> shell> make install and first configure the program by specifying the installation directory at <path>. Then Make must be called to install the program. Dot is then located in the directory <path> / bin /. For the Windows installation, download graphviz-v.v.exe and install the program in the desired directory (e.g. C: \ Programs \ Graphviz). If you have now installed the Dot tool, you can also use it in Doxygen. To do this, start the Doxywizard and activate the Dot tab.There you can now activate the HAVE_DOT option and enter the path to the Dot program under DOT_PATH. In addition to a class diagram (CLASS_GRAPH option), Doxygen can now also create a collaboration diagram (COLLABORATION_GRAPH option), a graphical illustration of the class hierarchy (GRAPHICAL_HIERARCHY option), a representation of the include dependencies (INCLUDE_GRAPH option) and a graph showing the call structure (CALL_GRAPH option) ) illustrates how to create. The rectangles in Figure 4.5 have the following meaning: A black-filled rectangle represents the structure or class for which the graph was generated. A rectangle with a black frame indicates a documented structure or class. A rectangle with a gray frame indicates an undocumented structure or class. A rectangle with a red frame indicates a documented structure or class for which not all inheritance / containment relationships are shown. A graph is truncated if it does not fit within the specified limits.</p><p>16 CHAPTER 4. DOCUMENTATION 15 These barriers can be changed by specifying the width for MAX_DOT_GRAPH_WIDTH and the height for MAX_DOT_GRAPH_HEIGHT. Both values ​​are preset to 1024 pixels and should be adjusted depending on the monitor resolution. The arrows in Figure 4.5 mean: A dark blue arrow represents a public inheritance relationship between two classes. A dark green arrow represents protected inheritance. A dark red arrow represents private inheritance. A dashed purple arrow means that one class is in another is included or is being used by someone else. At the arrow are the variables that can be used to access the structure or class at the arrowhead. A dashed yellow arrow indicates a link between a template instance and the template class from which it originates. The template parameters are shown next to the arrow. 4.5 Lists Simple lists can be created using the <list element>. The command has one argument and is either terminated with an empty line or with an. This command can only be used to create simple lists. However, if you still want to use nested lists, you can fall back on the HTML standard or create the lists in the following way. A simple list entry is indicated by a minus (-). If you want to create a numbered list, you have to add a hash (- #) after the minus. In order to create a subordinate list, the respective lines must be indented by a fixed number of spaces. All coats of paint that then begin in the same column belong to the same list. / ** * - List 1a * - # List 1a.1 * - # List 1a.2 * - List 1b * / The above example creates a list without numbering on the outside. The first list element again contains a numbered sub-list with two entries. In the following, more detailed example, two consecutive simple lists and one nested list are implemented using HTML code. Doxygen then generates the documentation text shown in Figure 4.6 for these lists. / ** Representation of lists. * * Simple lists: List 1a</p><p>17 CHAPTER 4. DOCUMENTATION 16 Figure 4.6: Creation of lists with Doxygen List 1b * List 2a List 2b * * Nested lists: * <ul> * <li> List 3a </li> * <ol> * <li> List 3a .1 </li> * <li> list 3a.2 </li> * </ol> * <li> list 3b </li> * </ul> * / class Example4 {} 4.6 Links Doxygen generates for everyone Files, classes, functions ... that appear in the documentation are automatically linked so that, for example, a link to this class is generated from the specification of a class name.</p><p>18 CHAPTER 4. DOCUMENTATION 17 HTML meaning <a href=...> </a> Creates a hyperlink. <p> </p> Indicates a paragraph. <b> </b> Text is shown in bold. <em> </em> or <i> </i> Text is shown in italics. <code> </code> Uses the typewriter font. </p><p> A line break. <hr> Creates a horizontal line. <center> </center> Aligns the text in the center. <ul> </ul> Generates an unordered list. <ol> </ol> Generates a numbered list. <li> </li> A list item. Table 4.1: HTML commands To link other elements to one another, you can use the <link-object>. The target <link-object> to be linked must be specified. The name of the link object <link-name> is used for the hyperlink in the documentation. A link ends It is also possible to use the HTML command to create a link (<a href=...> </a>). 4.7 HTML commands Doxygen also understands HTML commands and interprets them accordingly. Table 4.1 gives a brief overview of frequently used HTML tags. For a complete list of the commands, please refer to the manual [DvH04]. 4.8 Special characters Since some characters have a special meaning, they must be identified by an additional backslash if they are to be used in the documentation as a single character (e.g. #) (see Table 4.2). 4.9 Mathematical formulas Doxygen offers the possibility to integrate LATEX formulas into the documentation. This only works for HTML or LATEX output and not for RTF files or manuals. In order to include formulas in the form of images in the HTML documentation, the following three tools must be available: latex, for parsing the formulas.</p><p>19 CHAPTER 4. DOCUMENTATION 18 Doxygen characters \ $ \ \ \ & & \ ~ ~ \ <<\>> \ # # \%% Table 4.2: Special characters in Doxygen dvips to convert DVI files to PostScript gs to Convert PostScript files to bitmaps. There are two ways of including formulas in the documentation, namely within a text (between \ f $ ... \ f $) or as a separate formula (between \ f [... \ f]). All formulas must be valid commands in the math mode of LATEX. / ** * The distance between \ f $ (x_1, y_1) \ f $ and \ f $ (x_2, y_2) \ f $ is * \ f [\ sqrt {(x_2-x_1) ^ 2 + (y_2-y_1 ) ^ 2}. \ F] * / The result of the above example then has the following form: The distance between (x 1, y 1) and (x 2, y 2) is (x 2 x 1) 2 + (y 2 y 1) Summary The table is intended to provide a summary of all the commands discussed here and their meaning.</p><p>20 CHAPTER 4. DOCUMENTATION 19 <name> <name> <identifier> <link-object> Use Description of the main page of the documentation. A chapter begins. A subchapter begins. Description of a file. Author's name. Date of the last change. Version number of the document. Description of functional parameters. Return value of a function. Reference to another place. List of activities to be done. List of errors. Warnings about the use of a function or the like. Specification of test cases. Generate a list. Create a link. Table 4.3: Overview of some Doxygen commands</p></div></div> <ul> <li><a href="https://ramblingsofaneuroticwriter.com/?post=9101">21 Index Doxygen Author, 10 File, 10 Date, 10 Settings, 5 Function, 12 HTML Commands, 17 Hyperlink, 16 Comment, 8 Configuration, 5 Example, 7 CREATE_SUBDIRS, 5 Documentation, 6 Generate Documentation, 6 Input, 6 EXCLUDE, 6 EXTRACT_ALL, 6 FILE_PATTERNS, 6 GENERATE_HTML, 6 GENERATE_LATEX, 6 GENERATE_MAN, 6 GENERATE_RTF, 6 HTML_FILE_EXTENSION, 6 HTML_OUTPUT, 6 JAVADOC_AUTOBRIEF, 6, 8 LATEX_OUTPUT, 5, 8 LATEX_OUTPUT, 5, 5, 5, Project 6 OUTPUT , 16 list, 15 method, 12 variable, 12 version, 10 20</a></li><li><a href="https://ramblingsofaneuroticwriter.com/?post=379">Which are the evaluation subjects for optional</a></li><li><a href="https://ramblingsofaneuroticwriter.com/?post=1866">Is cryonics the answer to immortality?</a></li><li><a href="https://ramblingsofaneuroticwriter.com/?post=8644">How Much Money Do Homeschooling Teachers Make</a></li><li><a href="https://ramblingsofaneuroticwriter.com/?post=5800">Will Mumbai Indians enter the playoffs of this IPL</a></li><li><a href="https://ramblingsofaneuroticwriter.com/?post=9575">Is Holonis the new social media</a></li><li><a href="https://ramblingsofaneuroticwriter.com/?post=4103">Why is the goddess Durga Aparna called</a></li><li><a href="https://ramblingsofaneuroticwriter.com/?post=5116">Is math important in commerce</a></li><li><a href="https://ramblingsofaneuroticwriter.com/?post=2284">Take an annual family portrait</a></li><li><a href="https://ramblingsofaneuroticwriter.com/?post=3514">Who is a content writer</a></li> </ul> </div> <div class="col-md-4"> <div class="position-sticky" style="top: 2rem;"> <div class="p-4"> <ol class="list-unstyled"> <li><a href="https://ramblingsofaneuroticwriter.com/?post=2216">What is adaptive intelligence</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=905">Is animal feed safe for human consumption</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=5420">Is Lebanon still days away from economic collapse?</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=6316">Autism has biological evidence</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=1052">What are the requirements to be proud</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=3762">What is the criminal conspiracy in IPC</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=4761">How are noncommunicable diseases transmitted</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=9774">Has something happened to the bookmark function?</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=177">What is an F 22 Raptor</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=2273">What makes free apps valuable</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=1940">What are the 5 best underwear</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=3389">What is the use of Apple TV</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=4861">What is the importance of natural gas</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=8540">What is monitor democracy</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=3984">What causes swollen ankles after sunburn</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=2747">What is an ANR notification in Android</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=2975">What is cadence in road cycling</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=6534">Is Ketodiaet still useful in 2019</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=9506">What is the ring in the expanse</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=4106">Theoretically how small a transistor could get</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=2568">What do you know about Srinivasan Ramanujam</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=916">What is the best image compression software</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=1511">Why is logic so underestimated</a></li> <li><a href="https://ramblingsofaneuroticwriter.com/?post=9975">What is the most popular wine</a></li> </ol> </div> </div> </div> </div> </main> <footer class="blog-footer"> <p> <a href="#">Why does Google publish its research</a> </p> </footer> </body> </html><?