src/doxygen.md

   1 Doxygen Internals {#mainpage}
   2 =================
   3
   4 Introduction
   5 ------------
   6
   7 This page provides a high-level overview of the internals of doxygen, with
   8 links to the relevant parts of the code. This document is intended for
   9 developers who want to work on doxygen. Users of doxygen are refered to the
  10 [User Manual](http://www.doxygen.org/manual.html).
  11
  12 The generic starting point of the application is of cource the main() function.
  13
  14 Configuration options
  15 ---------------------
  16
  17 Configuration file data is stored in singleton class Config and can be
  18 accessed using wrapper macros
  19 Config_getString(), Config_getInt(), Config_getList(),
  20 Config_getEnum(), and Config_getBool() depending on the type of the
  21 option.
  22
  23 The format of the configuration file (options and types) is defined
  24 by the file `config.xml`. As part of the build process,
  25 the python script `configgen.py` will create a file configoptions.cpp
  26 from this, which serves as the input for the configuration file parser
  27 that is invoked using Config::parse()
  28
  29 Gathering Input files
  30 ---------------------
  31
  32 After the configuration is known, the input files are searched using
  33 searchInputFiles() and any tag files are read using readTagFile()
  34
  35 Parsing Input files
  36 -------------------
  37
  38 The function parseFiles() takes care of parsing all files.
  39 It uses the ParserManager singleton factory to create a suitable parser object
  40 for each file. Each parser implements the abstract interface ParserInterface.
  41
  42 If the parser indicates it needs preprocessing
  43 via ParserInterface::needsPreprocessing(), doxygen will call preprocessFile()
  44 on the file.
  45
  46 A second step is to convert multiline C++-style comments into C style comments
  47 for easier processing later on. As side effect of this step also
  48 aliases (ALIASES option) are resolved. The function that performs these
  49 2 tasks is called convertCppComments().
  50
  51 *Note:* Alias resolution should better be done in a separate step as it is
  52 now coupled to C/C++ code and does not work automatically for other languages!
  53
  54 The third step is the actual language parsing and is done by calling
  55 ParserInterface::parseInput() on the parser interface returned by
  56 the ParserManager.
  57
  58 The result of parsing is a tree of Entry objects.
  59 These Entry objects are wrapped in a EntryNav object and stored on disk using
  60 Entry::createNavigationIndex() on the root node of the tree.
  61
  62 Each Entry object roughly contains the raw data for a symbol and is later
  63 converted into a Definition object.
  64
  65 When a parser finds a special comment block in the input, it will do a first
  66 pass parsing via parseCommentBlock(). During this pass the comment block
  67 is split into multiple parts if needed. Some data that is later needed is
  68 extracted like section labels, xref items, and formulas.
  69 Also Markdown markup is processed using processMarkdown() during this pass.
  70
  71 Resolving relations
  72 -------------------
  73
  74 The Entry objects created and filled during parsing are stored on disk
  75 (to keep memory needs low). The name, parent/child relation, and
  76 location on disk of each Entry is stored as a tree of EntryNav nodes, which is
  77 kept in memory.
  78
  79 Doxygen does a number of tree walks over the EntryNav nodes in the tree to
  80 build up the data structures needed to produce the output.
  81
  82 The resulting data structures are all children of the generic base class
  83 called Definition which holds all non-specific data for a symbol definition.
  84
  85 Definition is an abstract base class. Concrete subclasses are
  86 - ClassDef: for storing class/struct/union related data
  87 - NamespaceDef: for storing namespace related data
  88 - FileDef: for storing file related data
  89 - DirDef: for storing directory related data
  90
  91 For doxygen specific concepts the following subclasses are available
  92 - GroupDef: for storing grouping related data
  93 - PageDef: for storing page related data
  94
  95 Finally the data for members of classes, namespaces, and files is stored is
  96 the subclass MemberDef.
  97
  98 Producing output
  99 ----------------
 100
 101 TODO
 102
 103 Topics TODO
 104 -----------
 105 - Grouping of files in Model / Parser / Generator categories
 106 - Index files based on IndexIntf
 107   - HTML navigation
 108   - HTML Help (chm)
 109   - Documentation Sets (XCode)
 110   - Qt Help (qhp)
 111   - Eclipse Help
 112 - Search index
 113   - Javascript based
 114   - Server based
 115   - External
 116 - Citations
 117   - via bibtex
 118 - Various processing steps for a comment block
 119   - comment conversion
 120   - comment scanner
 121   - markdown processor
 122   - doc tokeninzer
 123   - doc parser
 124   - doc visitors
 125 - Diagrams and Images
 126   - builtin
 127   - via Graphviz dot
 128   - via mscgen
 129   - PNG generation
 130 - Output formats: OutputGen, OutputList, and DocVisitor
 131   - Html:  HtmlGenerator and HtmlDocVisitor
 132   - Latex: LatexGenerator and LatexDocVisitor
 133   - RTF:   RTFGenerator and RTFDocVisitor
 134   - Man:   ManGenerator and ManDocVisitor
 135   - XML:   generateXML() and XmlDocVisitor
 136   - print: debugging via PrintDocVisitor
 137   - text:  TextDocVisitor for tooltips
 138   - perlmod
 139 - i18n via Translator and language.cpp
 140 - Customizing the layout via LayoutDocManager
 141 - Parsers
 142   - C Preprocessing
 143     - const expression evaluation
 144   - C link languages
 145   - Python
 146   - Fortran
 147   - VHDL
 148   - TCL
 149   - Tag files
 150 - Marshaling to/from disk
 151 - Portability functions
 152 - Utility functions
 153