|
|
              
Creating LinksThese commands are for creating hyperlinks to classes, functions, examples, and other targets. \l (link)The \l link command is used to create a hyperlink to many different kinds of targets. The command's general syntax is: \l {link target} {link text}
/ *! Read the \l {http://qt.nokia.com/doc/4.0/} {Qt's Reference Documentation} carefully. * / QDoc renders this as:
If the link target is equivalent to the link text, the second argument can be omitted. For example, if you have documentation like: / *! \target assertions Assertions make some statement about the text at the point where they occur in the regexp but they do not match any characters. ... Regexps are built up from expressions, quantifiers, and \l {assertions} {assertions}. * / You can simplify this as follows: / *! \target assertions Assertions make some statement about the text at the point where they occur in the regexp but they do not match any characters. ... Regexps are built up from expressions, quantifiers, and \l assertions. * / For the one-parameter version the braces can often be omitted. The \l command supports several kinds of links:
QDoc also tries to make a link out of any words that don't resemble any normal English words, for example Qt class names or functions, like QWidget or QWidget::sizeHint(). In these cases, the \l command can actually be omitted, but by using the command, you ensure that QDoc will emit a warning if it cannot find the link target. In addition, if you only want the function name to appear in the link, you can use the following syntax:
QDoc renders this as: See also \sa, \target and \keyword. \sa (see also)The \sa command defines a list of links that will be rendered in a separate "See also" section at the bottom of the documentation unit. The command takes a comma-separated list of links as its argument. If the line ends with a comma, you can continue the list on the next line. The general syntax is: \sa {the first link}, {the second link},
{the third link}, ...
QDoc will automatically try to generate "See also" links interconnecting a property's various functions. For example, a setVisible() function will automatically get a link to visible() and vice versa. In general, QDoc will generate "See also" links that interconnect the functions that access the same property. It recognizes four different syntax versions:
The \sa command supports the same kind of links as the \l command. / *! Appends the actions \a actions to this widget's list of actions. \sa removeAction(), QMenu, addAction() * / void QWidget::addActions(QList<QAction *> actions) { ... } QDoc renders this as:
See also \l, \target and \keyword. \targetThe \target command names a place in the documentation that you can link to using the \l (link) and \sa (see also) commands. The text up to the line break becomes the target name. Be sure to follow the target name with a line break. Curly brackets are not required around the target name, but they may be required when the target name is used in a link cammand. See below. / *! \target capturing parentheses \section1 Capturing Text Parentheses allow us to group elements together so that we can quantify and capture them. ... * / The target name capturing parentheses can be linked from within the same document containing the target in two ways:
Note: The brackets in the link example are required because the target name contains spaces. From other documents, the target name can be linked this way:
See also \l, \sa and \keyword. \keywordThe \keyword command names a place in the documentation that you can link to using the \l (link) and \sa (see also) commands. The \keyword command is like the \target command, but stronger. A keyword can be linked from anywhere using a simple syntax. Keywords must be unique over all the documents processed during the QDoc run. The command uses the rest of the line as its argument. Be sure to follow the keyword with a line break. / *! \class QRegExp \reentrant \brief The QRegExp class provides pattern matching using regular expressions. \ingroup tools \ingroup misc \ingroup shared \mainclass \keyword regular expression Regular expressions, or "regexps", provide a way to find patterns within text. ... * / The location marked with the keyword can be linked with: / *! When a string is surrounded by slashes, it is interpreted as a \l {regular expression}. * / QDoc renders this as:
If the keyword text contains spaces, the brackets are required. See also \l (link), \sa (see also) and \target. |
