The text formatting commands indicate how text is to be rendered.
The \a command tells QDoc the next word is a formal parameter name.
A warning is emitted when a formal parameter is not documented or is misspelled, so when you document a function you should mention each formal parameter by name in the function description, preceded by the \a command. The parameter name is then rendered in italics.
/ *! 构造行编辑包含文本 \a contents. The \a parent parameter is sent to the QWidget constructor. * / QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent) { ... }
QDoc renders this as:
QLineEdit::QLineEdit ( const QString & contents, QWidget *parent )
构造行编辑包含文本 contents 。 parent parameter is sent to the QWidget 构造函数。
The formal parameter name may be enclosed between curly brackets, but that isn't required.
The \c command is used for rendering variable names, user-defined class names, and C++ keywords (for example,
int
and
for
) in the code font.
The command renders its argument using a monospace font. For example:
/ *! The \c AnalogClock class provides a clock widget with hour and minute hands that is automatically updated every few seconds. * /
QDoc renders this as:
AnalogClock
class provides a clock widget with hour and minute hands, which are automatically updated every few seconds.
If the text to be rendered in the code font contains spaces, enclose the entire text in curly brackets.
\c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
QDoc renders this as:
QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)
The \c command accepts the special character
\
within its argument, which renders it as a normal character. So if you want to use nested commands, you must use the
teletype (\tt)
command instead.
The \div and \enddiv commands delimit a large or small block of text (which may include other QDoc commands) to which special formatting attributes should be applied.
An argument must be provided in curly braces, as in the QDoc comment shown below. The argument is not interpreted but is used as attribute(s) of the tag that is output by QDoc.
For example, we might want to render an inline image so that it floats to the right of the current block of text:
/ *! \div {class="float-right"} \inlineimage qml-column.png \enddiv * /
If QDoc is generating HTML, it will translate these commands to:
<div class="float-right"><p><img src="images/qml-column.png" /></p></div>
For HTML, the attribute value float-right then will refer to a clause in the style.css file, which in this case could be:
div.float-right { float: right; margin-left: 2em }
注意： 注意， \div command can be nested.
Below you can find an example taken from the index.qdoc file used to generate index.html for Qt 4.7:
\div {class="indexbox guide"}
\div {class="heading"}
Qt Developer Guide
\enddiv
\div {class="indexboxcont indexboxbar"}
\div {class="section indexIcon"} \emptyspan
\enddiv
\div {class="section"}
Qt is a cross-platform application and UI
framework. Using Qt, you can write web-enabled
applications once and deploy them across desktop,
mobile and embedded operating systems without
rewriting the source code.
\enddiv
\div {class="section sectionlist"}
\list
\li \l{Getting Started}
\li \l{Installation} {Installation}
\li \l{how-to-learn-qt.html} {How to learn Qt}
\li \l{tutorials.html} {Tutorials}
\li \l{Qt Examples} {Examples}
\li \l{qt4-7-intro.html} {What's new in Qt 4.7}
\endlist
\enddiv
\enddiv
\enddiv
When all the class attribute values are defined as they are in the style.css file that is used for rendering the Qt documentation, the above example is rendered as:
Qt Developer Guide