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