|
|
              
Text MarkupThe text formatting commands indicate how text is to be rendered. \a (parameter marker)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. / *! Constructs a line edit containing the text \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:
You can enclose the formal parameter name in curly brackets, if you want to, but it isn't necessary. \c (code font)The \c command is used for rendering variable names, user-defined class names, and C++ keywords (e.g. int and for) in the code font. The command renders its argument using a typewriter 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:
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:
The \c command accepts the special character \ within its argument, i.e. it renders it as a normal character. So if you want to use nested commands, you must use the teletype (\tt) command instead. \divThe \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 ultimately 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 } If qdoc is generating DITA XML, it will translate the commands to: <sectiondiv outputclass="float-right"> <p> <fig> <image href="images/qml-column.png" placement="inline"/> </fig> </p> </sectiondiv> Your DITA XML publishing program must then recognize the outputclass attribute value. Note: The \div command can be nested. Below is 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 Guides} {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 4.7 documentation, the above example is rendered as: Qt Developer Guide When generating DITA XML, qdoc outputs the nested div commands as: <sectiondiv outputclass="indexbox guide"> <sectiondiv outputclass="heading"> <p>Qt Developer Guide</p> </sectiondiv> <sectiondiv outputclass="indexboxcont indexboxbar"> <sectiondiv outputclass="section indexIcon"/> <sectiondiv outputclass="section"> <p>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. </p> </sectiondiv> <sectiondiv outputclass="section sectionlist"> <ul> <li> <xref href="gettingstarted.xml#id-606ee7a8-219b-47b7-8f94-91bc8c76e54c">Getting started</xref> </li> <li> <xref href="installation.xml#id-075c20e2-aa1e-4f88-a316-a46517e50443">Installation</xref> </li> <li> <xref href="how-to-learn-qt.xml#id-49f509b5-52f9-4cd9-9921-74217b9a5182">How to learn Qt</xref> </li> <li> <xref href="tutorials.xml#id-a737f955-a904-455f-b4aa-0dc69ed5a64f">Tutorials</xref> </li> <li> <xref href="all-examples.xml#id-98d95159-d65b-4706-b08f-13d80080448d">Examples</xref> </li> <li> <xref href="qt4-7-intro.xml#id-519ae0e3-4242-4c2a-b2be-e05d1e95f177">What's new in Qt 4.7</xref> </li> </ul> </sectiondiv> </sectiondiv> </sectiondiv> Your DITA XML publishing program must recognize the values of the outputclass attribute. See also \span. \spanThe \span command is for applying special formatting attributes to a small block of text. Two arguments must be provided, each argument in curly braces, as shown in the qdoc comment below. The first argument is not interpreted but is used as the formatting attribute(s) of the tag that is ultimately output by qdoc. The second argument is the text to be rendered with the special formatting attributes. For example, we might want to render the first word of each element in a numeric list in blue. / *! Global variables with complex types: \list 1 \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14 \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15 \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16 \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17 \endlist * / Class variableName refers to a clause in your style.css. .variableName { font-family: courier; color: blue } Using the variableName clause shown above, the example is rendered as: Global variables with complex types:
Note: The span command does not cause a new paragraph to be started. See also \div. \tt (teletype font)The \tt command renders its argument in a monospace font. This command behaves just like the \c command, except that \tt allows you to nest QDoc commands within the argument (e.g. \e, \b and \underline). / *! After \c setupUi() populates the main container with child widgets it scans the main container's list of slots for names with the form \tt{on_\e{objectName}_\e{signalName}().} * / QDoc renders this as:
If the text to be rendered in the code font contains spaces, enclose the entire text in curly brackets. \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
QDoc renders this as:
See also \c. \bThe \b command renders its argument in bold font. This command used to be called \bold. / *! This is regular text; \b {this text is rendered using the \\b command}. * / QDoc renders this as:
\e (emphasis, italics) (new 5/3/2012)The \e command renders its argument in a special font, normally italics. This command used to be called \i, which is now deprecated. Use for italics. If the argument contains spaces or other punctuation, enclose the argument in curly brackets. / *! Here, we render \e {a few words} in italic. * / QDoc renders this as:
If you want to use other QDoc commands within an argument that contains spaces, you always need to enclose the argument in braces. But QDoc is smart enough to count parentheses [3], so you don't need braces in cases like this: / *! An argument can sometimes contain whitespaces, for example: \e QPushButton(tr("A Brand New Button")) * / QDoc renders this as:
Finally, trailing punctuation is not included in an argument [4], nor is 's [5]
\subThe \sub command renders its argument lower than the baseline of the regular text, using a smaller font. / *! Definition (Range): Consider the sequence {x\sub n}\sub {n > 1} . The set {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} is called the range of the sequence. * / QDoc renders this as:
If the argument contains spaces or other punctuation, enclose the argument in curly brackets. \supThe \sup command renders its argument higher than the baseline of the regular text, using a smaller font. / *! The series 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... is called the \i {geometric series}. * / QDoc renders this as:
If the argument contains spaces or other punctuation, enclose the argument in curly brackets. \uicontrolThe \uicontrol command is used to mark content as being used for UI control elements. When using HTML the output is rendered in bold. When using DITA XML the content is enclosed in a uicontrol tag. \underlineThe \underline command renders its argument underlined. / *! The \underline {F}ile menu gives the users the possibility to open, and edit, an existing file, save a new or modified file, and exit the application. * / QDoc renders this as:
If the argument contains spaces or other punctuation, enclose the argument in curly brackets. \\ (double backslash)The \\ command expands to a single backslash. QDoc commands always start with a backslash alone. To display an actual backslash in the text you need to type two of the kind. If you want to display two backslashes, you need to type four, and so forth. / *! The \\\\ command is useful if you want a backslash to appear verbatim, for example, writing C:\\windows\\home\\. * / QDoc renders this as:
However, if you want your text to appear in a typewriter font as well, you can use the \c command instead, which accepts and renders the backslash as any other character. For example: / *! The \\c command is useful if you want a backslash to appear verbatim, and the word that contains it written in a typewriter font, like this: \c {C:\windows\home\}. * / QDoc renders this as:
See also \b. |
