From 73c460247af61dd37fb092a9dd4e647edcd8cbfa Mon Sep 17 00:00:00 2001 From: Dimitri van Heesch Date: Sat, 6 Jun 2020 14:57:58 +0200 Subject: Minor documentation updates --- doc/CMakeLists.txt | 2 +- doc/arch.doc | 110 ++++----- doc/archoverview.gif | Bin 7822 -> 0 bytes doc/archoverview.svg | 625 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc/install.doc | 24 +- 5 files changed, 697 insertions(+), 64 deletions(-) delete mode 100644 doc/archoverview.gif create mode 100644 doc/archoverview.svg diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 032c16a..537089b 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -32,7 +32,7 @@ set(DOC_INSTALL_DIR "share/doc/packages/doxygen" CACHE STRING "Relative path whe set(DOC_FILES arch.doc archoverview.eps - archoverview.gif + archoverview.svg autolink.doc changelog.doc commands.doc diff --git a/doc/arch.doc b/doc/arch.doc index bd51a1b..104b3e3 100644 --- a/doc/arch.doc +++ b/doc/arch.doc @@ -1,12 +1,12 @@ /****************************************************************************** * - * + * * * Copyright (C) 1997-2015 by Dimitri van Heesch. * * Permission to use, copy, modify, and distribute this software and its - * documentation under the terms of the GNU General Public License is hereby - * granted. No representations are made about the suitability of this software + * documentation under the terms of the GNU General Public License is hereby + * granted. No representations are made about the suitability of this software * for any purpose. It is provided "as is" without express or implied warranty. * See the GNU General Public License for more details. * @@ -22,7 +22,7 @@ The following picture shows how source files are processed by doxygen. -\image html archoverview.gif "Data flow overview" +\image html archoverview.svg "Data flow overview" \image latex archoverview.eps "Data flow overview" width=14cm The following sections explain the steps above in more detail. @@ -30,20 +30,20 @@ The following sections explain the steps above in more detail.

Config parser

The configuration file that controls the settings of a project is parsed -and the settings are stored in the singleton class \c Config -in src/config.h. The parser itself is written using \c flex -and can be found in src/config.l. This parser is also used +and the settings are stored in the singleton class \c Config +in src/config.h. The parser itself is written using \c flex +and can be found in src/config.l. This parser is also used directly by \c doxywizard, so it is put in a separate library. -Each configuration option has one of 5 possible types: \c String, +Each configuration option has one of 5 possible types: \c String, \c List, \c Enum, \c Int, or \c Bool. The values of these options are available through the global functions \c Config_getXXX(), where \c XXX is the type of the option. The argument of these function is a string naming -the option as it appears in the configuration file. For instance: +the option as it appears in the configuration file. For instance: \c Config_getBool("GENERATE_TESTLIST") returns a reference to a boolean -value that is \c TRUE if the test list was enabled in the configuration file. +value that is \c TRUE if the test list was enabled in the configuration file. -The function \c readConfiguration() in \c src/doxygen.cpp +The function \c readConfiguration() in \c src/doxygen.cpp reads the command line options and then calls the configuration parser.

C Preprocessor

@@ -54,29 +54,29 @@ C Preprocessor (after being piped through a user defined filter if available). The way the preprocessor works differs somewhat from a standard C Preprocessor. By default it does not do macro expansion, although it can be configured to expand all macros. Typical usage is to only expand a user specified set -of macros. This is to allow macro names to appear in the type of +of macros. This is to allow macro names to appear in the type of function parameters for instance. -Another difference is that the preprocessor parses, but not actually includes +Another difference is that the preprocessor parses, but not actually includes code when it encounters a \c \#include (with the exception of \c \#include -found inside { ... } blocks). The reasons behind this deviation from -the standard is to prevent feeding multiple definitions of the -same functions/classes to doxygen's parser. If all source files would -include a common header file for instance, the class and type -definitions (and their documentation) would be present in each -translation unit. +found inside { ... } blocks). The reasons behind this deviation from +the standard is to prevent feeding multiple definitions of the +same functions/classes to doxygen's parser. If all source files would +include a common header file for instance, the class and type +definitions (and their documentation) would be present in each +translation unit. The preprocessor is written using \c flex and can be found in -\c src/pre.l. For condition blocks (\c \#if) evaluation of constant expressions -is needed. For this a \c yacc based parser is used, which can be found +\c src/pre.l. For condition blocks (\c \#if) evaluation of constant expressions +is needed. For this a \c yacc based parser is used, which can be found in \c src/constexp.y and \c src/constexp.l. -The preprocessor is invoked for each file using the \c preprocessFile() -function declared in \c src/pre.h, and will append the preprocessed result +The preprocessor is invoked for each file using the \c preprocessFile() +function declared in \c src/pre.h, and will append the preprocessed result to a character buffer. The format of the character buffer is \verbatim -0x06 file name 1 +0x06 file name 1 0x06 preprocessed contents of file 1 ... 0x06 file name n @@ -85,17 +85,17 @@ to a character buffer. The format of the character buffer is

Language parser

-The preprocessed input buffer is fed to the language parser, which is -implemented as a big state machine using \c flex. It can be found -in the file \c src/scanner.l. There is one parser for all -languages (C/C++/Java/IDL). The state variables \c insideIDL -and \c insideJava are uses at some places for language specific choices. +The preprocessed input buffer is fed to the language parser, which is +implemented as a big state machine using \c flex. It can be found +in the file \c src/scanner.l. There is one parser for all +languages (C/C++/Java/IDL). The state variables \c insideIDL +and \c insideJava are uses at some places for language specific choices. -The task of the parser is to convert the input buffer into a tree of entries -(basically an abstract syntax tree). An entry is defined in \c src/entry.h -and is a blob of loosely structured information. The most important field +The task of the parser is to convert the input buffer into a tree of entries +(basically an abstract syntax tree). An entry is defined in \c src/entry.h +and is a blob of loosely structured information. The most important field is \c section which specifies the kind of information contained in the entry. - + Possible improvements for future versions: - Use one scanner/parser per language instead of one big scanner. - Move the first pass parsing of documentation blocks to a separate module. @@ -104,8 +104,8 @@ Possible improvements for future versions:

Data organizer

-This step consists of many smaller steps, that build -dictionaries of the extracted classes, files, namespaces, +This step consists of many smaller steps, that build +dictionaries of the extracted classes, files, namespaces, variables, functions, packages, pages, and groups. Besides building dictionaries, during this step relations (such as inheritance relations), between the extracted entities are computed. @@ -117,15 +117,15 @@ on the tree of entries, built during language parsing. Look at the The result of this step is a number of dictionaries, which can be found in the doxygen "namespace" defined in \c src/doxygen.h. Most elements of these dictionaries are derived from the class \c Definition; -The class \c MemberDef, for instance, holds all information for a member. -An instance of such a class can be part of a file ( class \c FileDef ), -a class ( class \c ClassDef ), a namespace ( class \c NamespaceDef ), +The class \c MemberDef, for instance, holds all information for a member. +An instance of such a class can be part of a file ( class \c FileDef ), +a class ( class \c ClassDef ), a namespace ( class \c NamespaceDef ), a group ( class \c GroupDef ), or a Java package ( class \c PackageDef ).

Tag file parser

If tag files are specified in the configuration file, these are parsed -by a SAX based XML parser, which can be found in \c src/tagreader.cpp. +by a SAX based XML parser, which can be found in \c src/tagreader.cpp. The result of parsing a tag file is the insertion of \c Entry objects in the entry tree. The field \c Entry::tagInfo is used to mark the entry as external, and holds information about the tag file. @@ -136,7 +136,7 @@ Special comment blocks are stored as strings in the entities that they document. There is a string for the brief description and a string for the detailed description. The documentation parser reads these strings and executes the commands it finds in it (this is the second pass -in parsing the documentation). It writes the result directly to the output +in parsing the documentation). It writes the result directly to the output generators. The parser is written in C++ and can be found in \c src/docparser.cpp. The @@ -144,7 +144,7 @@ tokens that are eaten by the parser come from \c src/doctokenizer.l. Code fragments found in the comment blocks are passed on to the source parser. The main entry point for the documentation parser is \c validatingParseDoc() -declared in \c src/docparser.h. For simple texts with special +declared in \c src/docparser.h. For simple texts with special commands \c validatingParseText() is used.

