doc/autolink.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 autolink Automatic link generation
  18
  19   \tableofcontents
  20
  21   Most documentation systems have special `see also' sections where links
  22   to other pieces of documentation can be inserted.
  23   Although doxygen also has a command to start such a section (See section
  24   \ref cmdsa "\\sa"), it does allow you to put these kind of links anywhere in the
  25   documentation.
  26   For \f$\mbox{\LaTeX}\f$ documentation a reference to the page number
  27   is written instead of a link. Furthermore, the index at the end of the
  28   document can be used to quickly find the documentation of a member, class,
  29   namespace or file.
  30   For man pages no reference information is generated.
  31
  32   The next sections show how to generate links to the various documented
  33   entities in a source file.
  34
  35   \section linkurl Links to web pages and mail addresses
  36
  37   Doxygen will automatically replace any URLs and mail addresses found in the
  38   documentation by links (in HTML). To manually specify link text, use the
  39   HTML '<tt>a</tt>' tag:
  40   \verbatim <a href="linkURL">link text</a> \endverbatim
  41   which will be automatically translated to other output formats by Doxygen.
  42
  43   \section linkclass Links to classes
  44
  45   All words in the documentation that correspond to a documented class and
  46   contain at least one non-lower case character will automatically be
  47   replaced by a link to the page containing the
  48   documentation of the class. If you want to prevent that a word
  49   that corresponds to a documented class is replaced by a link you
  50   should put a \% in front of the word.
  51   To link to an all lower case symbol, use \ref cmdref "\\ref".
  52
  53   \section linkfile Links to files
  54
  55   All words that contain a dot (<tt>.</tt>) that is not the last character
  56   in the word are considered to be file names.
  57   If the word is indeed the name of a documented input file, a link will
  58   automatically be created to the documentation of that file.
  59
  60   \section linkfunc Links to functions
  61
  62   Links to functions are created if one of the following patterns is
  63   encountered:
  64   <ol>
  65   <li><tt>\<functionName\>"("\<argument-list\>")"</tt>
  66   <li><tt>\<functionName\>"()"</tt>
  67   <li><tt>"::"\<functionName\></tt>
  68   <li><tt>(\<className\>"::")<sup>n</sup>\<functionName\>"("\<argument-list\>")"</tt>
  69   <li><tt>(\<className\>"::")<sup>n</sup>\<functionName\>"("\<argument-list\>")"\<modifiers\></tt>
  70   <li><tt>(\<className\>"::")<sup>n</sup>\<functionName\>"()"</tt>
  71   <li><tt>(\<className\>"::")<sup>n</sup>\<functionName\></tt>
  72   </ol>
  73   where n\>0.
  74
  75   \par Note 1:
  76     Function arguments should be specified with correct types, i.e.
  77     'fun(const std::string&,bool)' or '()' to match any prototype.
  78   \par Note 2:
  79     Member function modifiers (like 'const' and 'volatile')
  80     are required to identify the target, i.e. 'func(int) const' and 'fun(int)'
  81     target different member functions.
  82   \par Note 3:
  83     For JavaDoc compatibility a \# may be used instead of a :: in
  84     the patterns above.
  85   \par Note 4:
  86     In the documentation of a class containing a member foo,
  87     a reference to a global variable is made using "::foo", whereas \#foo
  88     will link to the member.
  89
  90   For non overloaded members the argument list may be omitted.
  91
  92   If a function is overloaded and no matching argument list is specified
  93   (i.e. pattern 2 or 6 is used), a link will be created to the
  94   documentation of one of the overloaded members.
  95
  96   For member functions the class scope (as used in patterns 4 to 7) may
  97   be omitted, if:
  98   <ol>
  99   <li>The pattern points to a documented member that belongs to the same class
 100       as the documentation block that contains the pattern.
 101   <li>The class that corresponds to the documentation blocks that contains
 102       the pattern has a base class that contains a documented member
 103       that matches the pattern.
 104   </ol>
 105
 106   \section linkother Links to other members
 107
 108   All of these entities can be linked to in the same way as described in the
 109   previous section. For sake of clarity it is advised to only use
 110   patterns 3 and 7 in this case.
 111
 112   \par Example:
 113   \verbinclude autolink.cpp
 114   \htmlonly
 115   Click <a href="$(DOXYGEN_DOCDIR)/examples/autolink/html/index.html">here</a>
 116   for the corresponding HTML documentation that is generated by Doxygen.
 117   \endhtmlonly
 118
 119   \section resolving typedefs
 120
 121   Typedefs that involve classes, structs and unions, like
 122 \verbatim
 123 typedef struct StructName TypeName
 124 \endverbatim
 125   create an alias for StructName, so links will be generated to StructName,
 126   when either StructName itself or TypeName is encountered.
 127
 128   \par Example:
 129   \verbinclude restypedef.cpp
 130   \htmlonly
 131   Click <a href="$(DOXYGEN_DOCDIR)/examples/restypedef/html/restypedef_8cpp.html">here</a>
 132   for the corresponding HTML documentation that is generated by Doxygen.
 133   \endhtmlonly
 134 */