doc/diagrams.doc

   1 /******************************************************************************
   2  *
   3  *
   4  *
   5  * Copyright (C) 1997-2012 by Dimitri van Heesch.
   6  *
   7  * Permission to use, copy, modify, and distribute this software and its
   8  * documentation under the terms of the GNU General Public License is hereby
   9  * granted. No representations are made about the suitability of this software
  10  * for any purpose. It is provided "as is" without express or implied warranty.
  11  * See the GNU General Public License for more details.
  12  *
  13  * Documents produced by Doxygen are derivative works derived from the
  14  * input used in their production; they are not affected by this license.
  15  *
  16  */
  17 /*! \page diagrams Graphs and diagrams
  18
  19   Doxygen has built-in support to generate inheritance diagrams for C++
  20   classes.
  21
  22   Doxygen can use the "dot" tool from graphviz to generate
  23   more advanced diagrams and graphs. Graphviz is an open-source,
  24   cross-platform graph drawing toolkit and can be found
  25   at http://www.graphviz.org/
  26
  27   If you have the "dot" tool in the path, you can set
  28   \ref cfg_have_dot "HAVE_DOT" to \c YES in the configuration file to
  29   let doxygen use it.
  30
  31   Doxygen uses the "dot" tool to generate the following graphs:
  32   <ul>
  33   <li>A graphical representation of the class hierarchy will be drawn, along
  34       with the textual one. Currently this feature is supported for HTML only.\n
  35       <b>Warning:</b> When you have a very large class hierarchy where many
  36       classes derive from a common base class, the resulting image may become
  37       too big to handle for some browsers.
  38   <li>An inheritance graph will be generated for each documented class showing the
  39       direct and indirect inheritance relations. This disables the
  40       generation of the built-in class inheritance diagrams.
  41   <li>An include dependency graph is generated for each documented file that
  42       includes at least one other file. This feature is currently supported
  43       for HTML and RTF only.
  44   <li>An inverse include dependency graph is also generated showing for
  45       a (header) file, which other files include it.
  46   <li>A graph is drawn for each documented class and struct that shows:
  47       <ul>
  48       <li> the inheritance relations with base classes.
  49       <li> the usage relations with other structs and classes (e.g.
  50            class \c A has a member variable \c m_a of type class \c B, then
  51            \c A has an arrow to \c B with \c m_a as label).
  52       </ul>
  53   <li>if \ref cfg_call_graph "CALL_GRAPH" is set to YES, a
  54       graphical call graph is drawn for each function showing the
  55       functions that the function directly or indirectly calls.
  56   <li>if \ref cfg_caller_graph "CALLER_GRAPH" is set to YES, a
  57       graphical caller graph is drawn for each function showing the
  58       functions that the function is directly or indirectly called by.
  59   </ul>
  60
  61   Using a \ref customize "layout file" you can determine which of the
  62   graphs are actually shown.
  63
  64   The options \ref cfg_dot_graph_max_nodes "DOT_GRAPH_MAX_NODES" and
  65   \ref cfg_max_dot_graph_depth "MAX_DOT_GRAPH_DEPTH" can be used to
  66   limit the size of the various graphs.
  67
  68   The elements in the class diagrams in HTML and RTF
  69   have the following meaning:
  70   <ul>
  71   <li> A \b yellow box indicates a class. A box can have a
  72        little marker in the lower right corner to indicate that the class
  73        contains base classes that are hidden.
  74        For the class diagrams the maximum tree width is currently 8 elements.
  75        If a tree is wider some nodes will be hidden.
  76        If the box is filled with a
  77        dashed pattern the inheritance relation is virtual.
  78   <li> A \b white box indicates that the documentation of the class
  79        is currently shown.
  80   <li> A \b gray box indicates an undocumented class.
  81   <li> A <b>solid dark blue</b> arrow indicates public inheritance.
  82   <li> A <b>dashed dark green</b> arrow indicates protected inheritance.
  83   <li> A <b>dotted dark green</b> arrow indicates private inheritance.
  84   </ul>
  85
  86   The elements in the class diagram in \f$\mbox{\LaTeX}\f$ have the
  87   following meaning:
  88   <ul>
  89   <li> A \b white box indicates a class.
  90        A \b marker in the lower right corner of the box indicates that the
  91        class has base classes that are hidden.
  92        If the box has a \b dashed border this indicates virtual inheritance.
  93   <li> A \b solid arrow indicates public inheritance.
  94   <li> A \b dashed arrow indicates protected inheritance.
  95   <li> A \b dotted arrow indicates private inheritance.
  96   </ul>
  97
  98   The elements in the graphs generated by the dot tool have the following
  99   meaning:
 100   <ul>
 101   <li> A \b white box indicates a class or struct or file.
 102   <li> A box with a \b red border indicates a node that has
 103        \e more arrows than are shown!
 104        In other words: the graph is \e truncated with respect to this node.
 105        The reason why a graph is sometimes truncated is to prevent images
 106        from becoming too large.
 107        For the graphs generated with dot doxygen tries
 108        to limit the width of the resulting image to 1024 pixels.
 109   <li> A \b black box indicates that the class' documentation is currently shown.
 110   <li> A <b>dark blue</b> arrow indicates an include relation (for the
 111        include dependency graph) or public inheritance (for the other graphs).
 112   <li> A <b>dark green</b> arrow indicates protected inheritance.
 113   <li> A <b>dark red</b> arrow indicates private inheritance.
 114   <li> A <b>purple dashed</b> arrow indicated a "usage" relation, the
 115        edge of the arrow is labeled with the variable(s) responsible for the
 116        relation.
 117        Class \c A uses class \c B, if class \c A has a member variable \c m
 118        of type C, where B is a subtype of C (e.g. `C` could be `B`, `B*`, `T\<B\>*`).
 119   </ul>
 120
 121
 122 Here are a couple of header files that together show the various diagrams
 123 that doxygen can generate:
 124
 125 <code>diagrams_a.h</code>
 126 \verbinclude diagrams_a.h
 127 <code>diagrams_b.h</code>
 128 \verbinclude diagrams_b.h
 129 <code>diagrams_c.h</code>
 130 \verbinclude diagrams_c.h
 131 <code>diagrams_d.h</code>
 132 \verbinclude diagrams_d.h
 133 <code>diagrams_e.h</code>
 134 \verbinclude diagrams_e.h
 135
 136  \htmlonly
 137  Click <a href="$(DOXYGEN_DOCDIR)/examples/diagrams/html/index.html">here</a>
 138  for the corresponding HTML documentation that is generated by doxygen<br/>
 139  (<code>EXTRACT_ALL</code> = <code>YES</code> is used here).<p>
 140  \endhtmlonly
 141
 142 \htmlonly
 143 Go to the <a href="preprocessing.html">next</a> section or return to the
 144  <a href="index.html">index</a>.
 145 \endhtmlonly
 146
 147 */
 148