Source parser

@@ -156,13 +156,13 @@ The code parser tries to cross-reference to source code it parses with documented entities. It also does syntax highlighting of the sources. The output is directly written to the output generators. -The main entry point for the code parser is \c parseCode() +The main entry point for the code parser is \c parseCode() declared in \c src/code.h.

Output generators

-After data is gathered and cross-referenced, doxygen generates -output in various formats. For this it uses the methods provided by +After data is gathered and cross-referenced, doxygen generates +output in various formats. For this it uses the methods provided by the abstract class \c OutputGenerator. In order to generate output for multiple formats at once, the methods of \c OutputList are called instead. This class maintains a list of concrete output generators, @@ -171,15 +171,15 @@ where each method called is delegated to all generators in the list. To allow small deviations in what is written to the output for each concrete output generator, it is possible to temporarily disable certain generators. The OutputList class contains various \c disable() and \c enable() -methods for this. The methods \c OutputList::pushGeneratorState() and +methods for this. The methods \c OutputList::pushGeneratorState() and \c OutputList::popGeneratorState() are used to temporarily save the -set of enabled/disabled output generators on a stack. +set of enabled/disabled output generators on a stack. The XML is generated directly from the gathered data structures. In the future XML will be used as an intermediate language (IL). The output generators will then use this IL as a starting point to generate the specific output formats. The advantage of having an IL is that various -independently developed tools written in various languages, +independently developed tools written in various languages, could extract information from the XML output. Possible tools could be: - an interactive source browser - a class diagram generator @@ -188,18 +188,18 @@ could extract information from the XML output. Possible tools could be:

