|
Packit Service |
50c9f2 |
Doxygen Internals {#mainpage}
|
|
Packit Service |
50c9f2 |
=================
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Introduction
|
|
Packit Service |
50c9f2 |
------------
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
This page provides a high-level overview of the internals of doxygen, with
|
|
Packit Service |
50c9f2 |
links to the relevant parts of the code. This document is intended for
|
|
Packit Service |
50c9f2 |
developers who want to work on doxygen. Users of doxygen are referred to the
|
|
Packit Service |
50c9f2 |
[User Manual](http://www.doxygen.org/manual.html).
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The generic starting point of the application is of cource the main() function.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Configuration options
|
|
Packit Service |
50c9f2 |
---------------------
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Configuration file data is stored in singleton class Config and can be
|
|
Packit Service |
50c9f2 |
accessed using wrapper macros
|
|
Packit Service |
50c9f2 |
Config_getString(), Config_getInt(), Config_getList(),
|
|
Packit Service |
50c9f2 |
Config_getEnum(), and Config_getBool() depending on the type of the
|
|
Packit Service |
50c9f2 |
option.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The format of the configuration file (options and types) is defined
|
|
Packit Service |
50c9f2 |
by the file `config.xml`. As part of the build process,
|
|
Packit Service |
50c9f2 |
the python script `configgen.py` will create a file configoptions.cpp
|
|
Packit Service |
50c9f2 |
from this, which serves as the input for the configuration file parser
|
|
Packit Service |
50c9f2 |
that is invoked using Config::parse(). The script `configgen.py` will also
|
|
Packit Service |
50c9f2 |
create the documentation for the configuration items, creating the file
|
|
Packit Service |
50c9f2 |
`config.doc`.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Gathering Input files
|
|
Packit Service |
50c9f2 |
---------------------
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
After the configuration is known, the input files are searched using
|
|
Packit Service |
50c9f2 |
searchInputFiles() and any tag files are read using readTagFile()
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Parsing Input files
|
|
Packit Service |
50c9f2 |
-------------------
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The function parseFiles() takes care of parsing all files.
|
|
Packit Service |
50c9f2 |
It uses the ParserManager singleton factory to create a suitable parser object
|
|
Packit Service |
50c9f2 |
for each file. Each parser implements the abstract interface ParserInterface.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
If the parser indicates it needs preprocessing
|
|
Packit Service |
50c9f2 |
via ParserInterface::needsPreprocessing(), doxygen will call preprocessFile()
|
|
Packit Service |
50c9f2 |
on the file.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
A second step is to convert multiline C++-style comments into C style comments
|
|
Packit Service |
50c9f2 |
for easier processing later on. As side effect of this step also
|
|
Packit Service |
50c9f2 |
aliases (ALIASES option) are resolved. The function that performs these
|
|
Packit Service |
50c9f2 |
2 tasks is called convertCppComments().
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
*Note:* Alias resolution should better be done in a separate step as it is
|
|
Packit Service |
50c9f2 |
now coupled to C/C++ code and does not work automatically for other languages!
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The third step is the actual language parsing and is done by calling
|
|
Packit Service |
50c9f2 |
ParserInterface::parseInput() on the parser interface returned by
|
|
Packit Service |
50c9f2 |
the ParserManager.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The result of parsing is a tree of Entry objects.
|
|
Packit Service |
50c9f2 |
These Entry objects are wrapped in a EntryNav object and stored on disk using
|
|
Packit Service |
50c9f2 |
Entry::createNavigationIndex() on the root node of the tree.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Each Entry object roughly contains the raw data for a symbol and is later
|
|
Packit Service |
50c9f2 |
converted into a Definition object.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
When a parser finds a special comment block in the input, it will do a first
|
|
Packit Service |
50c9f2 |
pass parsing via parseCommentBlock(). During this pass the comment block
|
|
Packit Service |
50c9f2 |
is split into multiple parts if needed. Some data that is later needed is
|
|
Packit Service |
50c9f2 |
extracted like section labels, xref items, and formulas.
|
|
Packit Service |
50c9f2 |
Also Markdown markup is processed using processMarkdown() during this pass.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Resolving relations
|
|
Packit Service |
50c9f2 |
-------------------
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The Entry objects created and filled during parsing are stored on disk
|
|
Packit Service |
50c9f2 |
(to keep memory needs low). The name, parent/child relation, and
|
|
Packit Service |
50c9f2 |
location on disk of each Entry is stored as a tree of EntryNav nodes, which is
|
|
Packit Service |
50c9f2 |
kept in memory.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Doxygen does a number of tree walks over the EntryNav nodes in the tree to
|
|
Packit Service |
50c9f2 |
build up the data structures needed to produce the output.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The resulting data structures are all children of the generic base class
|
|
Packit Service |
50c9f2 |
called Definition which holds all non-specific data for a symbol definition.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Definition is an abstract base class. Concrete subclasses are
|
|
Packit Service |
50c9f2 |
- ClassDef: for storing class/struct/union related data
|
|
Packit Service |
50c9f2 |
- NamespaceDef: for storing namespace related data
|
|
Packit Service |
50c9f2 |
- FileDef: for storing file related data
|
|
Packit Service |
50c9f2 |
- DirDef: for storing directory related data
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
For doxygen specific concepts the following subclasses are available
|
|
Packit Service |
50c9f2 |
- GroupDef: for storing grouping related data
|
|
Packit Service |
50c9f2 |
- PageDef: for storing page related data
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Finally the data for members of classes, namespaces, and files is stored in
|
|
Packit Service |
50c9f2 |
the subclass MemberDef.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Producing debug output
|
|
Packit Service |
50c9f2 |
----------------------
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Within doxygen there are a number of ways to obtain debug output. Besides the
|
|
Packit Service |
50c9f2 |
invasive method of putting print statements in the code there are a number of
|
|
Packit Service |
50c9f2 |
easy ways to get debug information.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
- Compilation of `.l` files
|
|
Packit Service |
50c9f2 |
This is also an invasive method but it will be automatically done by the
|
|
Packit Service |
50c9f2 |
`flex / lex` command. The result is that of each input line the (lex) rule(s)
|
|
Packit Service |
50c9f2 |
that are applied on it are shown.
|
|
Packit Service |
50c9f2 |
- windows
|
|
Packit Service |
50c9f2 |
- in the Visual C++ GUI
|
|
Packit Service |
50c9f2 |
- find the required `.l` file
|
|
Packit Service |
50c9f2 |
- select the `Properties` of this file
|
|
Packit Service |
50c9f2 |
- set the item `Write used lex rules` to `Yes`
|
|
Packit Service |
50c9f2 |
- see to it that the `.l` file is newer than the corresponding `.cpp` file
|
|
Packit Service |
50c9f2 |
or remove the corresponding `.cpp` file
|
|
Packit Service |
50c9f2 |
- unices
|
|
Packit Service |
50c9f2 |
- global change
|
|
Packit Service |
50c9f2 |
In the chapter "Doxygen's internals" a `perl` script is given to toggle the
|
|
Packit Service |
50c9f2 |
possibility of having the rules debug information.
|
|
Packit Service |
50c9f2 |
- command line change
|
|
Packit Service |
50c9f2 |
It is possible to the option `LEX="flex -d"` with the `make` command on the
|
|
Packit Service |
50c9f2 |
command line. In this case the `.l` that are converted to the corresponding
|
|
Packit Service |
50c9f2 |
`.cpp` files during this `make` get the rules debug information.
|
|
Packit Service |
50c9f2 |
To undo the rules debug information output just recompile the file with
|
|
Packit Service |
50c9f2 |
just `make`.
|
|
Packit Service |
50c9f2 |
Note this method applies for all the `.l` files that are rebuild to `.cpp`
|
|
Packit Service |
50c9f2 |
files so be sure that only the `.l` files(s) of which you want to have the
|
|
Packit Service |
50c9f2 |
rules debug information is (are) newer than the corresponding `.cpp`
|
|
Packit Service |
50c9f2 |
file(s).
|
|
Packit Service |
50c9f2 |
- Running doxygen
|
|
Packit Service |
50c9f2 |
During a run of doxygen it is possible to specify the `-d` option with the
|
|
Packit Service |
50c9f2 |
following possibilities (each option has to be preceded by `-d`):
|
|
Packit Service |
50c9f2 |
- findmembers
|
|
Packit Service |
50c9f2 |
Gives of global, class, module members its scope, arguments and other relevant information.
|
|
Packit Service |
50c9f2 |
- functions
|
|
Packit Service |
50c9f2 |
Gives of functions its scope, arguments and other relevant information.
|
|
Packit Service |
50c9f2 |
- variables
|
|
Packit Service |
50c9f2 |
Gives of variables its scope and other relevant information.
|
|
Packit Service |
50c9f2 |
- classes
|
|
Packit Service |
50c9f2 |
Gives of classes en modules its scope and other relevant information.
|
|
Packit Service |
50c9f2 |
- preprocessor
|
|
Packit Service |
50c9f2 |
Shows the results of the preprocessing phase, i.e. results from include files,
|
|
Packit Service |
50c9f2 |
<tt>\#define</tt> statements etc., definitions in the doxygen configuration file like:
|
|
Packit Service |
50c9f2 |
`EXPAND_ONLY_PREDEF`, `PREDEFINED` and `MACRO_EXPANSION`.
|
|
Packit Service |
50c9f2 |
- commentcnv
|
|
Packit Service |
50c9f2 |
Shows the results of the comment conversion, the comment conversion does the
|
|
Packit Service |
50c9f2 |
following:
|
|
Packit Service |
50c9f2 |
- It converts multi-line C++ style comment blocks (that are aligned)
|
|
Packit Service |
50c9f2 |
to C style comment blocks (if `MULTILINE_CPP_IS_BRIEF` is set to `NO`).
|
|
Packit Service |
50c9f2 |
- It replaces aliases with their definition (see `ALIASES`)
|
|
Packit Service |
50c9f2 |
- It handles conditional sections (<tt>\\cond ... \\endcond</tt> blocks)
|
|
Packit Service |
50c9f2 |
- commentscan
|
|
Packit Service |
50c9f2 |
Will print each comment block before and after the comment is interpreted by
|
|
Packit Service |
50c9f2 |
the comment scanner.
|
|
Packit Service |
50c9f2 |
- printtree
|
|
Packit Service |
50c9f2 |
Give the results in in pretty print way, i.e. in an XML like way with each
|
|
Packit Service |
50c9f2 |
level indented by a `"."` (dot).
|
|
Packit Service |
50c9f2 |
- time
|
|
Packit Service |
50c9f2 |
Provides information of the different stages of the doxygen process.
|
|
Packit Service |
50c9f2 |
- extcmd
|
|
Packit Service |
50c9f2 |
Shows which external commands are executed and which pipes are opened.
|
|
Packit Service |
50c9f2 |
- markdown
|
|
Packit Service |
50c9f2 |
Will print each comment block before and after Markdown processing.
|
|
Packit Service |
50c9f2 |
- filteroutput
|
|
Packit Service |
50c9f2 |
Gives the output of the output as result of the filter command (when a filter
|
|
Packit Service |
50c9f2 |
command is specified)
|
|
Packit Service |
50c9f2 |
- validate
|
|
Packit Service |
50c9f2 |
Currently not used
|
|
Packit Service |
50c9f2 |
- lex
|
|
Packit Service |
50c9f2 |
Provide output of the `lex` files used. When a lexer is started and when a lexer
|
|
Packit Service |
50c9f2 |
ends the name of the `lex` file is given so it is possible to see in which lexer the
|
|
Packit Service |
50c9f2 |
problem occurs. This makes it easier to select the file to be compiled in `lex` debug mode.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Producing output
|
|
Packit Service |
50c9f2 |
----------------
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
TODO
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Topics TODO
|
|
Packit Service |
50c9f2 |
-----------
|
|
Packit Service |
50c9f2 |
- Grouping of files in Model / Parser / Generator categories
|
|
Packit Service |
50c9f2 |
- Index files based on IndexIntf
|
|
Packit Service |
50c9f2 |
- HTML navigation
|
|
Packit Service |
50c9f2 |
- HTML Help (chm)
|
|
Packit Service |
50c9f2 |
- Documentation Sets (XCode)
|
|
Packit Service |
50c9f2 |
- Qt Help (qhp)
|
|
Packit Service |
50c9f2 |
- Eclipse Help
|
|
Packit Service |
50c9f2 |
- Search index
|
|
Packit Service |
50c9f2 |
- Javascript based
|
|
Packit Service |
50c9f2 |
- Server based
|
|
Packit Service |
50c9f2 |
- External
|
|
Packit Service |
50c9f2 |
- Citations
|
|
Packit Service |
50c9f2 |
- via bibtex
|
|
Packit Service |
50c9f2 |
- Various processing steps for a comment block
|
|
Packit Service |
50c9f2 |
- comment conversion
|
|
Packit Service |
50c9f2 |
- comment scanner
|
|
Packit Service |
50c9f2 |
- markdown processor
|
|
Packit Service |
50c9f2 |
- doc tokenizer
|
|
Packit Service |
50c9f2 |
- doc parser
|
|
Packit Service |
50c9f2 |
- doc visitors
|
|
Packit Service |
50c9f2 |
- Diagrams and Images
|
|
Packit Service |
50c9f2 |
- builtin
|
|
Packit Service |
50c9f2 |
- via Graphviz dot
|
|
Packit Service |
50c9f2 |
- via mscgen
|
|
Packit Service |
50c9f2 |
- PNG generation
|
|
Packit Service |
50c9f2 |
- Output formats: OutputGen, OutputList, and DocVisitor
|
|
Packit Service |
50c9f2 |
- Html: HtmlGenerator and HtmlDocVisitor
|
|
Packit Service |
50c9f2 |
- Latex: LatexGenerator and LatexDocVisitor
|
|
Packit Service |
50c9f2 |
- RTF: RTFGenerator and RTFDocVisitor
|
|
Packit Service |
50c9f2 |
- Man: ManGenerator and ManDocVisitor
|
|
Packit Service |
50c9f2 |
- XML: generateXML() and XmlDocVisitor
|
|
Packit Service |
50c9f2 |
- print: debugging via PrintDocVisitor
|
|
Packit Service |
50c9f2 |
- text: TextDocVisitor for tooltips
|
|
Packit Service |
50c9f2 |
- perlmod
|
|
Packit Service |
50c9f2 |
- i18n via Translator and language.cpp
|
|
Packit Service |
50c9f2 |
- Customizing the layout via LayoutDocManager
|
|
Packit Service |
50c9f2 |
- Parsers
|
|
Packit Service |
50c9f2 |
- C Preprocessing
|
|
Packit Service |
50c9f2 |
- const expression evaluation
|
|
Packit Service |
50c9f2 |
- C link languages
|
|
Packit Service |
50c9f2 |
- Python
|
|
Packit Service |
50c9f2 |
- Fortran
|
|
Packit Service |
50c9f2 |
- VHDL
|
|
Packit Service |
50c9f2 |
- TCL
|
|
Packit Service |
50c9f2 |
- Tag files
|
|
Packit Service |
50c9f2 |
- Marshaling to/from disk
|
|
Packit Service |
50c9f2 |
- Portability functions
|
|
Packit Service |
50c9f2 |
- Utility functions
|
|
Packit Service |
50c9f2 |
|