summaryrefslogtreecommitdiffstats
path: root/doc/autolink.doc
blob: 8279d903053f4e44592089b897821928a7ec481a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
/******************************************************************************
 *
 * 
 *
 * Copyright (C) 1997-2008 by Dimitri van Heesch.
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation under the terms of the GNU General Public License is hereby 
 * granted. No representations are made about the suitability of this software 
 * for any purpose. It is provided "as is" without express or implied warranty.
 * See the GNU General Public License for more details.
 *
 * Documents produced by Doxygen are derivative works derived from the
 * input used in their production; they are not affected by this license.
 *
 */
/*! \page autolink Automatic link generation

  Most documentation systems have special `see also' sections where links
  to other pieces of documentation can be inserted.
  Although doxygen also has a command to start such a section (See section
  \ref cmdsa "\\sa"), it does allow you to put these kind of links anywhere in the
  documentation. 
  For \f$\mbox{\LaTeX}\f$ documentation a reference to the page number
  is written instead of a link. Furthermore, the index at the end of the 
  document can be used to quickly find the documentation of a member, class, 
  namespace or file.
  For man pages no reference information is generated.

  The next sections show how to generate links to the various documented 
  entities in a source file.

  \section linkurl Links to web pages and mail addresses

  Doxygen will automatically replace any URLs and mail addresses found in the
  documentation by links (in HTML). To manually specify link text, use the
  HTML '<tt>a</tt>' tag:
  \verbatim <a href="linkURL">link text</a> \endverbatim
  which will be automatically translated to other output formats by Doxygen.

  \section linkclass Links to classes.

  All words in the documentation that correspond to a documented class and
  contain at least one non-lower case character will automatically be 
  replaced by a link to the page containing the 
  documentation of the class. If you want to prevent that a word 
  that corresponds to a documented class is replaced by a link you
  should put a \% in front of the word.
  To link to an all lower case symbol, use \ref cmdref "\\ref".

  \section linkfile Links to files.

  All words that contain a dot (<tt>.</tt>) that is not the last character
  in the word are considered to be file names.
  If the word is indeed the name of a documented input file, a link will 
  automatically be created to the documentation of that file.

  \section linkfunc Links to functions.

  Links to functions are created if one of the following patterns is 
  encountered:
  <ol>
  <li><tt>\<functionName\>"("\<argument-list\>")"</tt>
  <li><tt>\<functionName\>"()"</tt>
  <li><tt>"::"\<functionName\></tt>
  <li><tt>(\<className\>"::")<sup>n</sup>\<functionName\>"("\<argument-list\>")"</tt>
  <li><tt>(\<className\>"::")<sup>n</sup>\<functionName\>"("\<argument-list\>")"\<modifiers\></tt>
  <li><tt>(\<className\>"::")<sup>n</sup>\<functionName\>"()"</tt>
  <li><tt>(\<className\>"::")<sup>n</sup>\<functionName\></tt>
  </ol>
  where n\>0. 

  \par Note 1: 
    Function arguments should be specified with correct types, i.e. 
    'fun(const std::string&,bool)' or '()' to match any prototype.
  \par Note 2:
    Member function modifiers (like 'const' and 'volatile') 
    are required to identify the target, i.e. 'func(int) const' and 'fun(int)'
    target different member functions.
  \par Note 3: 
    For JavaDoc compatibility a \# may be used instead of a :: in 
    the patterns above.
  \par Note 4:
    In the documentation of a class containing a member foo, 
    a reference to a global variable is made using "::foo", whereas \#foo
    will link to the member.

  For non overloaded members the argument list may be omitted.

  If a function is overloaded and no matching argument list is specified
  (i.e. pattern 2 or 6 is used), a link will be created to the 
  documentation of one of the overloaded members.

  For member functions the class scope (as used in patterns 4 to 7) may
  be omitted, if:
  <ol>
  <li>The pattern points to a documented member that belongs to the same class
      as the documentation block that contains the pattern. 
  <li>The class that corresponds to the documentation blocks that contains
      the pattern has a base class that contains a documented member
      that matches the pattern.
  </ol>

  \section linkother Links to variables, typedefs, enum types, enum values and defines.

  All of these entities can be linked to in the same way as described in the 
  previous section. For sake of clarity it is advised to only use 
  patterns 3 and 7 in this case.

  \par Example:
  \verbinclude autolink.cpp
  \htmlonly
  Click <a href="$(DOXYGEN_DOCDIR)/examples/autolink/html/index.html">here</a> 
  for the corresponding HTML documentation that is generated by Doxygen.
  \endhtmlonly

  \section resolving typedefs.

  Typedefs that involve classes, structs and unions, like
\verbatim
typedef struct StructName TypeName
\endverbatim
  create an alias for StructName, so links will be generated to StructName, 
  when either StructName itself or TypeName is encountered.
  
  \par Example:
  \verbinclude restypedef.cpp
  \htmlonly
  Click <a href="$(DOXYGEN_DOCDIR)/examples/restypedef/html/restypedef_8cpp.html">here</a> 
  for the corresponding HTML documentation that is generated by Doxygen.
  \endhtmlonly
*/