Debugging

Since doxygen uses a lot of \c flex code it is important to understand -how \c flex works (for this one should read the \c man page) -and to understand what it is doing when \c flex is parsing some input. +how \c flex works (for this one should read the \c man page) +and to understand what it is doing when \c flex is parsing some input. Fortunately, when \c flex is used with the `-d` option it outputs what rules -matched. This makes it quite easy to follow what is going on for a -particular input fragment. +matched. This makes it quite easy to follow what is going on for a +particular input fragment. To make it easier to toggle debug information for a given \c flex file I wrote the following \c perl script, which automatically adds or removes `-d` from the correct line in the \c Makefile: \verbatim -#!/usr/bin/perl +#!/usr/bin/perl $file = shift @ARGV; print "Toggle debugging mode for $file\n"; @@ -232,7 +232,7 @@ if (open(F,"Testing @@ -258,7 +258,7 @@ Studio projects), e.g. `setenv TEST_FLAGS "--id 5 --id 7"` and `make tests`.

Doxyfile differences

-In case one has to communicate through e.g. a forum the configuration settings that +In case one has to communicate through e.g. a forum the configuration settings that are different from the standard doxygen configuration file settings one can run the doxygen command: with the `-x` option and the name of the configuration file (default is `Doxyfile`). The output will be a list of the not default settings (in `Doxyfile` diff --git a/doc/archoverview.gif b/doc/archoverview.gif deleted file mode 100644 index f404076..0000000 Binary files a/doc/archoverview.gif and /dev/null differ diff --git a/doc/archoverview.svg b/doc/archoverview.svg new file mode 100644 index 0000000..11a4340 --- /dev/null +++ b/doc/archoverview.svg @@ -0,0 +1,625 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/install.doc b/doc/install.doc index 9820f3c..97a0d7a 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -29,16 +29,15 @@ If you downloaded the source distribution, you need at least the following to build the executable: @@ -55,7 +54,7 @@ tools should be installed. TeX Live This is needed for generating \LaTeX, Postscript, and PDF output.
  • - the Graph visualization toolkit version 1.8.10 or higher + the Graph visualization toolkit version 2.38 or higher Needed for the include dependency graphs, the graphical inheritance graphs, and the collaboration graphs. If you compile graphviz yourself, make sure you do include @@ -165,7 +164,7 @@ From version 1.8.10 onwards, build files need to be generated by cmake. cmake can be downloaded from https://cmake.org/download/ \addindex cmake -At the moment only the express version of Visual Studio 2013 is tested, +At the moment only the express version of Visual Studio 2015 and 2017 are tested, but other version might also work. Alternatively, you can compile doxygen @@ -199,7 +198,16 @@ cd into the \c doxygen-x.y.z directory, create and cd to a build directory \verbatim mkdir build cd build -cmake -G "Visual Studio 12 2013" .. +cmake -G "Visual Studio 14 2015" .. +\endverbatim +This will create a project file then can be opened in Visual Studio. + +If you prefer compiling from the command prompt you can use the following instead: +\verbatim +mkdir build +cd build +cmake -G "NMake Makefiles" .. +nmake \endverbatim Note that compiling Doxywizard requires Qt 4.3 or newer @@ -214,7 +222,7 @@ Doxygen comes as a self-installing archive, so installation is extremely simple. Just follow the dialogs. After installation it is recommended to also download and install GraphViz -(version 2.20 or better is highly recommended). Doxygen can use the \c dot tool +(version 2.38 or better is highly recommended). Doxygen can use the \c dot tool of the GraphViz package to render nicer diagrams, see the \ref cfg_have_dot "HAVE_DOT" option in the configuration file. -- cgit v0.12