summaryrefslogtreecommitdiffstats
path: root/tools
diff options
context:
space:
mode:
authorMartin Smith <martin.smith@nokia.com>2011-03-01 12:44:24 (GMT)
committerMartin Smith <martin.smith@nokia.com>2011-03-01 12:44:24 (GMT)
commitc8c11c9eb265b5050e530279c13252de9a9971d3 (patch)
treeb556900c57827a48a2b5bb632a5b4bd6a9ca25e0 /tools
parentbc47cf8e2de94fae6b7c3971529a2088d0806701 (diff)
parent3dbb501a2a13786142c3b16ef4b50c101285e619 (diff)
downloadQt-c8c11c9eb265b5050e530279c13252de9a9971d3.zip
Qt-c8c11c9eb265b5050e530279c13252de9a9971d3.tar.gz
Qt-c8c11c9eb265b5050e530279c13252de9a9971d3.tar.bz2
Merge branch 'mimir' into 4.7
Diffstat (limited to 'tools')
-rw-r--r--tools/qdoc3/doc/qdoc-manual.qdoc3328
-rw-r--r--tools/qdoc3/htmlgenerator.cpp6
2 files changed, 1739 insertions, 1595 deletions
diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc
index 4a395e0..712dcea 100644
--- a/tools/qdoc3/doc/qdoc-manual.qdoc
+++ b/tools/qdoc3/doc/qdoc-manual.qdoc
@@ -33,31 +33,29 @@
\list
\o \l {Introduction to QDoc}
- \o \l {The QDoc Commands}
+ \o \l {Command Index}
+ \o \l {Topic Commands}
+ \o \l {Context Commands}
\list
- \o \l {Topic Commands}
- \o \l {Context Commands}
- \list
- \o \l {Document Navigation}
- \o \l {Reporting Status}
- \o \l {Thread Support}
- \o \l {Relating Things}
- \o \l {Grouping Things}
- \o \l {Naming Things}
- \endlist
- \o \l{Markup Commands}
- \list
- \o \l {Text Markup} \span {class="newStuff"} {(new: div & span)}
- \o \l {Document Structure}
- \o \l {Including Code Inline}
- \o \l {Including External Code}
- \o \l {Creating Links}
- \o \l {Including Images}
- \o \l {Tables and Lists}
- \o \l {Special Content}
- \o \l {Miscellaneous}
- \endlist
- \endlist
+ \o \l {Document Navigation}
+ \o \l {Reporting Status}
+ \o \l {Thread Support}
+ \o \l {Relating Things}
+ \o \l {Grouping Things}
+ \o \l {Naming Things}
+ \endlist
+ \o \l{Markup Commands}
+ \list
+ \o \l {Text Markup}
+ \o \l {Document Structure}
+ \o \l {Including Code Inline}
+ \o \l {Including External Code}
+ \o \l {Creating Links}
+ \o \l {Including Images}
+ \o \l {Tables and Lists}
+ \o \l {Special Content}
+ \o \l {Miscellaneous}
+ \endlist
\o \l {The QDoc Configuration File}
\list
\o \l {General Configuration Variables}
@@ -77,7 +75,7 @@
\page 01-qdoc-manual.html
\contentspage Table of Contents
\previouspage Table of Contents
- \nextpage The QDoc Commands
+ \nextpage Command Index
\title Introduction to QDoc
@@ -127,7 +125,7 @@
\endcode
From this snippet, QDoc generates the now famous HTML page \l
- {http://doc.trolltech.com/4.7/qobject.html} {QObject Class Reference}.
+ {http://doc.trolltech.com/4.7/qobject.html#details} {QObject Class Reference}.
This manual explains how to use the QDoc commands to write useful
qdoc comments in your source files. It also explains how to create
@@ -190,7 +188,6 @@
appearance and logical structure.
\list
- \o \l {04-qdoc-commands-textmarkup.html#backslash-command} {\\\\}
\o \l {04-qdoc-commands-textmarkup.html#a-command} {\\a}
\o \l {11-qdoc-commands-specialcontent.html#abstract-command} {\\abstract}
\o \l {06-qdoc-commands-includecodeinline.html#badcode-command} {\\badcode}
@@ -230,7 +227,7 @@
\o \l {11-qdoc-commands-specialcontent.html#quotation-command} {\\quotation}
\o \l {07-0-qdoc-commands-includingexternalcode.html#quotefile-command} {\\quotefile}
\o \l {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} {\\quotefromfile}
- \o \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\raw} \span {class="newStuff"} {(avoid)}
+ \o \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\raw} \span {class="newStuff"} {(deprecated)}
\o \l {10-qdoc-commands-tablesandlists.html#row-command} {\\row}
\o \l {08-qdoc-commands-creatinglinks.html#sa-command} {\\sa}
\o \l {05-qdoc-commands-documentstructure.html#sectionOne-command} {\\section1}
@@ -251,8 +248,8 @@
\o \l {04-qdoc-commands-textmarkup.html#underline-command} {\\underline}
\o \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\unicode}
\o \l {11-qdoc-commands-specialcontent.html#warning-command} {\\warning}
+ \o \l {04-qdoc-commands-textmarkup.html#backslash-command} {\\\\}
\endlist
-
*/
/*!
@@ -274,7 +271,7 @@
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. For example:
+ in italics.
\code
/ *!
@@ -616,8 +613,6 @@
The \\bold command renders its argument in bold font.
- For example:
-
\code
/ *!
This is regular text; \bold {this text is
@@ -737,8 +732,6 @@
The \\sub command renders its argument lower than the baseline of
the regular text, using a smaller font.
- For example:
-
\code
/ *!
Definition (Range): Consider the sequence
@@ -770,8 +763,6 @@
The \\sup command renders its argument higher than
the baseline of the regular text, using a smaller font.
- For example:
-
\code
/ *!
The series
@@ -800,8 +791,6 @@
The \\underline command renders its argument underlined.
- For example:
-
\code
/ *!
The \underline {F}ile menu gives the users the possibility
@@ -829,7 +818,7 @@
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. For example:
+ forth.
\code
/ *!
@@ -926,7 +915,7 @@
example from \c part to \c section1, is not allowed.
You can \e begin with either of the three: \c part, \c chapter or
- \c section1. For example:
+ \c section1.
\code
@@ -1138,8 +1127,6 @@
{quotefromfile-command} {\\quotefromfile} or \l
{quotefile-command} {\\quotefile} command.
- For example:
-
\code
/ *!
\code
@@ -1182,7 +1169,6 @@
{newcode-command} {\\newcode} and \l {oldcode-command}
{\\oldcode}.
-
\target badcode-command
\section1 \\badcode
@@ -1195,7 +1181,7 @@
Like the \l {code-command} {\\code} command, this command begins
its code snippet on a new line rendered in the code font and with
- the standard indentation. For example:
+ the standard indentation.
\code
/ *!
@@ -1255,7 +1241,7 @@
Like the \l {code-command} {\\code} and \l {badcode-command}
{\\badcode} commands, the \\newcode command renders its code on a
new line in the documentation using a typewriter font and the
- standard indentation. For example:
+ standard indentation.
\code
/ *!
@@ -1294,6 +1280,53 @@
and emits a warning.
See also \l {newcode-command} {\\newcode} and \l {badcode-command} {\\badcode}.
+
+ \target qml-command
+ \section1 \\qml \span {class="newStuff"} {(new)}
+
+ The \\qml and \\endqml commands enclose a snippet of QML source
+ code. Currently, QDoc handles \\qml and \\endqml exactly the same
+ as \\code and \\endcode.
+
+ \code
+ / *!
+ \qml
+ import QtQuick 1.0
+
+ Row {
+ Rectangle {
+ width: 100; height: 100
+ color: "blue"
+ transform: Translate { y: 20 }
+ }
+ Rectangle {
+ width: 100; height: 100
+ color: "red"
+ transform: Translate { y: -20 }
+ }
+ }
+ \endqml
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \qml
+ import QtQuick 1.0
+
+ Row {
+ Rectangle {
+ width: 100; height: 100
+ color: "blue"
+ transform: Translate { y: 20 }
+ }
+ Rectangle {
+ width: 100; height: 100
+ color: "red"
+ transform: Translate { y: -20 }
+ }
+ }
+ \endqml
*/
/*!
@@ -1331,7 +1364,7 @@
The file's contents is rendered in a separate paragraph, using a
typewriter font and the standard indentation. The code is shown
- verbatim. For example:
+ verbatim.
\code
/ *!
@@ -1377,7 +1410,7 @@
{\\printuntil}, \l {skipline-command} {\\skipline}, \l
{skipto-command} {\\skipto}, \l {skipuntil-command}
{\\skipuntil}. This enables you to quote specific portions of a
- file. For example:
+ file.
\code
/ *!
@@ -1453,7 +1486,7 @@
The line from the source file is rendered as a separate paragraph,
using a typewriter font and the standard indentation. The code is
- shown verbatim. For example:
+ shown verbatim.
\code
/ *!
@@ -1521,7 +1554,7 @@
\target substring
If the substring argument is surrounded by slashes it is
- interpreted as a \l {regular expression}. For example:
+ interpreted as a \l {regular expression}.
\code
/ *!
@@ -1582,7 +1615,7 @@
The lines from the source file are rendered in a separate
paragraph, using a typewriter font and the standard
- indentation. The code is shown verbatim. For example:
+ indentation. The code is shown verbatim.
\code
/ *!
@@ -1631,7 +1664,7 @@
The lines from the source file are rendered in a separate
paragraph, using a typewriter font and the standard
- indentation. The code is shown verbatim. For example:
+ indentation. The code is shown verbatim.
\code
/ *!
@@ -1685,7 +1718,7 @@
command also follows the same conventions for \l {substring}
{argument} as the \l {printline-command} {\\printline} command,
and it is used in conjunction with the \l {quotefromfile-command}
- {\\quotefromfile} command. For example:
+ {\\quotefromfile} command.
\code
/ *!
@@ -1744,7 +1777,7 @@
The command also follows the same conventions for \l {substring}
{argument} as the \l {printline-command} {\\printline} command,
and it is used in conjunction with the \l {quotefromfile-command}
- {\\quotefromfile} command. For example:
+ {\\quotefromfile} command.
\code
/ *!
@@ -1802,7 +1835,7 @@
The command also follows the same conventions for \l {substring}
{argument} as the \l {printline-command} {\\printline} command,
and it is used in conjunction with the \l {quotefromfile-command}
- {\\quotefromfile} command. For example:
+ {\\quotefromfile} command.
\code
/ *!
@@ -1850,7 +1883,7 @@
The command is used in conjunction with the \l
{quotefromfile-command} {\\quotefromfile} command, and should be
stated on its own line. The dots are rendered on a new line, using
- a typewriter font. For example:
+ a typewriter font.
\code
/ *!
@@ -1875,7 +1908,7 @@
(\l {Example File} {The complete example file...})
The default indentation is 4 spaces, but this can be adjusted
- using the command's optional argument. For example:
+ using the command's optional argument.
\code
/ *!
@@ -1967,14 +2000,12 @@
\section1 \\l (link)
The \\l link command is used to create a hyperlink to many
- different kinds of targets. The command's general syntax is
+ different kinds of targets. The command's general syntax is:
\code
\l {link target} {link text}
\endcode
- For example:
-
\code
/ *!
Read the \l {http://qt.nokia.com/doc/4.0/}
@@ -2118,7 +2149,7 @@
\endlist
The \\sa command supports the same kind of links as the \l
- {l-command} {\\l} command. For example:
+ {l-command} {\\l} command.
\code
/ *!
@@ -2162,8 +2193,6 @@
required around the target name, but they may be required when the
target name is used in a link cammand. See below.
- For example:
-
\code
/ *!
\target capturing parentheses
@@ -2205,7 +2234,7 @@
The \\keyword command is like the \l {target-command} {\\target}
command, but stronger. A keyword can be linked from anywhere using
- a simple syntax. For example:
+ 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
@@ -2289,8 +2318,6 @@
description with a line break. Curly brackets are required if the
description argument spans multiple lines.
- For example:
-
\code
/ *!
Qt by Trolltech is a C++ toolkit for cross-platform GUI
@@ -2396,7 +2423,7 @@
\endraw
The command can also be used to insert an image inline with the
- text. For example:
+ text.
\code
/ *!
@@ -2500,7 +2527,7 @@
\l {row-command} {\\row} command and consists of cells, which
starts with a \l {o-command} {\\o} command. There is also a \l
{header-command} {\\header} command which is a special kind of row
- with a special formatting. For example:
+ with a special formatting.
\code
/ *!
@@ -2629,7 +2656,7 @@
cells. A cell is created with the \l {o-command} {\\o} command.
A header cell's text is centered within the table cell and
- rendered using a bold font. For example:
+ rendered using a bold font.
\code
/ *!
@@ -2681,7 +2708,7 @@
The background cell color of each row alternates between two
shades of grey, making it easier to distinguish the rows from each
- other. The cells' contents is left aligned. For example:
+ other. The cells' contents is left aligned.
\code
/ *!
@@ -2824,7 +2851,7 @@
\endlist
The \\list command takes an optional argument providing
- alternative appearances for the list items. For example:
+ alternative appearances for the list items.
\code
/ *!
@@ -2931,7 +2958,7 @@
{list-command} {\\list}.
If the command is used within a table, you can in addition specify
- how many rows or columns the item should span. For example:
+ how many rows or columns the item should span.
\code
/ *!
@@ -3177,7 +3204,7 @@
\endcode
\warning The brief statement is used as the first paragraph of the
- detailed description. Do not repeat the sentence. For example:
+ detailed description. Do not repeat the sentence.
\code
/ *!
@@ -3400,7 +3427,7 @@
\section1 \\warning
The \\warning command prepends "Warning:" to the command's
- argument, in bold font. For example:
+ argument, in bold font.
\code
/ *!
@@ -3741,7 +3768,7 @@
the condition specified by the command's argument is true.
The command reads the rest of the line and parses it as an C++ #if
- statement. For example:
+ statement.
\code
/ *!
@@ -3795,7 +3822,7 @@
The \\else command can only be used within \l {if-command}
{\\if...\\endif} commands, but is useful when there is only two
- alternatives. For example:
+ alternatives.
\code
/ *!
@@ -3906,7 +3933,7 @@
the enclosing \c{/}\c{*!} ... \c{*}\c{/} marks. To ensure that
QDoc won't attempt to read the file as a stand-alone piece of
documentation, we recommend that you use the \c .qdocinc
- extension. For example:
+ extension.
\code
/ *!
@@ -3943,7 +3970,7 @@
The command accepts two arguments: The first argument (the
following word) is equivalent to the HTML meta tag's \e name
variable, and the second argument (the rest of the line) is
- equivalent to the tag's \e contents variable. For example:
+ equivalent to the tag's \e contents variable.
\code
/ *!
@@ -4042,11 +4069,11 @@
currently the only supported format is HTML.
The \\raw command is useful if you want some special HTML effects
- in your documentation. For example:
+ in your documentation.
\code
/ *!
- Qt has some predefined QColor objects. For example:
+ Qt has some predefined QColor objects.
\raw HTML
<style type="text/css" id="colorstyles">
@@ -4067,7 +4094,7 @@
QDoc renders this as:
\quotation
- Qt has some predefined QColor objects. For example:
+ Qt has some predefined QColor objects.
\raw HTML
<style type="text/css" id="colorstyles">
@@ -4162,7 +4189,7 @@
/*!
\page 13-qdoc-commands-topics.html
- \previouspage The QDoc Commands
+ \previouspage Command Index
\contentspage Table of Contents
\nextpage Context Commands
@@ -4172,8 +4199,6 @@
documented. Some topic commands allow you to create documentation
pages that aren't tied to any underlying source code element.
- \section1 General Description
-
When QDoc processes a QDoc comment, it tries to connect the
comment to an element in the source code by first looking for a
topic command that names the source code element. If there is no
@@ -4187,7 +4212,7 @@
The name of the thing being documented is the unique argument for
each topic command. The naming convention is to use the complete
- name. For example:
+ name.
\code
\enum QComboBox::InsertPolicy
@@ -4195,7 +4220,7 @@
The \l {fn-command} {\\fn} command is a special case. For the \l
{fn-command} {\\fn} command, use the function's signature
- including the class qualifier. For example:
+ including the class qualifier.
\code
\fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags)
@@ -4210,7 +4235,7 @@
')' as its argument.
If a topic command is repeated with different arguments, the
- same documentation will appear for both the units. For example:
+ same documentation will appear for both the units.
\code
/ *!
@@ -4543,6 +4568,54 @@
...
\endquotation
+ \target externalpage-command
+ \section1 \\externalpage
+
+ The \\externalpage command assigns a title to an external URL.
+
+ \code
+ / *!
+ \externalpage http://doc.trolltech.com/4.3/qtopiacore.html
+ \title Qtopia Core
+ * /
+ \endcode
+
+ This allows you to include a link to the external page in your
+ documentation this way:
+
+ \code
+ / *!
+ The broad scope of the \l {Qtopia Core} API enables it to
+ be used across a wide variety of development projects.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ The broad scope of the \l
+ {http://doc.trolltech.com/4.3/qtopiacore.html} {Qtopia
+ Core} API enables it to be used across a wide variety
+ of development projects.
+ \endquotation
+
+ To achieve the same result without using the \\externalpage
+ command, you would have to hard code the adress into your
+ documentation:
+
+ \code
+ / *!
+ The broad scope of the \l
+ {http://doc.trolltech.com/4.3/qtopiacore.html} {Qtopia
+ Core} API enables it to be used across a wide variety
+ of development projects.
+ * /
+ \endcode
+
+ The \\externalpage command makes it easier to maintain the
+ documentation. If the adress changes, you only need to change the
+ argument of the \\externalpage command.
+
\target fn-command
\section1 \\fn (function)
@@ -4559,7 +4632,7 @@
function's QDoc comment is written immediately above the function
implementation in the \c .cpp file. But it must be present when
documenting an inline function in the \c .cpp file that is
- implemented in the \c .h file. For example:
+ implemented in the \c .h file.
\code
/ *!
@@ -4603,7 +4676,7 @@
Each class name is listed as a link to the class reference page
followed by the text from the class's \l {brief-command} {\\brief}
- texts. For example:
+ texts.
\code
/ *!
@@ -4660,7 +4733,7 @@
Note that overview pages related to the group, must be listed
explicitly using the \l {generatelist-command} {\\generatelist}
- command with the \c related argument. For example:
+ command with the \c related argument.
\code
/ *!
@@ -4694,7 +4767,6 @@
If the argument doesn't exist as a header file, the \\headerfile
command creates a documentation page for the header file anyway.
- For example:
\code
/ *!
@@ -4951,7 +5023,7 @@
The \\namespace command is for documenting the contents of the C++
namespace named as its argument. The documentation outline QDoc
generates for a namespace is similar to the outline it generates
- for a C++ class. For example:
+ for a C++ class.
\code
/ *!
@@ -5005,7 +5077,7 @@
The \\page command is for creating a stand-alone documentation
page. The argument is the name of the file where QDoc should
store the page. The page title is set using the \l {title-command}
- {\\title} command. For example:
+ {\\title} command.
\code
/ *!
@@ -5032,55 +5104,6 @@
QDoc renders this page in \c {aboutqt.html}.
- \target externalpage-command
- \section1 \\externalpage
-
- The \\externalpage command assigns a title to an external URL.
- For example:
-
- \code
- / *!
- \externalpage http://doc.trolltech.com/4.3/qtopiacore.html
- \title Qtopia Core
- * /
- \endcode
-
- This allows you to include a link to the external page in your
- documentation this way:
-
- \code
- / *!
- The broad scope of the \l {Qtopia Core} API enables it to
- be used across a wide variety of development projects.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The broad scope of the \l
- {http://doc.trolltech.com/4.3/qtopiacore.html} {Qtopia
- Core} API enables it to be used across a wide variety
- of development projects.
- \endquotation
-
- To achieve the same result without using the \\externalpage
- command, you would have to hard code the adress into your
- documentation:
-
- \code
- / *!
- The broad scope of the \l
- {http://doc.trolltech.com/4.3/qtopiacore.html} {Qtopia
- Core} API enables it to be used across a wide variety
- of development projects.
- * /
- \endcode
-
- The \\externalpage command makes it easier to maintain the
- documentation. If the adress changes, you only need to change the
- argument of the \\externalpage command.
-
\target property-command
\section1 \\property
@@ -5089,7 +5112,7 @@
A property is defined using the Q_PROPERTY() macro. The macro
takes as arguments the property's name and its set, reset and get
- functions. For example:
+ functions.
\code
Q_PROPERTY(QString state READ state WRITE setState)
@@ -5107,7 +5130,7 @@
fragment that will be included in a one line description of the
property. The command follows the same rules for the \l
{brief-property} {description} as the \l {variable-command}
- {\\variable} command. For example:
+ {\\variable} command.
\code
/ *!
@@ -5195,6 +5218,226 @@
See also \l {class-command} {\\class} and \l
{generatelist-command} {\\generatelist}.
+ \target qmlattachedproperty-command
+ \section1 \\qmlattachedproperty \span {class="newStuff"} {(new)}
+
+ The \\qmlattachedproperty command is for documenting a QML
+ property that will be attached to some QML element type. See
+ \l{http://doc.trolltech.com/4.7/qdeclarativeintroduction.html#attached-properties}
+ {Attached Properties}. The argument is the rest of the line. The
+ argument text should be the property type, followed by the QML
+ element name where the property is being declared, the \c{::}
+ qualifier, and finally the property name. If we have a QML
+ attached property named \c isCurrentItem in QML element \c ListView,
+ and the property has type \c {bool}, the \\qmlattachedproperty for
+ it would look like this:
+
+ \code
+ / *!
+ \qmlattachedproperty bool ListView::isCurrentItem
+ This attached property is true if this delegate is the current
+ item; otherwise false.
+
+ It is attached to each instance of the delegate.
+
+ This property may be used to adjust the appearance of the current
+ item, for example:
+
+ \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem
+ * /
+ \endcode
+
+ QDoc includes this attached property on the QML reference page for the
+ \l{http://doc.trolltech.com/4.7/qml-listview.html#isCurrentItem-prop}
+ {ListView} element.
+
+ \target qmlattachedsignal-command
+ \section1 \\qmlattachedsignal \span {class="newStuff"} {(new)}
+
+ The \\qmlattachedsignal command is for documenting an attachable
+ \l{http://doc.trolltech.com/4.7/qdeclarativeintroduction.html#signal-handlers}
+ {signal handler}. The \\qmlattachedsignal command is used just like
+ the \l{qmlsignal-command} {\\qmlsignal} command.
+
+ The argument is the rest of the line. It should be the name of the
+ QML element where the signal handler is declared, the \c{::}
+ qualifier, and finally the signal handler name. If we have a QML
+ attached signal handler named \c onAdd() in the \c GridView
+ element, the \\qmlattachedsignal for it would look like this:
+
+ \code
+ / *!
+ \qmlattachedsignal GridView::onAdd()
+ This attached handler is called immediately after an item is
+ added to the view.
+ * /
+ \endcode
+
+ QDoc includes this documentation on the QML reference page for the
+ \l{http://doc.trolltech.com/4.7/qml-gridview.html#onAdd-signal}
+ {GridView} element.
+
+ \target qmlbasictype-command
+ \section1 \\qmlbasictype \span {class="newStuff"} {(new)}
+
+ The \\qmlbasictype command is for documenting a basic type for QML.
+ The argument is the type name. The type must be included in the
+ QML basic types group using the \l{ingroup-command}{\\ingroup}
+ command as shown below. This will cause QDoc to include the
+ documentation for the type on the
+ \l{http://doc.trolltech.com/4.7/qdeclarativebasictypes.html}
+ {QML Basic Types} page. The \l{brief-command} {\\brief} command
+ is also required, because it appears on the
+ \l{http://doc.trolltech.com/4.7/qdeclarativebasictypes.html}
+ {QML Basic Types} page as well.
+
+ \code
+ / *!
+ \qmlbasictype int
+ \ingroup qmlbasictypes
+
+ \brief An integer is a whole number, e.g. 0, 10, or -20.
+
+ An integer is a whole number, e.g. 0, 10, or -20. The possible
+ \c int values range from around -2000000000 to around
+ 2000000000, although most elements will only accept a reduced
+ range (which they mention in their documentation).
+
+ Example:
+ \qml
+ Item { width: 100; height: 200 }
+ \endqml
+
+ \sa {QML Basic Types}
+ * /
+ \endcode
+
+ QDoc outputs this as \l{http://doc.trolltech.com/4.7/qml-int.html}
+ {qml-int.html}.
+
+ \target qmlclass-command
+ \section1 \\qmlclass \span {class="newStuff"} {(new)}
+
+ The \\qmlclass command is for documenting a QML element that is
+ instantiated by a C++ class. The command has two arguments. The
+ first argument is the name of the QML element. The second argument
+ is the name of the C++ class that instantiates the QML element.
+
+ \code
+ / *!
+ \qmlclass Transform QGraphicsTransform
+ \ingroup qml-transform-elements
+ \since 4.7
+ \brief The Transform elements provide a way of building
+ advanced transformations on Items.
+
+ The Transform element is a base type which cannot be
+ instantiated directly. The following concrete Transform types
+ are available:
+
+ \list
+ \o \l Rotation
+ \o \l Scale
+ \o \l Translate
+ \endlist
+
+ The Transform elements let you create and control advanced
+ transformations that can be configured independently using
+ specialized properties.
+
+ You can assign any number of Transform elements to an \l
+ Item. Each Transform is applied in order, one at a time.
+
+ * /
+ \endcode
+
+ This example generates the
+ \l {http://doc.trolltech.com/4.7/qml-transform.html} {QML Trasform
+ Element} page. The \\qmlclass comment should include the \l
+ {since-command} {\\since} command, because all QML elements are
+ new. It should also include the \l{brief-command} {\\brief}
+ command. And since every QML element is a member of a group of QML
+ elements, it should also include one or more \l{ingroup-command}
+ {\\ingroup} commands.
+
+ \target qmlmethod-command
+ \section1 \\qmlmethod \span {class="newStuff"} {(new)}
+
+ The \\qmlmethod command is for documenting a QML method. The
+ argument is the complete method signature, including return
+ type and parameter names and types.
+
+ \code
+ / *!
+ \qmlmethod void TextInput::select(int start, int end)
+
+ Causes the text from \a start to \a end to be selected.
+
+ If either start or end is out of range, the selection is not changed.
+
+ After calling this, selectionStart will become the lesser and
+ selectionEnd will become the greater (regardless of the order
+ passed to this method).
+
+ \sa selectionStart, selectionEnd
+ * /
+ \endcode
+
+ QDoc includes this documentation on the element refence page for the
+ \l{http://doc.trolltech.com/4.7/qml-textinput.html#select-method}
+ {TextInput} element.
+
+ \target qmlproperty-command
+ \section1 \\qmlproperty \span {class="newStuff"} {(new)}
+
+ The \\qmlproperty command is for documenting a QML property. The
+ argument is the rest of the line. The argument text should be the
+ property type, followed by the QML element name, the \c{::}
+ qualifier, and finally the property name. If we have a QML
+ property named \c x in QML element \c Translate, and the property
+ has type \c {real}, the \\qmlproperty for it would look like this:
+
+ \code
+ / *!
+ \qmlproperty real Translate::x
+
+ The translation along the X axis.
+ * /
+ \endcode
+
+ QDoc includes this QML property on the QML reference page for the
+ \l {http://doc.trolltech.com/4.7/qml-translate.html} {Translate}
+ element.
+
+ \target qmlsignal-command
+ \section1 \\qmlsignal \span {class="newStuff"} {(new)}
+
+ The \\qmlsignal command is for documenting a
+ \l{http://doc.trolltech.com/4.7/qdeclarativeintroduction.html#signal-handlers}
+ {signal handler}.
+ The argument is the rest of the line. It should be the QML element where the
+ signal handler is declared, the \c{::} qualifier, and finally the signal
+ handler name. If we have a QML signal handler named \c onAdd() in QML
+ element \c MouseArea, the \\qmlsignal for it would look like this:
+
+ \code
+ / *!
+ \qmlsignal MouseArea::onEntered()
+
+ This handler is called when the mouse enters the mouse area.
+
+ By default the onEntered handler is only called while a button is
+ pressed. Setting hoverEnabled to true enables handling of
+ onEntered when no mouse button is pressed.
+
+ \sa hoverEnabled
+ * /
+ \endcode
+
+ QDoc includes this documentation on the QML reference page for the
+ \l{http://doc.trolltech.com/4.7/qml-mousearea.html#onEntered-signal}
+ {MouseArea} element.
+
\target typedef-command
\section1 \\typedef
@@ -5204,7 +5447,7 @@
for the class, namespace, or header file in which the typedef
is declared. To relat the \\typedef to a class, namespace, or
header file, the \\typedef comment must contain a
- \l {relates-command} {\\relates} command. For example:
+ \l {relates-command} {\\relates} command.
\code
/ *!
@@ -5263,7 +5506,7 @@
\endquotation
Other typedefs are located on the reference page for the class
- that defines them. For example:
+ that defines them.
\code
/ *!
@@ -5392,18 +5635,34 @@
documented that QDoc can't deduce on its own. e.g. Is a class
thread-safe? Is a function reentrant? Which module is the class a
member of? Context commands can appear anywhere in a QDoc comment,
- but we put them at the top of the comment, right below the \l
- {Topic Commands} {topic} command.
+ but they are normally placed near the top of the comment, just
+ below the \l {Topic Commands} {topic} command.
- \section1 Categories
\list
- \o \l {Document Navigation}
- \o \l {Reporting Status}
- \o \l {Thread Support}
- \o \l {Relating Things}
- \o \l {Grouping Things}
- \o \l {Naming Things}
+ \o \l {16-qdoc-commands-status.html#compat-command}{\\compat},
+ \o \l {15-qdoc-commands-navigation.html#contentspage-command}{\\contentspage},
+ \o \l {15-qdoc-commands-navigation.html#indexpage-command}{\\indexpage},
+ \o \l {19-qdoc-commands-grouping.html#ingroup-command}{\\ingroup},
+ \o \l {18-qdoc-commands-relating.html#inherits-command}{\\inherits},
+ \o \l {19-qdoc-commands-grouping.html#inmodule-command}{\\inmodule},
+ \o \l {16-qdoc-commands-status.html#internal-command}{\\internal},
+ \o \l {19-qdoc-commands-grouping.html#mainclass-command}{\\mainclass},
+ \o \l {15-qdoc-commands-navigation.html#nextpage-command}{\\nextpage},
+ \o \l {17-qdoc-commands-thread.html#nonreentrant-command}{\\nonreentrant},
+ \o \l {16-qdoc-commands-status.html#obsolete-command}{\\obsolete},
+ \o \l {18-qdoc-commands-relating.html#overload-command}{\\overload},
+ \o \l {16-qdoc-commands-status.html#preliminary-command}{\\preliminary},
+ \o \l {15-qdoc-commands-navigation.html#previouspage-command}{\\previouspage},
+ \o \l {17-qdoc-commands-thread.html#reentrant-command}{\\reentrant},
+ \o \l {18-qdoc-commands-relating.html#reimp-command}{\\reimp},
+ \o \l {18-qdoc-commands-relating.html#relates-command}{\\relates},
+ \o \l {16-qdoc-commands-status.html#since-command}{\\since},
+ \o \l {15-qdoc-commands-navigation.html#startpage-command}{\\startpage},
+ \o \l {20-qdoc-commands-namingthings.html#subtitle-command}{\\subtitle}
+ \o \l {17-qdoc-commands-thread.html#threadsafe-command}{\\threadsafe},
+ \o \l {20-qdoc-commands-namingthings.html#title-command}{\\title}
\endlist
+
*/
/*!
@@ -5414,15 +5673,11 @@
\title Document Navigation
- The navigation commands allow you to link the pages of a multipage
- document together. They provide the components of a navigation bar
- at the top and bottom of the document. They also provide browser
- and search engine support.
+ The navigation commands are for linking the pages of a document in
+ a meaningful sequence. Below is a sequence of QDoc comments that
+ shows a typical use of the navigation commands.
- \section1 General Description
-
- The QDoc comments below show a typical way of using the navigation
- commands.
+ \section1 Example
\code
/ *!
@@ -5493,8 +5748,7 @@
* /
\endcode
- The second page of this multipage document, "Getting Started",
- QDoc renders this as:
+ QDoc renders the "Getting Started" page in \c{creatingdialogs.html}:
\quotation
\raw HTML
@@ -5529,18 +5783,16 @@
\endraw
\endquotation
- in creatingdialogs.html.
-
- In addition, the \l {indexpage-command} {\\indexpage} and \l
- {startpage-command} {\\startpage} commands specifies links to the page's
- index page and start page. These links are used by browsers and
- search engines.
+ The \l {indexpage-command} {\\indexpage} and \l
+ {startpage-command} {\\startpage} commands create links to the
+ page's index page and start page. These links can be used by
+ browsers and search engines.
The index page is typically an alphabetical list of the document's
titles and topics, while the start page is the page considered by
the author to be the starting point of a multipage document.
- The links are included in the generated HTML source code but has
+ The links are included in the generated HTML source code but have
no visual effect on the documentation:
\code
@@ -5552,85 +5804,61 @@
</head>
\endcode
- \target previouspage-command
- \section1 \\previouspage
-
- The \\previouspage command links the current page
- to the previous one in an ordered series of documents.
-
- The command has two arguments, each enclosed by curly
- braces: The first is the link target, i.e. the title of the
- previous page, the second is the link text. If the page's
- title is equivalent to the link text, the second argument
- can be omitted.
+ \section1 Commands
- The command must stand alone on its own line.
+ \target previouspage-command
+ \section2 \\previouspage
- In the end, the link is rendered at the top and bottom of
- the current page. For an example, see the \l {General
- Description} section.
+ The \\previouspage command links the current page to the previous
+ page in a sequence.a The command has two arguments, each enclosed
+ by curly braces: The first is the link target, i.e. the title of
+ the previous page, the second is the link text. If the page's
+ title is equivalent to the link text, the second argument can be
+ omitted.
+ The command must stand alone on its own line.
\target nextpage-command
- \section1 \\nextpage
-
- The \\nextpage command links the current
- page to the next page in an ordered series of documents.
-
- The command follows the same syntax and argument convention
- as the \l {previouspage-command} {\\previouspage} command.
-
- For an example, see the \l {General Description} section.
+ \section2 \\nextpage
+ The \\nextpage command links the current page to the next page in
+ a sequence. The command follows the same syntax and argument
+ convention as the \l {previouspage-command} {\\previouspage}
+ command.
\target startpage-command
- \section1 \\startpage
-
- The \\startpage command specifies the first document
- in a collection of documents.
-
- The command must stand alone on its own line, and its
- unique argument is the title of the first document.
-
- QDoc will generate a link to the specified document which
- is included in the HTML file but has no visual effect on
- the documentation. The generated link type tells browsers
- and search engines which document is considered by the
- author to be the starting point of the collection.
+ \section2 \\startpage
- For an example, see the \l {General Description} section.
+ The \\startpage command specifies the first page of a sequence of
+ pages. The command must stand alone on its own line, and its
+ unique argument is the title of the first document.
+ QDoc will generate a link to the start page and include it in the
+ generated HTML file, but this has no visual effect on the
+ documentation. The generated link type tells browsers and search
+ engines which document is considered by the author to be the
+ starting point of the collection.
\target contentspage-command
- \section1 \\contentspage
-
- The \\contentspage command links the current
- page to a contents page.
-
- The command follows the same syntax and argument convention
- as the \l {previouspage-command} {\\previouspage} command.
-
- For an example, see the \l {General Description} section.
+ \section2 \\contentspage
+ The \\contentspage command links the current page to a table of
+ contents page. The command follows the same syntax and argument
+ convention as the \l {previouspage-command} {\\previouspage}
+ command.
\target indexpage-command
- \section1 \\indexpage
-
- The \\indexpage command specifies a document providing
- an index for the current document.
-
- The command must stand alone on its own line, and its
- unique argument is the title of the index document.
-
- QDoc will generate a link to the specified document which
- is included in the HTML file but has no visual effect on
- the documentation. The generated link type tells browsers
- and search engines which document is considered by the
- author to be the index page for the current document.
-
- For an example, see the \l {General Description} section.
+ \section2 \\indexpage
+ The \\indexpage command specifies an index page for the current
+ document. The command must stand alone on its own line, and its
+ unique argument is the title of the index document.
+ QDoc will generate a link to the index page and include it in the
+ generated HTML file, but this has no visual effect on the
+ documentation. The generated link type tells browsers and search
+ engines which document is considered by the author to be the
+ index page of the collection.
*/
/*!
@@ -5641,244 +5869,251 @@
\title Reporting Status
- The usage commands can indicate whether a documented object is
- under development, becoming obsolete, provided for compatibility
- reasons or simply not part of the public interface. They can
- describe the history of minor versions. And they can also describe
- a documented object's ability to handle multithreaded programming.
-
- \target preliminary-command
- \section1 \\preliminary
-
- The \\preliminary command indicates that the
- referenced function is under development.
-
- The command must stand on its own line.
-
- The \\preliminary command expands to a notification in the
- function documentation, and marks the function as
- preliminary when it appears in lists. For example:
-
- \code
- / *!
- \preliminary
-
- Returns information about the joining properties of the
- character (needed for certain languages such as
- Arabic).
- * /
- QChar::Joining QChar::joining() const
- {
- return ::joining(*this);
- }
- \endcode
-
- QDoc renders this as:
+ These commands are for indicating that a documented element is
+ still under development, is becoming obsolete, is provided for
+ compatibility reasons, or is simply not to be included in the
+ public interface. The \l {since-command}{\\since} command is for
+ including information about the version when a function or class
+ first appeared.
- \quotation
- \raw HTML
- <h3>
- <a href="http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum">Joining</a>
- QChar::joining () const</h3>
- \endraw
+ \target compat-command
+ \section1 \\compat
- \bold {This function is under development and
- is subject to change.}
+ The \\compat command is for indicating that a class or function is
+ part of the support library provided to keep old source code
+ working.
- Returns information about the joining properties of the
- character (needed for certain languages such as
- Arabic).
- \endquotation
+ The command must stand on its own line.
- And the function's entry in QChar's list of functions will
- be rendered as
+ Usually an equivalent function or class is provided as an
+ alternative.
- \quotation
- \list
- \o ...
- \o Joining
- \l {http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum}
- {joining}()
- const \c (preliminary)
- \o ...
- \endlist
- \endquotation
+ If the command is used in the documentation of a class, the
+ command expands to a warning that the referenced class is part of
+ the support library. The warning is located at the top of the
+ documentation page.
+ \code
+ / *!
+ \class MyQt3SupportClass
+ \compat
+ * /
+ \endcode
- \target obsolete-command
- \section1 \\obsolete
+ QDoc renders this at the top of the MyQt3SupportClass class
+ reference page.
- The \\obsolete command indicates that the referenced
- function no longer should be used in new code;
- there is no guarantee for how long it will remain in
- the library.
+ \quotation
+ \bold {This class is part of the Qt 3 support
+ library.} It is provided to keep old source code
+ working. We strongly advise against using it in new
+ code. See the \l
+ {http://qt.nokia.com/doc/4.0/porting4.html} {Porting
+ Guide} for more information.
+ \endquotation
- The command must stand on its own line.
+ If the command is used when documenting a function, QDoc will
+ create and link to a separate page documenting Qt 3 support
+ members when generating the reference documentation for the
+ associated class.
- When generating the reference documentation for a class,
- QDoc will create and link to a separate page documenting
- its obsolete functions. Usually an equivalent function is
- provided as an alternative.
+ \code
+ / *!
+ \fn MyClass::MyQt3SupportMemberFunction
+ \compat
- For example:
+ Use MyNewFunction() instead.
+ * /
+ \endcode
- \code
- / *!
- \fn MyClass::MyObsoleteFunction
- \obsolete
+ QDoc renders this in \c{myclass-qt3.html} as:
- Use MyNewFunction() instead.
- * /
- \endcode
+ \quotation
+ \raw HTML
+ <h1>Qt 3 Support Members for MyClass</h1>
+ \endraw
- QDoc renders this as:
+ \bold {The following class members are part of the Qt 3
+ support layer.} They are provided to help you port old code to
+ Qt 4. We advise against using them in new code.
- \quotation
- \raw HTML
- <h1>Obsolete Members for MyClass</h1>
- \endraw
+ ...
- \bold {The following class members are obsolete.} They
- are provided to keep old source code working. We
- strongly advise against using them in new code.
+ \list
+ \o void MyQt3SupportMemberFunction()
+ \o ...
+ \endlist
- ...
+ \raw HTML
+ <hr />
+ <h2>Member Function Documentation</h2>
+ <h3>void MyQt3SupportMemberFunction ()</h3>
+ <p>Use MyNewFunction() instead.</p>
+ \endraw
+ ...
+ \endquotation
- \list
- \o void MyObsoleteFunction() \c (obsolete)
- \o ...
- \endlist
+ \target default-command
+ \section1 \\default \span {class="newStuff"} {(new)}
- \raw HTML
- <hr />
- <h2>Member Function Documentation</h2>
- <h3>void MyObsoleteFunction ()</h3>
- <p>Use MyNewFunction() instead.</p>
- \endraw
+ The \\default command is for marking a QML property as the
+ \l {http://doc.trolltech.com/4.7/qdeclarativeintroduction.html#default-properties}
+ {default property}. The word \span {class="newStuff"} {default} is shown in red in
+ the documentation of the property.
- ...
- \endquotation
+ \code
+ / *!
+ \qmlproperty list<Change> State::changes
+ This property holds the changes to apply for this state
+ \default
- in myclass-obsolete.html
+ By default these changes are applied against the default state. If the state
+ extends another state, then the changes are applied against the state being
+ extended.
+ * /
+ \endcode
+ See how QDoc renders this property on the reference page for the
+ \l {http://doc.trolltech.com/4.7/qml-state.html#changes-prop} {State}
+ element.
+ \target obsolete-command
+ \section1 \\obsolete
- \target compat-command
- \section1 \\compat
+ The \\obsolete command is for indicating that a function is being
+ deprecated, and it should no longer be used in new code. There is
+ no guarantee for how long it will remain in the library.
- The \\compat command indicates that the referenced class
- or function is part of the support library provided to keep
- old source code working.
+ The command must stand on its own line.
- The command must stand on its own line.
+ When generating the reference documentation for a class, QDoc will
+ create and link to a separate page documenting its obsolete
+ functions. Usually an equivalent function is provided as an
+ alternative.
- Usually an equivalent function or class is provided as an
- alternative.
+ \code
+ / *!
+ \fn MyClass::MyObsoleteFunction
+ \obsolete
- If the command is used within the documentation of a class,
- the command expands to a warning that the referenced class
- is part of the support library. The warning is located on
- top of the associated documentation. For example:
+ Use MyNewFunction() instead.
+ * /
+ \endcode
- \code
- / *!
- \class MyQt3SupportClass
- \compat
- * /
- \endcode
+ QDoc renders this in \c{myclass-obsolete.html} as:
- QDoc renders this as:
+ \quotation
+ \raw HTML
+ <h1>Obsolete Members for MyClass</h1>
+ \endraw
- \quotation
- \bold {This class is part of the Qt 3 support
- library.} It is provided to keep old source code
- working. We strongly advise against using it in new
- code. See the \l
- {http://qt.nokia.com/doc/4.0/porting4.html} {Porting
- Guide} for more information.
- \endquotation
+ \bold {The following class members are obsolete.} They are
+ provided to keep old source code working. We strongly advise
+ against using them in new code.
- on the top of the MyQt3SupportClass class reference.
+ ...
- If the command is used when documenting a function, QDoc
- will create and link to a separate page documenting Qt 3
- support members when generating the reference documentation
- for the associated class. For example:
+ \list
+ \o void MyObsoleteFunction() \c (obsolete)
+ \o ...
+ \endlist
- \code
- / *!
- \fn MyClass::MyQt3SupportMemberFunction
- \compat
+ \raw HTML
+ <hr />
+ <h2>Member Function Documentation</h2>
+ <h3>void MyObsoleteFunction ()</h3>
+ <p>Use MyNewFunction() instead.</p>
+ \endraw
+ ...
+ \endquotation
- Use MyNewFunction() instead.
- * /
- \endcode
+ \target internal-command
+ \section1 \\internal
- QDoc renders this as:
+ The \\internal command indicates that the referenced
+ function is not part of the public interface.
- \quotation
- \raw HTML
- <h1>Qt 3 Support Members for MyClass</h1>
- \endraw
+ The command must stand on its own line.
- \bold {The following class members are part of the Qt
- 3 support layer.} They are provided to help you port
- old code to Qt 4. We advise against using them in new
- code.
+ QDoc ignores the documentation as well as the documented item,
+ when generating the associated class reference documenation.
- ...
+ \code
+ / *!
+ \internal
- \list
- \o void MyQt3SupportMemberFunction()
- \o ...
- \endlist
+ Tries to find the decimal separator. If it can't find
+ it and the thousand delimiter is != '.' it will try to
+ find a '.';
+ * /
+ int QDoubleSpinBoxPrivate::findDelimiter
+ (const QString &str, int index) const
+ {
+ int dotindex = str.indexOf(delimiter, index);
+ if (dotindex == -1 && thousand != dot && delimiter != dot)
+ dotindex = str.indexOf(dot, index);
+ return dotindex;
+ }
+ \endcode
- \raw HTML
- <hr />
- <h2>Member Function Documentation</h2>
- <h3>void MyQt3SupportMemberFunction ()</h3>
- <p>Use MyNewFunction() instead.</p>
- \endraw
+ This function will not be included in the documentation.
- ...
- \endquotation
+ \target preliminary-command
+ \section1 \\preliminary
- in myclass-qt3.html
+ The \\preliminary command is for indicating that a referenced
+ function is still under development.
+ The command must stand on its own line.
+ The \\preliminary command expands to a notification in the
+ function documentation, and marks the function as preliminary when
+ it appears in lists.
- \target internal-command
- \section1 \\internal
+ \code
+ / *!
+ \preliminary
- The \\internal command indicates that the referenced
- function is not part of the public interface.
+ Returns information about the joining properties of the
+ character (needed for certain languages such as
+ Arabic).
+ * /
+ QChar::Joining QChar::joining() const
+ {
+ return ::joining(*this);
+ }
+ \endcode
- The command must stand on its own line.
+ QDoc renders this as:
- QDoc ignores the documentation as well as the documented
- item, when generating the associated class reference
- documenation. For example:
+ \quotation
+ \raw HTML
+ <h3>
+ <a href="http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum">Joining</a>
+ QChar::joining () const</h3>
+ \endraw
- \code
- / *!
- \internal
+ \bold {This function is under development and
+ subject to change.}
- Tries to find the decimal separator. If it can't find
- it and the thousand delimiter is != '.' it will try to
- find a '.';
- * /
- int QDoubleSpinBoxPrivate::findDelimiter
- (const QString &str, int index) const
- {
- int dotindex = str.indexOf(delimiter, index);
- if (dotindex == -1 && thousand != dot && delimiter != dot)
- dotindex = str.indexOf(dot, index);
- return dotindex;
- }
- \endcode
+ Returns information about the joining properties of the
+ character (needed for certain languages such as
+ Arabic).
+ \endquotation
- in qspinbox.cpp, will not be rendered at all.
+ And the function's entry in QChar's list of functions will be
+ rendered as:
+ \quotation
+ \list
+ \o ...
+ \o Joining
+ \l {http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum}
+ {joining}()
+ const \c (preliminary)
+ \o ...
+ \endlist
+ \endquotation
\target since-command
\section1 \\since
@@ -5886,52 +6121,46 @@
The \\since command tells in which minor release
the associated functionality was added.
- For example:
-
- \code
- / *!
- \since 4.1
-
- Returns an icon for \a standardIcon.
+ \code
+ / *!
+ \since 4.1
- ...
+ Returns an icon for \a standardIcon.
- \sa standardIconImplementation(), standardPixmap()
- * /
- QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const
- {
- }
- \endcode
-
- QDoc renders this as:
+ ...
- \quotation
- \raw HTML
- <h3>QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const</h3>
- \endraw
+ \sa standardIconImplementation(), standardPixmap()
+ * /
+ QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const
+ {
+ }
+ \endcode
- This function was introduced in Qt version 4.1
+ QDoc renders this as:
- Returns an icon for \a standardIcon.
+ \quotation
+ \raw HTML
+ <h3>QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const</h3>
+ \endraw
- ...
+ This function was introduced in Qt version 4.1
- See also \l
- {QStyle::standardIconImplementation()} {standardIconImplementation()}
- and \l {QStyle::standardPixmap()} {standardPixmap()}.
- \endquotation
+ Returns an icon for \a standardIcon.
- QDoc generates the "Qt" reference from the \l
- {25-qdoc-configuration-derivedprojects.html#project} {\c
- project} configuration variable. For that reason this
- reference will change according to the current
- documentation project.
+ ...
- See also \l
- {25-qdoc-configuration-derivedprojects.html#project} {\c
- project}.
+ See also \l {QStyle::standardIconImplementation()}
+ {standardIconImplementation()} and \l
+ {QStyle::standardPixmap()} {standardPixmap()}.
+ \endquotation
+ QDoc generates the "Qt" reference from the \l
+ {25-qdoc-configuration-derivedprojects.html#project} {\c project}
+ configuration variable. For that reason this reference will change
+ according to the current documentation project.
+ See also \l {25-qdoc-configuration-derivedprojects.html#project}
+ {\c project}.
*/
/*!
@@ -5942,14 +6171,10 @@
\title Thread Support
- The thread support commands specify the level of support for
- multithreaded programming of a class or function.
-
- \section1 General Description
-
- There are three levels of support for multithreaded programming of
- a class or function: \c threadsafe, \c reentrant and \c
- nonreentrant.
+ The thread support commands are for specifying the level of
+ support for multithreaded programming in a class or function.
+ There are three levels of support: \c threadsafe, \c reentrant and
+ \c nonreentrant.
The default is \c nonreentrant which means that the associated
class or function cannot be called by multiple threads. \c
@@ -5962,15 +6187,14 @@
can be called simultaneously by multiple threads even when each
invocation references shared data.
- When a class is declared \c reentrant or \c threadsafe, using the
- \l {reentrant-command} {\\reentrant} and \l {threadsafe-command} {\\threadsafe}
- commands respectively, functions in the referenced class can be
- declared \c nonreentrant, using the \l
- {nonreentrant-command} {\\nonreentrant} command, excluding the functions
- from the general view.
+ When a class is marked \l {reentrant-command} {\\reentrant} or \l
+ {threadsafe-command} {\\threadsafe}, functions in that class can
+ be marked \c nonreentrant using the \l {nonreentrant-command}
+ {\\nonreentrant} command.
- For example:
+ \section1 Example
+ \target reentrant-example
\code
/ *!
\class QLocale
@@ -6071,56 +6295,55 @@
For more information see the general documentation on \l
{threads.html#reentrant} {reentrancy and thread-safety}.
- \target threadsafe-command
- \section1 \\threadsafe
+ \section1 Commands
- The \\threadsafe command indicates that the
- associated class or function can be called simultaneously by
- multiple threads even when each invocation references
- shared data.
+ \target threadsafe-command
+ \section2 \\threadsafe
- The command must stand on its own line.
+ The \\threadsafe command includes a line in the documentation to
+ indicate that the associated class or function is \e threadsafe
+ and can be called simultaneously by multiple threads, even when
+ separate invocations reference shared data.
- The generated documentation resulting from using the
- \\threadsafe command is similar to the result of using the
- \l {reentrant-command} {\\reentrant} command. For an example, see
- the \l {General Description} section.
+ The command must stand on its own line.
- See also \l{reentrant-command} {\\reentrant} and
- \l{nonreentrant-command} {\\nonreentrant}.
+ The documentation generated from this command will be similar to
+ the what is generated for the \l {reentrant-command} {\\reentrant}
+ command. See the example above in the \l {reentrant-example}
+ {introduction}.
+ See also \l{reentrant-command} {\\reentrant} and
+ \l{nonreentrant-command} {\\nonreentrant}.
\target reentrant-command
- \section1 \\reentrant
+ \section2 \\reentrant
- The \\reentrant command indicates that the associated
- class or function can be called simultaneously
- by multiple threads, provided that each invocation of the
- functions reference unique data.
+ The \\reentrant command indicates that the associated class or
+ function can be called simultaneously by multiple threads,
+ provided that each invocation references its own data. See the \l
+ {reentrant-example} {example} above.
- The command must stand on its own line.
-
- For an example, see the \l {General Description} section.
-
- See also \l{nonreentrant-command} {\\nonreentrant} and
- \l{threadsafe-command} {\\threadsafe}.
+ The command must stand on its own line.
+ See also \l{nonreentrant-command} {\\nonreentrant} and
+ \l{threadsafe-command} {\\threadsafe}.
\target nonreentrant-command
- \section1 \\nonreentrant
-
- The \\nonreentrant command indicates that the
- associated class or function cannot be called by
- multiple threads.
+ \section2 \\nonreentrant
- The command must stand on its own line.
+ The \\nonreentrant command indicates that the associated class or
+ function cannot be called by multiple threads. Nonreentrant is the
+ default case.
- For an example, see the \l {General Description} section.
-
- See also \l{reentrant-command} {\\reentrant} and
- \l{threadsafe-command} {\\threadsafe}.
+ The command must stand on its own line.
+ When a class is marked \l {reentrant-command} {\\reentrant} or \l
+ {threadsafe-command} {\\threadsafe}, functions in that class can
+ be marked \c nonreentrant using this command in the \l{fn-command}
+ {\\fn} comment of the functions to be excluded.
+ See also \l{reentrant-command} {\\reentrant} and
+ \l{threadsafe-command} {\\threadsafe}.
*/
/*!
@@ -6131,147 +6354,180 @@
\title Relating Things
- The relation commands discribe how the documented object relates
- to its context: Whether it is an overloaded function, a
- reimplemented function or a global function related to a specified
- class or header file.
+ The relating commands are for specifying how one documented
+ element relates to another documented element. e.g., This function
+ is an overload of another function, or this function is a
+ reimplementation of another function, or this typedef is \e
+ related to some class or header file. There is also a command
+ for documenting that a QML element inherits some other QML
+ element.
- \target overload-command
- \section1 \\overload
+ \section1 Commands
- The \\overload command indicates that the
- function is a secondary overload of its name.
+ \target inherits-command
+ \section2 \\inherits \span {class="newStuff"} {(new)}
- The command must stand on its own line.
+ The \\inherits command is for documenting that one QML element
+ inherits some other QML element. It must be included in the
+ inheriting element's \l{qmlclass-command}{\\qmlclass} comment.
+ The argument is the name of the inherited QML element.
- For any overloaded function (except constructors), QDoc
- expects one primary version of the function and all the
- the overloads marked with the \bold{\\overload command}.
- The primary version should be fully documented. Each
- overload can have whatever extra documentation you want
- to add for just that overload.
+ \code
+ / *!
+ \qmlclass PauseAnimation QDeclarativePauseAnimation
+ \ingroup qml-animation-transition
+ \since 4.7
+ \inherits Animation
+ \brief The PauseAnimation element provides a pause for an animation.
- From Qt 4.5, you can include the function name plus '()'
- as a parameter to the \bold{\\overload} command, which
- will include a standard \e{This function overloads...}
- line of text with a link to the documentation for the
- primary version of the function.
+ When used in a SequentialAnimation, PauseAnimation is a step
+ when nothing happens, for a specified duration.
- For example:
+ A 500ms animation sequence, with a 100ms pause between two animations:
- \code
- / *!
- \overload addAction()
+ SequentialAnimation {
+ NumberAnimation { ... duration: 200 }
+ PauseAnimation { duration: 100 }
+ NumberAnimation { ... duration: 200 }
+ }
- This convenience function creates a new action with an
- \a icon and some \a text. The function adds the newly
- created action to the menu's list of actions, and
- returns it.
+ \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example}
+ * /
+ \endcode
- \sa QWidget::addAction()
- * /
- QAction *QMenu::addAction(const QIcon &icon, const QString &text)
- {
- QAction *ret = new QAction(icon, text, this);
- addAction(ret);
- return ret;
- }
- \endcode
+ QDoc includes this line on the reference page for the
+ \l{http://doc.trolltech.com/4.7/qml-pauseanimation.html} {PauseAnimation}
+ element:
- QDoc renders this as:
+ \quotation
+ Inherits \l{http://doc.trolltech.com/4.7/qml-animation.html} {Animation}
+ \endquotation
- \quotation
- \raw HTML
- <h3><a href="http://qt.nokia.com/doc/4.0/qaction.html">QAction</a>
- * QMenu::addAction ( const QIcon & <i>icon</i>,
- const QString & <i>text</i> )
- </h3>
- \endraw
+ \target overload-command
+ \section2 \\overload
- This function overloads \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction} {addAction()}
+ The \\overload command is for indicating that a function is a
+ secondary overload of its name.
- This convenience function creates a new action with an
- \e icon and some \e text. The function adds the newly
- created action to the menu's list of actions, and
- returns it.
+ The command must stand on its own line.
- See also
- \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction}
- {QWidget::addAction}().
- \endquotation
+ For a function name that is overloaded (except constructors), QDoc
+ expects one primary version of the function, and all the others
+ marked with the \bold {\\overload command}. The primary version
+ should be fully documented. Each overload can have whatever extra
+ documentation you want to add for just that overloaded version.
- If you don't include the function name with the
- \bold{\\overlaod} command, then instead of the "This
- function overloads..." line with the link to the
- documentation for the primary version, you get the old
- standard line:
+ From Qt 4.5, you can include the function name plus '()' as a
+ parameter to the \bold{\\overload} command, which will include a
+ standard \e{This function overloads...} line of text with a link
+ to the documentation for the primary version of the function.
- \quotation
- This is an overloaded member function, provided for
- convenience.
- \endquotation.
+ \code
+ / *!
+ \overload addAction()
+ This convenience function creates a new action with an
+ \a icon and some \a text. The function adds the newly
+ created action to the menu's list of actions, and
+ returns it.
- \target reimp-command
- \section1 \\reimp
+ \sa QWidget::addAction()
+ * /
+ QAction *QMenu::addAction(const QIcon &icon, const QString &text)
+ {
+ QAction *ret = new QAction(icon, text, this);
+ addAction(ret);
+ return ret;
+ }
+ \endcode
- The \\reimp command indicates that the
- referenced function is a reimplementation of a virtual function,
- where the reimplementation has no effect on the interface.
+ QDoc renders this as:
- The command must stand on its own line.
+ \quotation
+ \raw HTML
+ <h3><a href="http://qt.nokia.com/doc/4.0/qaction.html">QAction</a>
+ * QMenu::addAction ( const QIcon & <i>icon</i>,
+ const QString & <i>text</i> )
+ </h3>
+ \endraw
- QDoc will omit the reimplemented function from the class
- reference. For example:
+ This function overloads \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction} {addAction()}
- \code
- / *!
- \reimp
- * /
- void QToolButton::nextCheckState()
- {
- Q_D(QToolButton);
- if (!d->defaultAction)
- QAbstractButton::nextCheckState();
- else
- d->defaultAction->trigger();
- }
- \endcode
+ This convenience function creates a new action with an
+ \e icon and some \e text. The function adds the newly
+ created action to the menu's list of actions, and
+ returns it.
- will not be rendered at all; only a link to the inherited
- QAbstractButton::nextCheckState() will appear in the
- documentation.
+ See also
+ \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction}
+ {QWidget::addAction}().
+ \endquotation
+ If you don't include the function name with the \bold{\\overlaod}
+ command, then instead of the "This function overloads..." line
+ with the link to the documentation for the primary version, you
+ get the old standard line:
- \target relates-command
- \section1 \\relates
+ \quotation
+ This is an overloaded member function, provided for
+ convenience.
+ \endquotation.
- The \\relates command attaches the documentation of
- a global function to that of a related class or header file.
+ \target reimp-command
+ \section2 \\reimp
- The command's argument is a class name, an the command (and
- its argument) must stand on its own line.
+ The \\reimp command is for indicating that a function is a
+ reimplementation of a virtual function.
- \code
- / *!
- \relates QChar
+ The command must stand on its own line.
- Reads a char from the stream \a in into char \a chr.
+ QDoc will omit the reimplemented function from the class
+ reference.
- \sa {Format of the QDataStream operators}
- * /
- QDataStream &operator>>(QDataStream &in, QChar &chr)
- {
- quint16 u;
- in >> u;
- chr.unicode() = ushort(u);
- return in;
- }
- \endcode
+ \code
+ / *!
+ \reimp
+ * /
+ void QToolButton::nextCheckState()
+ {
+ Q_D(QToolButton);
+ if (!d->defaultAction)
+ QAbstractButton::nextCheckState();
+ else
+ d->defaultAction->trigger();
+ }
+ \endcode
+
+ This function will not be included in the documentation. Instead,
+ a link to the base function QAbstractButton::nextCheckState() will
+ appear in the documentation.
+
+ \target relates-command
+ \section2 \\relates
+
+ The \\relates command is for including the documentation of a
+ global element to some class or header file. The argument is a
+ class name or header file.
- will be rendered with the QChar documentation.
+ \code
+ / *!
+ \relates QChar
+ Reads a char from the stream \a in into char \a chr.
+ \sa {Format of the QDataStream operators}
+ * /
+ QDataStream &operator>>(QDataStream &in, QChar &chr)
+ {
+ quint16 u;
+ in >> u;
+ chr.unicode() = ushort(u);
+ return in;
+ }
+ \endcode
+
+ The documentation for this function will be included on the reference page
+ for class QChra.
*/
/*!
@@ -6287,108 +6543,105 @@
classes in the documentation, while the modules are elements of
Qt's structure.
+ \section1 Commands
+
\target mainclass-command
- \section1 \\mainclass
+ \section2 \\mainclass
The \\mainclass command relates the documented class to
a group called mainclasses.
- The command must stand on its own line.
-
- For example:
+ The command must stand on its own line.
- \code
- / *!
- \class QWidget qwidget.h
- \brief The QWidget class is the base class of
- all user interface objects.
+ \code
+ / *!
+ \class QWidget qwidget.h
+ \brief The QWidget class is the base class of
+ all user interface objects.
- \mainclass
+ \mainclass
- ...
- * /
- \endcode
+ ...
+ * /
+ \endcode
- will ensure that the QWidget class is included in the \c
- mainclasses group, which means, for example, that the class
- will appear on the list created by calling the \l
- {generatelist-command} {\\generatelist} command with the \c
- mainclasses argument:
+ This will include the QWidget class in the \e mainclasses
+ group, which means, for example, that the class will appear on the
+ list created by calling the \l {generatelist-command}
+ {\\generatelist} command with the \c mainclasses argument:
- \l http://qt.nokia.com/doc/4.0/mainclasses.html
+ \l http://qt.nokia.com/doc/4.0/mainclasses.html
- See also \l {generatelist-command} {\\generatelist}.
+ \note The Qt documentation no longer includes the \e mainclasses
+ page.
+ See also \l {generatelist-command} {\\generatelist}.
\target ingroup-command
- \section1 \\ingroup
+ \section2 \\ingroup
The \\ingroup command indicates that the given
overview or documented class belongs to a certain group of
related docmentation.
- A class or overview may belong to many groups.
+ A class or overview may belong to many groups.
- The \\ingroup command's argument is a group name, but note
- that the command considers the rest of the line as part of
- its argument. Make sure that the group name is followed by
- a linebreak. For example:
+ The \\ingroup command's argument is a group name, but note
+ that the command considers the rest of the line as part of
+ its argument. Make sure that the group name is followed by
+ a linebreak.
- \code
- / *!
- \class QDir
- \brief The QDir class provides access to directory
- structures and their contents.
+ \code
+ / *!
+ \class QDir
+ \brief The QDir class provides access to directory
+ structures and their contents.
- \ingroup io
- ...
- * /
- \endcode
+ \ingroup io
+ ...
+ * /
+ \endcode
- will ensure that the QDir class is included in the \c io
- group, which means, for example, that QDir will appear on
- the list created by calling the \l {group-command} {\\group} command
- with the \c io argument.
+ This will include the QDir class in the \c io group, which means,
+ for example, that QDir will appear on the list created by calling
+ the \l {group-command} {\\group} command with the \c io argument.
- Note that to list overviews that are related to a given
- group, you must generate the list exlicitly by using the \l
- {generatelist-command} {\\generatelist} command with the \c related
- argument.
+ To list overviews that are related to a certain group, you must
+ generate the list explicitly using the \l {generatelist-command}
+ {\\generatelist} command with the \c related argument.
- See also \l {group-command} {\\group}.
+ See also \l {group-command} {\\group}.
\target inmodule-command
- \section1 \\inmodule
-
- The \\inmodule command relates the documented class
- to the module specified by the command's argument.
+ \section2 \\inmodule
- For the basic classes in Qt, a class's module is determined
- by its location, i.e. its directory. However, for
- extensions, like ActiveQt and Qt Designer, a class needs to
- be related to a module explicitly.
+ The \\inmodule command relates a class to the module specified by
+ the command's argument.
- The command's argument is a module name, but note that the
- command considers the rest of the line as part of its
- argument. Make sure that the module name is followed by a
- linebreak. For example:
+ For the basic classes in Qt, a class's module is determined by its
+ location, i.e. its directory. However, for extensions, like
+ ActiveQt and Qt Designer, a class must be related to a module
+ explicitly.
- \code
- /*!
- \class QDesignerTaskMenuExtension
- \inmodule QtDesigner
- * /
- \endcode
+ The command's argument is a module name, but note that the command
+ considers the rest of the line as part of its argument. Make sure
+ that the module name is followed by a linebreak.
- will ensure that the QDesignerTaskMenuExtension class is
- included in the \c QtDesigner module, which means, for
- example, that the class will appear on the list created by
- calling the \l {generatelist-command} {\\generatelist} command with
- the \c {{classesbymodule QtDesigner}} argument.
+ \code
+ /*!
+ \class QDesignerTaskMenuExtension
+ \inmodule QtDesigner
+ * /
+ \endcode
- See also \l {module-command} {\\module} and \l
- {generatelist-command} {\\generatelist}.
+ This ensures that the QDesignerTaskMenuExtension class is included
+ in the \c QtDesigner module, which means, for example, that the
+ class will appear on the list created by calling the \l
+ {generatelist-command} {\\generatelist} command with the \c
+ {{classesbymodule QtDesigner}} argument.
+ See also \l {module-command} {\\module} and \l
+ {generatelist-command} {\\generatelist}.
*/
/*!
@@ -6399,90 +6652,83 @@
\title Naming Things
- In general a title command considers everything that follows it
- until the first line break as its argument. If the title needs to
- be spanned over several lines, make sure to end each line (except
- the last one) with a backslash.
-
- \target title-command
- \section1 \\title
-
- The \\title command sets the title for a
- documentation page, or allows you to override it.
+ In general, a title command considers everything that follows it
+ until the first line break as its argument. If the title is so
+ long it must span multiple lines, end each line (except the last
+ one) with a backslash.
- For example:
+ \section1 Commands
- \code
- / *!
- \page signalandslots.html
+ \target title-command
+ \section2 \\title
- \title Signals & Slots
+ The \\title command sets the title for a documentation page, or
+ allows you to override it.
- Signals and slots are used for communication between
- objects. The signals and slots mechanism is a central
- feature of Qt and probably the part that differs most
- from the features provided by other frameworks.
+ \code
+ / *!
+ \page signalandslots.html
- ...
- * /
- \endcode
+ \title Signals & Slots
- QDoc renders this as:
+ Signals and slots are used for communication between
+ objects. The signals and slots mechanism is a central
+ feature of Qt and probably the part that differs most
+ from the features provided by other frameworks.
- \quotation
- \raw HTML
- <h1><center>Signal and Slots</center></h1>
- \endraw
+ ...
+ * /
+ \endcode
- Signals and slots are used for communication between
- objects. The signals and slots mechanism is a central
- feature of Qt and probably the part that differs most
- from the features provided by other frameworks.
+ QDoc renders this as:
- ...
- \endquotation
- See also \l {subtitle-command} {\\subtitle}.
+ \quotation
+ \raw HTML
+ <h1><center>Signal and Slots</center></h1>
+ \endraw
+ Signals and slots are used for communication between
+ objects. The signals and slots mechanism is a central
+ feature of Qt and probably the part that differs most
+ from the features provided by other frameworks.
+ ...
+ \endquotation
+ See also \l {subtitle-command} {\\subtitle}.
\target subtitle-command
- \section1 \\subtitle
+ \section2 \\subtitle
- The \\subtitle command sets a subtitle for a
- documentation page.
+ The \\subtitle command sets a subtitle for a documentation page.
- For example:
-
- \code
- / *!
- \page qtopiacore-overview.html
-
- \title Qtopia Core
- \subtitle Qt for Embedded Linux
-
- Qt/Embedded, the embedded Linux port of Qt, is a
- complete and self-contained C++ GUI and platform
- development tool for Linux-based embedded development.
+ \code
+ / *!
+ \page qtopiacore-overview.html
- ...
- * /
- \endcode
+ \title Qtopia Core
+ \subtitle Qt for Embedded Linux
- QDoc renders this as:
+ Qt/Embedded, the embedded Linux port of Qt, is a
+ complete and self-contained C++ GUI and platform
+ development tool for Linux-based embedded development.
+ ...
+ * /
+ \endcode
- \quotation
- \raw HTML
- <h1><center>Qtopia Core</center></h1>
- <h2><center>Qt for Embedded Linux</center></h2>
- \endraw
+ QDoc renders this as:
- Qt/Embedded, the embedded Linux port of Qt, is a
- complete and self-contained C++ GUI and platform
- development tool for Linux-based embedded development.
+ \quotation
+ \raw HTML
+ <h1><center>Qtopia Core</center></h1>
+ <h2><center>Qt for Embedded Linux</center></h2>
+ \endraw
- ...
- \endquotation
+ Qt/Embedded, the embedded Linux port of Qt, is a
+ complete and self-contained C++ GUI and platform
+ development tool for Linux-based embedded development.
+ ...
+ \endquotation
- See also \l {title-command} {\\title}.
+ See also \l {title-command} {\\title}.
*/
@@ -6524,7 +6770,7 @@
projects.
If some of the variable keys have the same values, they can be set
- at the same time. For example:
+ at the same time.
\code
{header, source}dirs = kernel
@@ -6546,7 +6792,7 @@
provide a variable of the latter type with several strings they
will simply be concatenated. The quotes around the value string
are optional. But applying them allows you to use special
- characters like '=' and ' \" ' within the string. For example:
+ characters like '=' and ' \" ' within the string.
\code
HTML.postheader = "<a href=\"index.html\">Home</a>"
@@ -6656,657 +6902,606 @@
The \c alias variable renames a QDoc command.
- The general syntax is \tt {alias.\e{original-command-name}
- = \e temporary-command-name}.
-
- For example:
-
- \code
- alias.i = e
- \endcode
+ The general syntax is \tt {alias.\e{original-command-name} = \e
+ temporary-command-name}.
- renames the built-in command \\i (italics) to \\e.
-
- The \c alias variable is often used for compatibility
- reasons; for more information see the
- \l {Compatibility Issues} {compatibility section}.
+ \code
+ alias.i = e
+ \endcode
- See also \l {macro-command} {macro}.
+ This renames the built-in command \\i (italics) to \\e. The \c
+ alias variable is often used for compatibility reasons; for more
+ information see the \l {Compatibility Issues} {compatibility
+ section}.
+ See also \l {macro-command} {macro}.
\target codeindent-variable
\section1 codeindent
- The \c codeindent variable specifies the level of
- indentation that QDoc uses when writing code snippets.
-
- QDoc originally used a hard-coded value of four spaces for
- code indentation to ensure that code snippets could be easily
- distinguished from surrounding text. Since we can use
- \l{HTML Specific Configuration Variables#HTML.stylesheets} {stylesheets} to
- adjust the appearance of certain types of HTML elements, this
- level of indentation is not always required.
+ The \c codeindent variable specifies the level of indentation that
+ QDoc uses when writing code snippets.
+ QDoc originally used a hard-coded value of four spaces for code
+ indentation to ensure that code snippets could be easily
+ distinguished from surrounding text. Since we can use \l{HTML
+ Specific Configuration Variables#HTML.stylesheets} {stylesheets}
+ to adjust the appearance of certain types of HTML elements, this
+ level of indentation is not always required.
\target defines-variable
\section1 defines
- The \c defines variable specifies the C++ preprocessor
- symbols that QDoc will recognize and respond to.
+ The \c defines variable specifies the C++ preprocessor symbols
+ that QDoc will recognize and respond to.
- When a preprocessor symbol is specified using the \c
- defines variable, you can also use the \l {if-command} {\\if}
- command to enclose documentation that only will be included
- if the preprocessor symbol is defined.
+ When a preprocessor symbol is specified using the \c defines
+ variable, you can also use the \l {if-command} {\\if} command to
+ enclose documentation that only will be included if the
+ preprocessor symbol is defined.
- The values of the variable are regular expressions (see
- QRegExp for details). By default, no symbol is defined,
- meaning that code protected with #ifdef...#endif will be
- ignored.
+ The values of the variable are regular expressions (see QRegExp
+ for details). By default, no symbol is defined, meaning that code
+ protected with #ifdef...#endif will be ignored.
- For example:
-
- \code
- defines = Q_QDOC \
- QT_.*_SUPPORT \
- QT_.*_LIB \
- QT_COMPAT \
- QT3_SUPPORT \
- Q_WS_.* \
- Q_OS_.* \
- Q_BYTE_ORDER \
- __cplusplus
- \endcode
-
- ensures that QDoc will process the code that requires these
- symbols to be defined. For example:
+ \code
+ defines = Q_QDOC \
+ QT_.*_SUPPORT \
+ QT_.*_LIB \
+ QT_COMPAT \
+ QT3_SUPPORT \
+ Q_WS_.* \
+ Q_OS_.* \
+ Q_BYTE_ORDER \
+ __cplusplus
+ \endcode
- \code
- #ifdef Q_WS_WIN
- HDC getDC() const;
- void releaseDC(HDC) const;
- #endif
- \endcode
+ This ensures that QDoc will process the code that requires these
+ symbols to be defined. For example:
- Since the Q_WS_.* regular expression (specified using the
- \c defines variable) matches Q_WS_WIN, QDoc will process
- the code within #ifdef and #endif in our example.
+ \code
+ #ifdef Q_WS_WIN
+ HDC getDC() const;
+ void releaseDC(HDC) const;
+ #endif
+ \endcode
- You can also define preprocessor symbols manually on the
- command line using the -D option. For example:
+ Since the Q_WS_.* regular expression (specified using the \c
+ defines variable) matches Q_WS_WIN, QDoc will process the code
+ within #ifdef and #endif in our example.
- \code
- currentdirectory$ qdoc3 -Dconsoleedition qt.qdocconf
- \endcode
+ You can also define preprocessor symbols manually on the command
+ line using the -D option. For example:
- In this case the -D option ensures that the \c
- consoleedition preprocessor symbol is defined when QDoc
- processes the source files defined in the qt.qdocconf file.
+ \code
+ currentdirectory$ qdoc3 -Dconsoleedition qt.qdocconf
+ \endcode
- See also \l {falsehoods-variable} {falsehoods} and \l {if-command} {\\if}.
+ In this case the -D option ensures that the \c consoleedition
+ preprocessor symbol is defined when QDoc processes the source
+ files defined in the qt.qdocconf file.
+ See also \l {falsehoods-variable} {falsehoods} and \l {if-command} {\\if}.
\target edition-variable
\section1 edition
- The \c edition variable specifies which modules are
- included in each edition of a package, and provides QDoc
- with information to provide class lists for each edition.
-
- This feature is mostly used when providing documentation
- for Qt packages.
+ The \c edition variable specifies which modules are included in
+ each edition of a package, and provides QDoc with information to
+ provide class lists for each edition.
- The \c edition variable is always used with a particular
- edition name to define the modules for that edition:
+ This feature is mostly used when providing documentation for Qt
+ packages.
- \code
- edition.Console = QtCore QtNetwork QtSql QtXml
- edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \
- QtDesigner QtAssistant Qt3Support QAxContainer \
- QAxServer
- edition.DesktopLight = QtCore QtGui Qt3SupportLight
- \endcode
+ The \c edition variable is always used with a particular edition
+ name to define the modules for that edition:
- In the above examples, the \c Console edition only includes
- the contents of four modules. Only the classes from these
- modules will be used when the
- \l{Miscellaneous#generatelist-command} {generatelist} command
- is used to generate a list of classes for this edition:
+ \code
+ edition.Console = QtCore QtNetwork QtSql QtXml
+ edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \
+ QtDesigner QtAssistant Qt3Support QAxContainer \
+ QAxServer
+ edition.DesktopLight = QtCore QtGui Qt3SupportLight
+ \endcode
- \code
- \generatelist{classesbyedition Console}
- \endcode
+ In the above examples, the \c Console edition only includes the
+ contents of four modules. Only the classes from these modules will
+ be used when the \l{Miscellaneous#generatelist-command}
+ {generatelist} command is used to generate a list of classes for
+ this edition:
+ \code
+ \generatelist{classesbyedition Console}
+ \endcode
\target exampledirs-variable
\section1 exampledirs
- The \c exampledirs variable specifies the directories
- containing the source code of the example files.
-
- The \l {examples-variable} {examples} {examples} and \l
- {exampledirs-variable} {exampledirs} variables are used by
- the \l {quotefromfile-command} {\\quotefromfile}, \l
- {quotefile-command} {\\quotefile} and \l {example-command}
- {\\example} commands. If both the \l {examples-variable}
- {examples} and \l {exampledirs-variable} {exampledirs}
- variables are defined, QDoc will search in both, first in
- \l {examples-variable} {examples} then in \l
- {exampledirs-variable} {exampledirs}.
+ The \c exampledirs variable specifies the directories containing
+ the source code of the example files.
- QDoc will search through the directories in the specified
- order, and accept the first matching file it finds. It will
- only search in the specified directories, \e not in
- subdirectories.
+ The \l {examples-variable} {examples} {examples} and \l
+ {exampledirs-variable} {exampledirs} variables are used by the \l
+ {quotefromfile-command} {\\quotefromfile}, \l {quotefile-command}
+ {\\quotefile} and \l {example-command} {\\example} commands. If
+ both the \l {examples-variable} {examples} and \l
+ {exampledirs-variable} {exampledirs} variables are defined, QDoc
+ will search in both, first in \l {examples-variable} {examples}
+ then in \l {exampledirs-variable} {exampledirs}.
- For example:
+ QDoc will search through the directories in the specified order,
+ and accept the first matching file it finds. It will only search
+ in the specified directories, \e not in subdirectories.
- \code
- exampledirs = $QTDIR/doc/src \
- $QTDIR/examples \
- $QTDIR \
- $QTDIR/qmake/examples
+ \code
+ exampledirs = $QTDIR/doc/src \
+ $QTDIR/examples \
+ $QTDIR \
+ $QTDIR/qmake/examples
- examples = $QTDIR/examples/widgets/analogclock/analogclock.cpp
- \endcode
+ examples = $QTDIR/examples/widgets/analogclock/analogclock.cpp
+ \endcode
- When processing
+ When processing
- \code
- \quotefromfile widgets/calculator/calculator.cpp
- \endcode
-
- QDoc will then see if there exists a file called \c
- calculator.cpp listed as a value in the \l {examples} {\c
- examples} variable. If it doesn't, it will search in the \c
- exampledirs variable, and first see if there exists a file
- called
+ \code
+ \quotefromfile widgets/calculator/calculator.cpp
+ \endcode
- \code
- $QTDIR/doc/src/widgets/calculator/calculator.cpp
- \endcode
+ QDoc will then see if there exists a file called \c calculator.cpp
+ listed as a value in the \l {examples} {\c examples} variable. If
+ it doesn't, it will search in the \c exampledirs variable, and
+ first see if there exists a file called
- If it doesn't, QDoc will continue looking for a file
- called
+ \code
+ $QTDIR/doc/src/widgets/calculator/calculator.cpp
+ \endcode
- \code
- $QTDIR/examples/widgets/calculator/calculator.cpp
- \endcode
+ If it doesn't, QDoc will continue looking for a file called
- and so forth.
+ \code
+ $QTDIR/examples/widgets/calculator/calculator.cpp
+ \endcode
- See also \l examples.
+ and so forth.
+ See also \l examples.
\target examples-variable
\section1 examples
- The \c examples variable allows you to specify individual
- example files in addition to those located in the directories
- specified by the \l {exampledirs-variable} {\c exampledirs} variable.
-
- The \c examples and \l {exampledirs-variable} {\c exampledirs}
- variables are used by the \l {quotefromfile-command} {\\quotefromfile},
- \l {quotefile-command} {\\quotefile} and \l {example}
- {\\example} commands. If both the \c examples and \l {exampledirs-variable}
- {\c exampledirs} variables are defined, QDoc will search in both, first in
- \c examples then in \l {exampledirs-variable} {\c exampledirs}.
+ The \c examples variable allows you to specify individual example
+ files in addition to those located in the directories specified by
+ the \l {exampledirs-variable} {\c exampledirs} variable.
- QDoc will search through the values listed for the \c examples
- variable, in the specified order, and accept the
- first one it finds.
+ The \c examples and \l {exampledirs-variable} {\c exampledirs}
+ variables are used by the \l {quotefromfile-command}
+ {\\quotefromfile}, \l {quotefile-command} {\\quotefile} and \l
+ {example} {\\example} commands. If both the \c examples and \l
+ {exampledirs-variable} {\c exampledirs} variables are defined,
+ QDoc will search in both, first in \c examples then in \l
+ {exampledirs-variable} {\c exampledirs}.
- For an extensive example, see the \l {exampledirs-variable}
- {\c exampledirs} command. But note that if you know the file is
- listed in the \c examples variable, you don't need to specify its
- path:
+ QDoc will search through the values listed for the \c examples
+ variable, in the specified order, and accept the first one it
+ finds.
- \code
- \quotefromfile calculator.cpp
- \endcode
+ For an extensive example, see the \l {exampledirs-variable} {\c
+ exampledirs} command. But note that if you know the file is listed
+ in the \c examples variable, you don't need to specify its path:
- See also \l {exampledirs-variable} {exampledirs}.
+ \code
+ \quotefromfile calculator.cpp
+ \endcode
+ See also \l {exampledirs-variable} {exampledirs}.
\target examples.fileextensions-variable
\section1 examples.fileextensions
- The \c examples.fileextensions variable specifies the
- file extensions that qdoc will look for when collecting example
- files for display in the documentation.
+ The \c examples.fileextensions variable specifies the file
+ extensions that qdoc will look for when collecting example files
+ for display in the documentation.
- The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml
- and *.ui. However, if
+ The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml
+ and *.ui. However, if
- The extensions are given as standard wildcard expressions.
- You can add a file extension to the filter using '+='. For
- example:
+ The extensions are given as standard wildcard expressions. You
+ can add a file extension to the filter using '+='. For example:
- \code
- examples.fileextensions += *.qrc
- \endcode
-
- See also \l{headers.fileextensions}.
+ \code
+ examples.fileextensions += *.qrc
+ \endcode
+ See also \l{headers.fileextensions}.
\target extraimages-variable
\section1 extraimages
- The \c extraimages variable tells QDoc to incorporate
- specific images in the generated documentation.
+ The \c extraimages variable tells QDoc to incorporate specific
+ images in the generated documentation.
- QDoc will not recognize images used within HTML (or any
- other markup language). If we want the images to be copied
- from the directories specified by \l {imagedirs} {\c
- imagedirs} (the images in question must be located in these
- directories) to the output directory, we must specify the
- images using the \c extraimages variable.
+ QDoc will not recognize images used within HTML (or any other
+ markup language). If we want the images to be copied from the
+ directories specified by \l {imagedirs} {\c imagedirs} (the images
+ in question must be located in these directories) to the output
+ directory, we must specify the images using the \c extraimages
+ variable.
- The general syntax is \tt {extraimages.\e{format} = \e
- image}. The file extension is optional.
+ The general syntax is \tt {extraimages.\e{format} = \e image}. The
+ file extension is optional.
- For example, in \l qt.qdocconf we use a couple of images
- within the HTML.postheader variable which value is pure
- HTML. For that reason, these images are specified using the
- \c extraimages variable:
+ For example, in \l qt.qdocconf we use a couple of images within
+ the HTML.postheader variable which value is pure HTML. For that
+ reason, these images are specified using the \c extraimages
+ variable:
- \code
- extraimages.HTML = qt-logo
- \endcode
-
- See also \l images and \l imagedirs.
+ \code
+ extraimages.HTML = qt-logo
+ \endcode
+ See also \l images and \l imagedirs.
\target falsehoods-variable
\section1 falsehoods
- The \c falsehoods variable defines the truth value of
- specified preprocessor symbols as false.
-
- If this variable is not set for a preprocessor symbol, QDoc
- assumes its truth value is true. The exception is '0',
- which value always is false.
+ The \c falsehoods variable defines the truth value of specified
+ preprocessor symbols as false.
- QDoc will recognize, and is able to evaluate, the following
- preprocessor syntax:
+ If this variable is not set for a preprocessor symbol, QDoc
+ assumes its truth value is true. The exception is '0', which value
+ always is false.
- \code
- #ifdef NOTYET
- ...
- #endif
+ QDoc will recognize, and is able to evaluate, the following
+ preprocessor syntax:
- #if defined (NOTYET)
- ...
- #end if
- \endcode
+ \code
+ #ifdef NOTYET
+ ...
+ #endif
- However, faced with unknown syntax like
+ #if defined (NOTYET)
+ ...
+ #end if
+ \endcode
- \code
- #if NOTYET
- ...
- #endif
- \endcode
+ However, faced with unknown syntax like
- QDoc will evaluate it as true by default, \e unless the
- preprocessor symbol is specified within the \c falsehoods
- variable entry:
+ \code
+ #if NOTYET
+ ...
+ #endif
+ \endcode
- \code
- falsehoods = NOTYET
- \endcode
+ QDoc will evaluate it as true by default, \e unless the
+ preprocessor symbol is specified within the \c falsehoods variable
+ entry:
- See also \l defines.
+ \code
+ falsehoods = NOTYET
+ \endcode
+ See also \l defines.
\target generateindex-variable
\section1 generateindex
The \c generateindex variable contains a boolean value that
- specifies whether to generate an index file when HTML documentation
- is generated.
+ specifies whether to generate an index file when HTML
+ documentation is generated.
- By default, an index file is always generated with HTML documentation,
- so this variable is typically only used when disabling this feature
- (by setting the value to \c false) or when enabling index generation
- for the WebXML output (by setting the value to \c true).
+ By default, an index file is always generated with HTML
+ documentation, so this variable is typically only used when
+ disabling this feature (by setting the value to \c false) or when
+ enabling index generation for the WebXML output (by setting the
+ value to \c true).
\target headerdirs-variable
\section1 headerdirs
- The \c headerdirs variable specifies the directories
- containing the header files associated with the \c .cpp source
- files used in the documentation.
-
- For example:
-
- \code
- headerdirs = $QTDIR/src \
- $QTDIR/extensions/activeqt \
- $QTDIR/extensions/motif \
- $QTDIR/tools/designer/src/lib/extension \
- $QTDIR/tools/designer/src/lib/sdk \
- $QTDIR/tools/designer/src/lib/uilib
- \endcode
+ The \c headerdirs variable specifies the directories containing
+ the header files associated with the \c .cpp source files used in
+ the documentation.
- When executed, the first QDoc will do is to read through
- the headers specified in the \l {headers} {\c headers}
- variable, and the ones located in the directories specified
- in the \c headerdir variable (including all
- subdirectories), building an internal structure of the
- classes and their functions.
+ \code
+ headerdirs = $QTDIR/src \
+ $QTDIR/extensions/activeqt \
+ $QTDIR/extensions/motif \
+ $QTDIR/tools/designer/src/lib/extension \
+ $QTDIR/tools/designer/src/lib/sdk \
+ $QTDIR/tools/designer/src/lib/uilib
+ \endcode
- Then it will read through the sources specified in the \l
- {sources-variable} {\c sources}, and the ones located in the
- directories specified in the \l {sourcedirs-variable}
- {\c sourcedirs}
- varible (including all subdirectories), merging the
- documentation with the structure it retrieved from the
- header files.
+ When executed, the first QDoc will do is to read through the
+ headers specified in the \l {headers} {\c headers} variable, and
+ the ones located in the directories specified in the \c headerdir
+ variable (including all subdirectories), building an internal
+ structure of the classes and their functions.
- If both the \c headers and \c headerdirs variables are
- defined, QDoc will read through both, first \l {headers} {\c
- headers} then \c headerdirs.
+ Then it will read through the sources specified in the \l
+ {sources-variable} {\c sources}, and the ones located in the
+ directories specified in the \l {sourcedirs-variable} {\c
+ sourcedirs} varible (including all subdirectories), merging the
+ documentation with the structure it retrieved from the header
+ files.
- In the specified directories, QDoc will only read the files
- with the fileextensions specified in the \l
- {headers.fileextensions} {\c headers.fileextensions}
- variable. The default extensions are *.ch, *.h, *.h++,
- *.hh, *.hpp and *.hxx". The files specified by \l
- {headers} {\c headers} will be read independent of their
- fileextensions.
+ If both the \c headers and \c headerdirs variables are defined,
+ QDoc will read through both, first \l {headers} {\c headers} then
+ \c headerdirs.
- See also \l headers and \l headers.fileextensions.
+ In the specified directories, QDoc will only read the files with
+ the fileextensions specified in the \l {headers.fileextensions}
+ {\c headers.fileextensions} variable. The default extensions are
+ *.ch, *.h, *.h++, *.hh, *.hpp and *.hxx". The files specified by
+ \l {headers} {\c headers} will be read independent of their
+ fileextensions.
+ See also \l headers and \l headers.fileextensions.
\target headers-variable
\section1 headers
- The \c headers variable allows you to specify individual
- header files in addition to those located in the directories
- specified by the \l {headerdirs} {\c headerdirs} variable.
-
- For example:
-
- \code
- headers = $QTDIR/src/gui/widgets/qlineedit.h \
- $QTDIR/src/gui/widgets/qpushbutton.h
- \endcode
+ The \c headers variable allows you to specify individual header
+ files in addition to those located in the directories specified by
+ the \l {headerdirs} {\c headerdirs} variable.
- When processing the \c headers variable, QDoc behaves in the
- same way as it does when processing the \l {headerdirs} {\c
- headerdirs} variable. For more information, see the \l
- {headerdirs} {\c headerdirs} variable.
+ \code
+ headers = $QTDIR/src/gui/widgets/qlineedit.h \
+ $QTDIR/src/gui/widgets/qpushbutton.h
+ \endcode
- See also \l headerdirs.
+ When processing the \c headers variable, QDoc behaves in the same
+ way as it does when processing the \l {headerdirs} {\c headerdirs}
+ variable. For more information, see the \l {headerdirs} {\c
+ headerdirs} variable.
+ See also \l headerdirs.
\target headers.fileextensions-variable
\section1 headers.fileextensions
- The \c headers.fileextensions variable specify the
- extension used by the headers.
+ The \c headers.fileextensions variable specify the extension used
+ by the headers.
- When processing the header files specified in the \l
- {headerdirs} {\c headerdirs} variable, QDoc will only read
- the files with the fileextensions specified in the \c
- headers.fileextensions variable. In this way QDoc avoid
- spending time reading irrelevant files.
+ When processing the header files specified in the \l {headerdirs}
+ {\c headerdirs} variable, QDoc will only read the files with the
+ fileextensions specified in the \c headers.fileextensions
+ variable. In this way QDoc avoid spending time reading irrelevant
+ files.
- The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp
- and *.hxx.
+ The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp and
+ *.hxx.
- The extensions are given as standard wildcard expressions.
- You can add a file extension to the filter using '+='. For
- example:
+ The extensions are given as standard wildcard expressions. You
+ can add a file extension to the filter using '+='. For example:
- \code
- header.fileextensions += *.H
- \endcode
-
- \warning The above assignment may not work as described.
+ \code
+ header.fileextensions += *.H
+ \endcode
- See also \l headerdirs.
+ \warning The above assignment may not work as described.
+ See also \l headerdirs.
\target imagedirs-variable
\section1 imagedirs
- The \c imagedirs variable specifies the directories
- containing the images used in the documentation.
+ The \c imagedirs variable specifies the directories containing the
+ images used in the documentation.
- The \l {images} {\c images} and \c imagedirs variables are
- used by the \l {image-command} {\\image} and \l
- {inlineimage-command} {\\inlineimage} commands. If both the \l
- {images} {\c images} and \c imagedirs variables are defined,
- QDoc will search in both, first in \l {images} {\c images}
- then in \c imagedirs.
+ The \l {images} {\c images} and \c imagedirs variables are used by
+ the \l {image-command} {\\image} and \l {inlineimage-command}
+ {\\inlineimage} commands. If both the \l {images} {\c images} and
+ \c imagedirs variables are defined, QDoc will search in both,
+ first in \l {images} {\c images} then in \c imagedirs.
- QDoc will search through the directories in the specified
- order, and accept the first matching file it finds. It will
- only search in the specified directories, \e not in
- subdirectories.
+ QDoc will search through the directories in the specified order,
+ and accept the first matching file it finds. It will only search
+ in the specified directories, \e not in subdirectories.
- For example:
-
- \code
- imagedirs = $QTDIR/doc/src/images \
- $QTDIR/examples
+ \code
+ imagedirs = $QTDIR/doc/src/images \
+ $QTDIR/examples
- images = $QTDIR/doc/src/images/calculator-example.png
- \endcode
+ images = $QTDIR/doc/src/images/calculator-example.png
+ \endcode
- When processing
+ When processing
- \code
- \image calculator-example.png
- \endcode
+ \code
+ \image calculator-example.png
+ \endcode
- QDoc will then see if there exists a file called
- calculator-example.png listed as a value in the \c images
- variable. If it doesn't, it will search in the \c imagedirs
- variable, and first see if there exists a file called
+ QDoc will then see if there exists a file called
+ calculator-example.png listed as a value in the \c images
+ variable. If it doesn't, it will search in the \c imagedirs
+ variable, and first see if there exists a file called
- \code
- $QTDIR/doc/src/images/calculator-example.png
- \endcode
+ \code
+ $QTDIR/doc/src/images/calculator-example.png
+ \endcode
- If it doesn't, QDoc will look for a file called
+ If it doesn't, QDoc will look for a file called
- \code
- $QTDIR/examples/calculator-example.png
- \endcode
-
- You can filter the images in an image directory using the
- \l {images.fileextensions} {\c images.fileextensions}
- variable. The general idea behind the \l
- {images.fileextensions} {\c images.fileextensions} variable
- is to enable different image format for different output
- format.
+ \code
+ $QTDIR/examples/calculator-example.png
+ \endcode
- \warning The \l {images.fileextensions} {\c
- images.fileextensions} variable's functionality is
- preliminay since QDoc at this point only support HTML.
+ You can filter the images in an image directory using the \l
+ {images.fileextensions} {\c images.fileextensions} variable. The
+ general idea behind the \l {images.fileextensions} {\c images.fileextensions}
+ variable is to enable different image format for different output format.
- See also \l images and \l images.fileextensions.
+ \warning The \l {images.fileextensions} {\c images.fileextensions}
+ variable's functionality is preliminay since QDoc at this point
+ only support HTML.
+ See also \l images and \l images.fileextensions.
\target images-variable
\section1 images
- The \c images variable allows you to specify individual
- image files in addition to those located in the directories
- specified by the \l {imagedirs} {\c imagedirs} variable.
-
- For example:
-
- \code
- images = $QTDIR/doc/src/images/calculator-example.png
- \endcode
+ The \c images variable allows you to specify individual image
+ files in addition to those located in the directories specified by
+ the \l {imagedirs} {\c imagedirs} variable.
- When processing the \c images variable, QDoc behaves in the
- same way as it does when processing the \l {imagedirs} {\c
- imagedirs} variable. For more information, see the \l
- {imagedirs} {\c imagedirs} variable.
+ \code
+ images = $QTDIR/doc/src/images/calculator-example.png
+ \endcode
- See also \l imagedirs and \l images.fileextensions.
+ When processing the \c images variable, QDoc behaves in the same
+ way as it does when processing the \l {imagedirs} {\c imagedirs}
+ variable. For more information, see the \l {imagedirs} {\c
+ imagedirs} variable.
+ See also \l imagedirs and \l images.fileextensions.
\target images.fileextensions-variable
\section1 images.fileextensions
- The images.fileextensions variable filters the files within
- an image directory.
-
- The variable's values (the extensions) are given as
- standard wildcard expressions. The general syntax is: \tt
- {images.fileextensions.\e{format} = *.\e{extension}}.
+ The images.fileextensions variable filters the files within an
+ image directory.
- The idea is to enable different image format for different
- output format. For example:
+ The variable's values (the extensions) are given as standard
+ wildcard expressions. The general syntax is: \tt
+ {images.fileextensions.\e{format} = *.\e{extension}}.
- \code
- images.fileextensions.HTML = *.png
- images.fileextensions.LOUT = *.eps
- \endcode
+ The idea is to enable different image format for different output
+ format.
- Then, when processing the \l {image-command} {\\image} and \l
- {inlineimage-command} {\\inlineimage} commands, QDoc will only
- search for files with extensions specified in the output
- format's associated image extension variable.
+ \code
+ images.fileextensions.HTML = *.png
+ images.fileextensions.LOUT = *.eps
+ \endcode
- \warning This is preliminary functionality since QDoc at
- this point only support HTML.
+ Then, when processing the \l {image-command} {\\image} and \l
+ {inlineimage-command} {\\inlineimage} commands, QDoc will only
+ search for files with extensions specified in the output format's
+ associated image extension variable.
- The default extensions for HTML are *.png, *.jpg, *.jpeg
- and *.gif.
+ \warning This is preliminary functionality since QDoc at this
+ point only support HTML.
- You can add a file extension to the filter using '+='. For
- example:
+ The default extensions for HTML are *.png, *.jpg, *.jpeg and
+ *.gif.
- \code
- images.fileextensions.HTML += *.eps
- \endcode
+ You can add a file extension to the filter using '+='. For
+ example:
- See also \l imagedirs and \l images.
+ \code
+ images.fileextensions.HTML += *.eps
+ \endcode
+ See also \l imagedirs and \l images.
\target language-variable
\section1 language
- The \c language variable specifies the language of the
- source code that is used in the documentation.
-
- Currently, C++ is the only language that QDoc
- understands. It is also the default language, and doesn't
- really need to be specified. But for example in \l
- qt.qdocconf:
+ The \c language variable specifies the language of the source code
+ that is used in the documentation.
- \code
- language = Cpp
- \endcode
+ Currently, C++ is the only language that QDoc understands. It is
+ also the default language, and doesn't really need to be
+ specified. But for example in \l qt.qdocconf:
- identifies the language of the Qt source code as C++.
+ \code
+ language = Cpp
+ \endcode
+ identifies the language of the Qt source code as C++.
\target macro-variable
\section1 macro
- The \c macro variable can be used to create your
- own QDoc commands.
-
- The general syntax is \tt {macro.\e{command} =
- "\e{definition}}". The definition can be described using
- QDoc syntax. In addition it is possible to provide an HTML
- definition by appending .HTML to the variable.
+ The \c macro variable can be used to create your own QDoc
+ commands.
- For example in \l qt.qdocconf:
+ The general syntax is \tt {macro.\e{command} =
+ "\e{definition}}". The definition can be described using QDoc
+ syntax. In addition it is possible to provide an HTML definition
+ by appending .HTML to the variable.
- \code
- macro.gui = "\\bold"
- macro.raisedaster.HTML = "<sup>*</sup>"
- \endcode
+ For example in \l qt.qdocconf:
- makes sure that the \\gui command renders its argument using a
- bold font, and that \\raisedaster renders a '*'.
+ \code
+ macro.gui = "\\bold"
+ macro.raisedaster.HTML = "<sup>*</sup>"
+ \endcode
+ makes sure that the \\gui command renders its argument using a
+ bold font, and that \\raisedaster renders a '*'.
\target naturallanguage-variable
\section1 naturallanguage
- The \c naturallanguage variable specifies the natural
- language used for the documentation generated by qdoc.
-
- For example:
-
- \code
- naturallanguage = zh-Hans
- \endcode
+ The \c naturallanguage variable specifies the natural language
+ used for the documentation generated by qdoc.
- By default, the natural language is \c en for compatibility
- with legacy documentation.
+ \code
+ naturallanguage = zh-Hans
+ \endcode
- qdoc will add the natural language information to the HTML
- it generates, using the \c lang and \c xml:lang attributes.
+ By default, the natural language is \c en for compatibility with
+ legacy documentation.
- See also \l {sourceencoding-variable} {sourceencoding},
- \l {outputencoding-variable} {outputencoding},
- \l{http://www.w3.org/TR/xhtml1/#C_7} {C.7. The lang and xml:lang Attributes} and
- \l{http://www.w3.org/TR/i18n-html-tech-lang/#ri20040429.113217290} {Best Practice 13: Using Hans and Hant codes}.
+ qdoc will add the natural language information to the HTML it
+ generates, using the \c lang and \c xml:lang attributes.
+ See also \l {sourceencoding-variable} {sourceencoding},
+ \l {outputencoding-variable} {outputencoding},
+ \l{http://www.w3.org/TR/xhtml1/#C_7}
+ {C.7. The lang and xml:lang Attributes} and
+ \l{http://www.w3.org/TR/i18n-html-tech-lang/#ri20040429.113217290}
+ {Best Practice 13: Using Hans and Hant codes}.
\target outputdir-variable
\section1 outputdir
- The \c outputdir variable specifies the directory
- where QDoc will put the generated documentation.
-
- In qt.qdocconf:
+ The \c outputdir variable specifies the directory where QDoc will
+ put the generated documentation.
- \code
- outputdir = $QTDIR/doc/html
- \endcode
+ In qt.qdocconf:
- locates the generated Qt reference documentation in
- $QTDIR/doc/html. For example, the documentation of the
- QWidget class is located in
+ \code
+ outputdir = $QTDIR/doc/html
+ \endcode
- \code
- $QTDIR/doc/html/qwidget.html
- \endcode
+ locates the generated Qt reference documentation in
+ $QTDIR/doc/html. For example, the documentation of the QWidget
+ class is located in
- The associated images will be put in an \c images subdirectory.
+ \code
+ $QTDIR/doc/html/qwidget.html
+ \endcode
- \warning When running QDoc multiple times using the same output
- directory, all files from the previous run will be lost.
+ The associated images will be put in an \c images subdirectory.
+ \warning When running QDoc multiple times using the same output
+ directory, all files from the previous run will be lost.
\target outputencoding-variable
\section1 outputencoding
- The \c outputencoding variable specifies the encoding
- used for the documentation generated by qdoc.
-
- For example:
+ The \c outputencoding variable specifies the encoding used for the
+ documentation generated by qdoc.
- \code
- outputencoding = UTF-8
- \endcode
-
- By default, the output encoding is \c ISO-8859-1 (Latin1) for
- compatibility with legacy documentation. When generating
- documentation for some languages, particularly non-European
- languages, this is not sufficient and an encoding such as UTF-8
- is required.
+ \code
+ outputencoding = UTF-8
+ \endcode
- qdoc will encode HTML using this encoding and generate the
- correct declarations to indicate to browsers which encoding
- is being used. The \l naturallanguage configuration variable
- should also be specified to provide browsers with a complete
- set of character encoding and language information.
+ By default, the output encoding is \c ISO-8859-1 (Latin1) for
+ compatibility with legacy documentation. When generating
+ documentation for some languages, particularly non-European
+ languages, this is not sufficient and an encoding such as UTF-8 is
+ required.
- See also \l outputencoding and \l naturallanguage.
+ qdoc will encode HTML using this encoding and generate the correct
+ declarations to indicate to browsers which encoding is being
+ used. The \l naturallanguage configuration variable should also be
+ specified to provide browsers with a complete set of character
+ encoding and language information.
+ See also \l outputencoding and \l naturallanguage.
\target outputformats-variable
\section1 outputformats
@@ -7314,28 +7509,24 @@
The \c outputformats variable specifies the format of
the generated documentation.
- Currently, QDoc only supports the HTML format. It is also
- the default format, and doesn't need to be specified.
-
+ Currently, QDoc only supports the HTML format. It is also
+ the default format, and doesn't need to be specified.
\target outputprefixes
\section1 outputprefixes
- The \c outputprefixes variable specifies a mapping between types of files
- and the prefixes to prepend to the HTML file names in the generated
- documentation.
-
- For example:
-
- \code
- outputprefixes = QML
- outputprefixes.QML = qt-components-
- \endcode
+ The \c outputprefixes variable specifies a mapping between types of files
+ and the prefixes to prepend to the HTML file names in the generated
+ documentation.
- By default, files containing the API documentation for QML elements
- or components are prefixed with "qml-". In the above example, the
- prefix "qt-components-" is used instead.
+ \code
+ outputprefixes = QML
+ outputprefixes.QML = qt-components-
+ \endcode
+ By default, files containing the API documentation for QML elements
+ or components are prefixed with "qml-". In the above example, the
+ prefix "qt-components-" is used instead.
\target qhp-variable
\section1 qhp
@@ -7351,92 +7542,80 @@
\section1 slow
The \c slow variable specifies whether QDoc should do
- time-consuming processing, such as syntax highlighting.
-
- By default, this setting is false.
+ time-consuming processing, such as syntax highlighting. The
+ default value is false.
- Example:
-
- This option has been replaced by the \l{syntaxhighlighing} option.
-
- For compatibility, the \c -slow command-line option has been
- retained. This has the effect of enabling syntax highlighting.
+ \note This option has been replaced by the \l{syntaxhighlighting} option.
+ For compatibility, the \c -slow command-line option has been
+ retained. This has the effect of enabling syntax highlighting.
\target sourcedirs-variable
\section1 sourcedirs
- The \c sourcedirs variable specifies the directories
- containing the \c .cpp or \c .qdoc files used in
- the documentation.
-
- For example in \l qt.qdocconf
+ The \c sourcedirs variable specifies the directories containing
+ the \c .cpp or \c .qdoc files used in the documentation.
- \code
- sourcedirs = $QTDIR/src \
- $QTDIR/doc/src \
- $QTDIR/extensions/activeqt \
- $QTDIR/extensions/motif \
- $QTDIR/tools/designer/src/lib/extension \
- $QTDIR/tools/designer/src/lib/sdk \
- $QTDIR/tools/designer/src/lib/uilib
- \endcode
+ For example in \l qt.qdocconf
- When executed, the first QDoc will do is to read through
- the headers specified in the \l {header-command} {\c header}
- variable, and the ones located in the directories specified
- in the \c headerdir variable (including all
- subdirectories), building an internal structure of the
- classes and their functions.
+ \code
+ sourcedirs = $QTDIR/src \
+ $QTDIR/doc/src \
+ $QTDIR/extensions/activeqt \
+ $QTDIR/extensions/motif \
+ $QTDIR/tools/designer/src/lib/extension \
+ $QTDIR/tools/designer/src/lib/sdk \
+ $QTDIR/tools/designer/src/lib/uilib
+ \endcode
- Then it will read through the sources specified in the \l
- {sources} {\c sources}, and the ones located in the
- directories specified in the \l {sourcedirs} {\c sourcedirs}
- varible (including all subdirectories), merging the
- documentation with the structure it retrieved from the
- header files.
+ When executed, the first QDoc will do is to read through the
+ headers specified in the \l {header-command} {\c header} variable,
+ and the ones located in the directories specified in the \c
+ headerdir variable (including all subdirectories), building an
+ internal structure of the classes and their functions.
- If both the \c sources and \c sourcedirs variables are
- defined, QDoc will read through both, first \l {sources} {\c
- sources} then \c sourcedirs.
+ Then it will read through the sources specified in the \l
+ {sources} {\c sources}, and the ones located in the directories
+ specified in the \l {sourcedirs} {\c sourcedirs} varible
+ (including all subdirectories), merging the documentation with the
+ structure it retrieved from the header files.
- In the specified directories, QDoc will only read the files
- with the fileextensions specified in the \l
- {sources.fileextensions} {\c sources.fileextensions}
- variable. The default extensions are *.c++, *.cc, *.cpp and
- *.cxx. The files specified by \l {sources} {\c sources} will
- be read independent of their fileextensions.
+ If both the \c sources and \c sourcedirs variables are defined,
+ QDoc will read through both, first \l {sources} {\c sources} then
+ \c sourcedirs.
- See also \l {sources-variable} {sources} and
- \l {sources.fileextensions-variable} {sources.fileextensions}.
+ In the specified directories, QDoc will only read the files with
+ the fileextensions specified in the \l {sources.fileextensions}
+ {\c sources.fileextensions} variable. The default extensions are
+ *.c++, *.cc, *.cpp and *.cxx. The files specified by \l {sources}
+ {\c sources} will be read independent of their fileextensions.
+ See also \l {sources-variable} {sources} and
+ \l {sources.fileextensions-variable} {sources.fileextensions}.
\target sourceencoding-variable
\section1 sourceencoding
- The \c sourceencoding variable specifies the encoding
- used for the source code and documentation.
-
- For example:
+ The \c sourceencoding variable specifies the encoding used for the
+ source code and documentation.
- \code
- sourceencoding = UTF-8
- \endcode
-
- By default, the source encoding is \c ISO-8859-1 (Latin1) for
- compatibility with legacy documentation. For some languages,
- particularly non-European languages, this is not sufficient
- and an encoding such as UTF-8 is required.
+ \code
+ sourceencoding = UTF-8
+ \endcode
- Although qdoc will use the encoding to read source and
- documentation files, limitations of C++ compilers may prevent
- you from using non-ASCII characters in source code comments.
- In cases like these, it is possible to write API documentation
- completely in documentation files.
+ By default, the source encoding is \c ISO-8859-1 (Latin1) for
+ compatibility with legacy documentation. For some languages,
+ particularly non-European languages, this is not sufficient and an
+ encoding such as UTF-8 is required.
- See also \l {naturallanguage-variable} {naturallanguage} and
- \l {outputencoding-variable} {outputencoding}.
+ Although qdoc will use the encoding to read source and
+ documentation files, limitations of C++ compilers may prevent you
+ from using non-ASCII characters in source code comments. In cases
+ like these, it is possible to write API documentation completely
+ in documentation files.
+ See also \l {naturallanguage-variable} {naturallanguage} and
+ \l {outputencoding-variable} {outputencoding}.
\target sources-variable
\section1 sources
@@ -7445,111 +7624,96 @@
files in addition to those located in the directories specified by
the \l {sourcedirs-variable} {sourcedirs} variable.
- For example:
-
- \code
- sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
- $QTDIR/src/gui/widgets/qpushbutton.cpp
- \endcode
-
- When processing the \c sources variable, QDoc behaves in the
- same way as it does when processing the \l {sourcedirs-variable}
- {sourcedirs} variable. For more information, see the \l
- {sourcedirs-variable} {sourcedirs} variable.
+ \code
+ sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
+ $QTDIR/src/gui/widgets/qpushbutton.cpp
+ \endcode
- See also \l {sourcedirs-variable} {sourcedirs}.
+ When processing the \c sources variable, QDoc behaves in the same
+ way as it does when processing the \l {sourcedirs-variable}
+ {sourcedirs} variable. For more information, see the \l
+ {sourcedirs-variable} {sourcedirs} variable.
+ See also \l {sourcedirs-variable} {sourcedirs}.
\target sources.fileextensions-variable
\section1 sources.fileextensions
- The \c sources.fileextensions variable filters the
- files within a source directory.
+ The \c sources.fileextensions variable filters the files within a
+ source directory.
- When processing the source files specified in the \l
- {sourcedirs} {\c sourcedirs} variable, QDoc will only read
- the files with the fileextensions specified in the \c
- sources.fileextensions variable. In this way QDoc avoid
- spending time reading irrelevant files.
+ When processing the source files specified in the \l {sourcedirs}
+ {\c sourcedirs} variable, QDoc will only read the files with the
+ fileextensions specified in the \c sources.fileextensions
+ variable. In this way QDoc avoid spending time reading irrelevant
+ files.
- The default extensions are *.c++, *.cc, *.cpp and *.cxx.
+ The default extensions are *.c++, *.cc, *.cpp and *.cxx.
- The extensions are given as standard wildcard expressions.
- You can add a file extension to the filter using '+='. For
- example:
+ The extensions are given as standard wildcard expressions. You
+ can add a file extension to the filter using '+='. For example:
- \code
- sources.fileextensions += *.CC
- \endcode
+ \code
+ sources.fileextensions += *.CC
+ \endcode
- \warning The above assignment may not work as described.
+ \warning The above assignment may not work as described.
- See also \l {sourcedirs-variable} {sourcedirs} and
- \l (sources-variable} {sources}.
+ See also \l {sourcedirs-variable} {sourcedirs} and \l
+ (sources-variable} {sources}.
\target spurious-variable
\section1 spurious
- The \c spurious variable excludes specified
- QDoc warnings from the output.
-
- The warnings are specified using standard wildcard
- expressions. For example:
+ The \c spurious variable excludes specified QDoc warnings from the
+ output. The warnings are specified using standard wildcard
+ expressions.
- \code
- spurious = "Cannot find .*" \
- "Missing .*"
- \endcode
+ \code
+ spurious = "Cannot find .*" \
+ "Missing .*"
+ \endcode
- makes sure that warnings matching either of these
- expressions, will not be part of the output when running
- QDoc. For example would the following warning be omitted
- from the output:
+ makes sure that warnings matching either of these expressions,
+ will not be part of the output when running QDoc. For example
+ would the following warning be omitted from the output:
- \code
- qt-4.0/src/opengl/qgl_mac.cpp:156: Missing parameter name
- \endcode
+ \code
+ qt-4.0/src/opengl/qgl_mac.cpp:156: Missing parameter name
+ \endcode
\target syntaxhighlighting
\section1 syntaxhighlighting
- The \c syntaxhighlighting variable specifies whether QDoc
- should perform syntax highlighting on source code quoted in the
- documentation it generates.
-
- For example:
-
- \code
- syntaxhighlighting = true
- \endcode
+ The \c syntaxhighlighting variable specifies whether QDoc should
+ perform syntax highlighting on source code quoted in the
+ documentation it generates.
- will enable syntax highlighting for all supported programming
- languages.
+ \code
+ syntaxhighlighting = true
+ \endcode
+ will enable syntax highlighting for all supported programming
+ languages.
\target tabsize-variable
\section1 tabsize
The \c tabsize variable defines the size of a tab character.
- For example:
-
- \code
- tabsize = 4
- \endcode
-
- will give the tab character the size of 4 spaces.
-
- The default value of the variable is 8, and doesn't need to
- be specified.
+ \code
+ tabsize = 4
+ \endcode
+ will give the tab character the size of 4 spaces. The default
+ value of the variable is 8, and doesn't need to be specified.
\target tagfile-variable
\section1 tagfile
-
- The \c tagfile variable specifies the Doxygen tag file to be written
- when HTML is generated.
+
+ The \c tagfile variable specifies the Doxygen tag file to be
+ written when HTML is generated.
\target version-variable
\section1 version
@@ -7557,54 +7721,47 @@
The \c version variable specifies the version number of the
documented software.
- For example:
-
- \code
- version = 4.0.1
- \endcode
-
- When a version number is specified (using the \tt{\l
- version} or \tt {\l versionsym} variables in a \c .qdocconf
- file), it is accessible through the corresponding \\version
- command for use in the documentation.
+ \code
+ version = 4.0.1
+ \endcode
- \warning The \\version command's functionality is not
- fully implemented; currently it only works within raw HTML
- code.
+ When a version number is specified (using the \tt{\l version} or
+ \tt {\l versionsym} variables in a \c .qdocconf file), it is
+ accessible through the corresponding \\version command for use in
+ the documentation.
- See also \l versionsym.
+ \warning The \\version command's functionality is not fully
+ implemented; currently it only works within raw HTML code.
+ See also \l versionsym.
\target versionsym-variable
\section1 versionsym
- The \c versionsym variable specifies a C++
- preprocessor symbol that defines the version number
- of the documented software.
-
- For example in \l qt.qdocconf:
-
- \code
- versionsym = QT_VERSION_STR
- \endcode
+ The \c versionsym variable specifies a C++ preprocessor symbol
+ that defines the version number of the documented software.
- QT_VERSION_STR is defined in qglobal.h as follows
+ For example in \l qt.qdocconf:
- \code
- #define QT_VERSION_STR "4.0.1"
- \endcode
+ \code
+ versionsym = QT_VERSION_STR
+ \endcode
- When a version number is specified (using the \tt{\l
- version} or \tt {\l versionsym} variables in a \c .qdocconf
- file), it is accessible through the corresponding \\version
- command for use in the documentation.
+ QT_VERSION_STR is defined in qglobal.h as follows
- \warning The \\version command's functionality is not fully
- implemented; currently it only works within raw HTML code.
+ \code
+ #define QT_VERSION_STR "4.0.1"
+ \endcode
- See also \l {version} {\\version}.
+ When a version number is specified (using the \tt{\l version} or
+ \tt {\l versionsym} variables in a \c .qdocconf file), it is
+ accessible through the corresponding \\version command for use in
+ the documentation.
+ \warning The \\version command's functionality is not fully
+ implemented; currently it only works within raw HTML code.
+ See also \l {version} {\\version}.
*/
/*!
@@ -7690,118 +7847,107 @@
\target Cpp.ignoredirectives-variable
\section1 Cpp.ignoredirectives
- The \c Cpp.ignoredirectives variable makes QDoc ignore
- the specified non-standard constructs, within C++ source code.
+ The \c Cpp.ignoredirectives variable makes QDoc ignore the
+ specified non-standard constructs, within C++ source code.
- If not specified by the \tt {\l Cpp.ignoretokens} or \tt
- {\l Cpp.ignoredirectives} variables, non-standard
- constructs (typically macros) can result in erroneous
- documentation.
+ If not specified by the \tt {\l Cpp.ignoretokens} or \tt {\l
+ Cpp.ignoredirectives} variables, non-standard constructs
+ (typically macros) can result in erroneous documentation.
- In \l qt.qdocconf:
+ In \l qt.qdocconf:
- \code
- Cpp.ignoredirectives = Q_DECLARE_INTERFACE \
- Q_DECLARE_OPERATORS_FOR_FLAGS \
- Q_DECLARE_PRIVATE \
- Q_DECLARE_PUBLIC \
- Q_DISABLE_COPY \
- Q_DUMMY_COMPARISON_OPERATOR \
- Q_ENUMS \
- Q_FLAGS \
- Q_INTERFACES \
- __attribute__
- \endcode
+ \code
+ Cpp.ignoredirectives = Q_DECLARE_INTERFACE \
+ Q_DECLARE_OPERATORS_FOR_FLAGS \
+ Q_DECLARE_PRIVATE \
+ Q_DECLARE_PUBLIC \
+ Q_DISABLE_COPY \
+ Q_DUMMY_COMPARISON_OPERATOR \
+ Q_ENUMS \
+ Q_FLAGS \
+ Q_INTERFACES \
+ __attribute__
+ \endcode
- makes sure that when processing the code below, for
- example, QDoc will simply ignore the 'Q_ENUMS' and
- 'Q_FLAGS' expressions:
+ makes sure that when processing the code below, for example, QDoc
+ will simply ignore the 'Q_ENUMS' and 'Q_FLAGS' expressions:
- \code
- class Q_CORE_EXPORT Qt {
- Q_OBJECT
- Q_ENUMS(Orientation TextFormat BackgroundMode
- DateFormat ScrollBarPolicy FocusPolicy
- ContextMenuPolicy CaseSensitivity
- LayoutDirection ArrowType)
- Q_ENUMS(ToolButtonStyle)
- Q_FLAGS(Alignment)
- Q_FLAGS(Orientations)
- Q_FLAGS(DockWidgetAreas)
-
- public:
- ...
- };
- \endcode
-
- The Q_OBJECT macro, however, is an exception: QDoc
- recognizes this particular non-standard construct, so there
- is no need specifying it using the \tt {\l
- Cpp.ignoredirectives} variable.
+ \code
+ class Q_CORE_EXPORT Qt {
+ Q_OBJECT
+ Q_ENUMS(Orientation TextFormat BackgroundMode
+ DateFormat ScrollBarPolicy FocusPolicy
+ ContextMenuPolicy CaseSensitivity
+ LayoutDirection ArrowType)
+ Q_ENUMS(ToolButtonStyle)
+ Q_FLAGS(Alignment)
+ Q_FLAGS(Orientations)
+ Q_FLAGS(DockWidgetAreas)
+
+ public:
+ ...
+ };
+ \endcode
- Regarding the Q_CORE_EXPORT macro; see the documentation of
- the \tt {\l Cpp.ignoretokens} variable.
+ The Q_OBJECT macro, however, is an exception: QDoc recognizes this
+ particular non-standard construct, so there is no need specifying
+ it using the \tt {\l Cpp.ignoredirectives} variable.
- See also \l Cpp.ignoretokens.
+ Regarding the Q_CORE_EXPORT macro; see the documentation of the
+ \tt {\l Cpp.ignoretokens} variable.
+ See also \l Cpp.ignoretokens.
\target Cpp.ignoretokens-variable
\section1 Cpp.ignoretokens
- The \c Cpp.ignoretokens variable makes QDoc ignore
- the specified non-standard constructs, within C++ source code.
+ The \c Cpp.ignoretokens variable makes QDoc ignore the specified
+ non-standard constructs, within C++ source code.
- If not specified by the \tt {\l Cpp.ignoretokens} or \tt
- {\l Cpp.ignoredirectives} variables, non-standard
- constructs (typically macros) can result in erroneous
- documentation.
+ If not specified by the \tt {\l Cpp.ignoretokens} or \tt {\l
+ Cpp.ignoredirectives} variables, non-standard constructs
+ (typically macros) can result in erroneous documentation.
- In \l qt.qdocconf:
+ In \l qt.qdocconf:
- \code
- Cpp.ignoretokens = QAXFACTORY_EXPORT \
- QM_EXPORT_CANVAS \
- ...
- Q_COMPAT_EXPORT \
- Q_CORE_EXPORT \
- Q_EXPLICIT \
- Q_EXPORT \
- ...
- Q_TYPENAME \
- Q_XML_EXPORT
- \endcode
-
- makes sure that when processing the code below, for
- example, QDoc will simply ignore the 'Q_CORE_EXPORT'
- expression:
-
- \code
- class Q_CORE_EXPORT Qt {
- Q_OBJECT
- Q_ENUMS(Orientation TextFormat BackgroundMode
- DateFormat ScrollBarPolicy FocusPolicy
- ContextMenuPolicy CaseSensitivity
- LayoutDirection ArrowType)
- Q_ENUMS(ToolButtonStyle)
- Q_FLAGS(Alignment)
- Q_FLAGS(Orientations)
- Q_FLAGS(DockWidgetAreas)
-
- public:
- ...
- };
- \endcode
+ \code
+ Cpp.ignoretokens = QAXFACTORY_EXPORT \
+ QM_EXPORT_CANVAS \
+ ...
+ Q_COMPAT_EXPORT \
+ Q_CORE_EXPORT \
+ Q_EXPLICIT \
+ Q_EXPORT \
+ ...
+ Q_TYPENAME \
+ Q_XML_EXPORT
+ \endcode
- Regarding the Q_OBJECT, Q_ENUMS and Q_FLAGS macros; see the
- documentation of the \tt {\l Cpp.ignoredirectives}
- variable.
+ makes sure that when processing the code below, for example, QDoc
+ will simply ignore the 'Q_CORE_EXPORT' expression:
- See also \l Cpp.ignoredirectives.
+ \code
+ class Q_CORE_EXPORT Qt {
+ Q_OBJECT
+ Q_ENUMS(Orientation TextFormat BackgroundMode
+ DateFormat ScrollBarPolicy FocusPolicy
+ ContextMenuPolicy CaseSensitivity
+ LayoutDirection ArrowType)
+ Q_ENUMS(ToolButtonStyle)
+ Q_FLAGS(Alignment)
+ Q_FLAGS(Orientations)
+ Q_FLAGS(DockWidgetAreas)
+ public:
+ ...
+ };
+ \endcode
+ Regarding the Q_OBJECT, Q_ENUMS and Q_FLAGS macros; see the
+ documentation of the \tt {\l Cpp.ignoredirectives} variable.
+ See also \l Cpp.ignoredirectives.
*/
-
/*!
\page 24-qdoc-configuration-htmlvariables.html
\previouspage C++ Specific Configuration Variables
@@ -7818,60 +7964,56 @@
\target HTML.footer-variable
\section1 HTML.footer
- The \c HTML.footer variable defines the content
- of the generated HTML documentation's footer.
+ The \c HTML.footer variable defines the content of the generated
+ HTML documentation's footer.
- The footer is rendered at the bottom of the generated
- documentation page.
-
- The variable's value is given as raw HTML code enclosed by
- quotation marks. Note that if the value spans several
- lines, each line needs to be enclosed by quotation marks.
+ The footer is rendered at the bottom of the generated
+ documentation page.
- For example in \l qt.qdocconf:
+ The variable's value is given as raw HTML code enclosed by
+ quotation marks. Note that if the value spans several lines, each
+ line needs to be enclosed by quotation marks.
- \code
- HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \
- ...
- "</tr></table></div></address>"
- \endcode
+ For example in \l qt.qdocconf:
- The complete variable entry in \l qt.qdocconf provides the
- standard footer of the \l
- {http://qt.nokia.com/doc/4.0/index.html} {Qt Reference
- Documentation}.
+ \code
+ HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \
+ ...
+ "</tr></table></div></address>"
+ \endcode
+ The complete variable entry in \l qt.qdocconf provides the
+ standard footer of the \l {http://qt.nokia.com/doc/4.0/index.html}
+ {Qt Reference Documentation}.
\target HTML.postheader-variable
\section1 HTML.postheader
- The \c HTML.postheader variable defines the content
- of the generated HTML documentation's postheader.
+ The \c HTML.postheader variable defines the content of the
+ generated HTML documentation's postheader.
- The header is rendered at the top of the generated
- documentation page.
+ The header is rendered at the top of the generated documentation
+ page.
- The variable's value is given as raw HTML enclosed by
- quotation marks. Note that if the value spans several
- lines, each line needs to be enclosed by quotation marks.
+ The variable's value is given as raw HTML enclosed by quotation
+ marks. Note that if the value spans several lines, each line needs
+ to be enclosed by quotation marks.
- For example in \l qt.qdocconf:
+ For example in \l qt.qdocconf:
- \code
- HTML.postheader = "<table border=\"0\"..." \
- ...
- "<img src=\"images/trolltech-logo.png\" \
- "align=\"right\" width=\"203\" height=\"32\""\
- "border=\"0\" />" \
- "</td></tr>" \
- "</table>"
- \endcode
-
- The complete variable entry in \l qt.qdocconf provides the
- standard header of the \l
- {http://qt.nokia.com/doc/4.0/index.html} {Qt Reference
- Documentation}.
+ \code
+ HTML.postheader = "<table border=\"0\"..." \
+ ...
+ "<img src=\"images/trolltech-logo.png\" \
+ "align=\"right\" width=\"203\" height=\"32\""\
+ "border=\"0\" />" \
+ "</td></tr>" \
+ "</table>"
+ \endcode
+ The complete variable entry in \l qt.qdocconf provides the
+ standard header of the \l {http://qt.nokia.com/doc/4.0/index.html}
+ {Qt Reference Documentation}.
\target HTML.style-variable
\section1 HTML.style
@@ -7879,27 +8021,26 @@
The HTML.style variable defines the style for
the generated HTML documentation.
- The variable's value is given as raw HTML enclosed by
- quotation marks. Note that if the value spans several
- lines, each line needs to be enclosed by quotation marks.
+ The variable's value is given as raw HTML enclosed by quotation
+ marks. Note that if the value spans several lines, each line needs
+ to be enclosed by quotation marks.
- For example in \l qt.qdocconf:
+ For example in \l qt.qdocconf:
- \code
- HTML.style = "h3.fn,span.fn" \
- "{ margin-left: 1cm; text-indent: -1cm; }\n" \
- "a:link { color: #004faf; text-decoration: none }\n" \
- "a:visited" \
- "{ color: #672967; text-decoration: none }\n" \
- "td.postheader { font-family: sans-serif }\n" \
- "tr.address { font-family: sans-serif }\n" \
- "body { background: #ffffff; color: black; }"
- \endcode
-
- provides the HTML style for the \l
- {http://qt.nokia.com/doc/4.0/index.html} {Qt Reference
- Documentation}.
+ \code
+ HTML.style = "h3.fn,span.fn" \
+ "{ margin-left: 1cm; text-indent: -1cm; }\n" \
+ "a:link { color: #004faf; text-decoration: none }\n" \
+ "a:visited" \
+ "{ color: #672967; text-decoration: none }\n" \
+ "td.postheader { font-family: sans-serif }\n" \
+ "tr.address { font-family: sans-serif }\n" \
+ "body { background: #ffffff; color: black; }"
+ \endcode
+ provides the HTML style for the \l
+ {http://qt.nokia.com/doc/4.0/index.html} {Qt Reference
+ Documentation}.
\target HTML.stylesheets-variable
\section1 HTML.stylesheets
@@ -7907,18 +8048,18 @@
The HTML.stylesheets variable defines a list of stylesheets
to use for the generated HTML documentation.
- Using separate stylesheets for the documentation makes it easier to
- customize and experiment with the style used once the contents has
- been generated. Typically, it is only necessary to define a single
- stylesheet for any set of documentation; for example:
+ Using separate stylesheets for the documentation makes it easier
+ to customize and experiment with the style used once the contents
+ has been generated. Typically, it is only necessary to define a
+ single stylesheet for any set of documentation; for example:
- \code
- HTML.stylesheets = classic.css
- \endcode
+ \code
+ HTML.stylesheets = classic.css
+ \endcode
- QDoc expects to find stylesheets in the directory containing the
- \l qt.qdocconf file, and it will copy those specified to the output
- directory alongside the HTML pages.
+ QDoc expects to find stylesheets in the directory containing the
+ \l qt.qdocconf file, and it will copy those specified to the output
+ directory alongside the HTML pages.
*/
@@ -7930,84 +8071,78 @@
\title Supporting Derived Projects
- Some particular configuration variables allow you to use QDoc to
- support Qt-based projects; i.e to make projects, such as Qt Solutions,
- contain references to the online Qt documentation. This
- means that QDoc will be able to create links to the class reference
- documentation, without any explicit linking command.
+ Some configuration variables allow you to use QDoc to support
+ Qt-based projects; i.e allow your project to contain links to the
+ online Qt documentation. This means that QDoc will be able to
+ create links to the class reference documentation, without any
+ explicit linking command.
\target description-variable
\section1 description
- The description variable holds a short description of
- the associated project.
-
- See also \l project.
+ The description variable holds a short description of the
+ associated project.
+ See also \l project.
\target indexes-variable
\section1 indexes
- The \c indexes variable lists the index files
- that will be used to generate references.
-
- For example. to make a derived Qt project contain links to
- the Qt Reference documentation, you need to specify the
- associated index file:
+ The \c indexes variable lists the index files that will be used to
+ generate references.
- \code
- indexes = $QTDIR/doc/html/qt.index
- \endcode
+ For example. to make a derived Qt project contain links to the Qt
+ Reference documentation, you need to specify the associated index
+ file:
- See also \l project and \l url.
+ \code
+ indexes = $QTDIR/doc/html/qt.index
+ \endcode
+ See also \l project and \l url.
\target project-variable
\section1 project
- The \c project variable provides a name for the project
- associated with the \c .qdocconf file.
+ The \c project variable provides a name for the project associated
+ with the \c .qdocconf file.
- The project's name is used to form a file name for the
- associated project's \e index file. For example:
+ The project's name is used to form a file name for the associated
+ project's \e index file.
- \code
- project = QtMotif
- \endcode
+ \code
+ project = QtMotif
+ \endcode
- This will cause an index file called \c qtmotif.index to be
- created.
+ This will cause an index file called \c qtmotif.index to be
+ created.
- See also \l description and \l indexes.
+ See also \l description and \l indexes.
\target url-variable
\section1 url
- The \c url variable holds the base URL for the
- reference documentation associated with the current project.
-
- The URL is stored in the generated index file for the
- project. When we use the index on its own, QDoc will use
- this as the base URL when constructing links to classes,
- functions, and other things listed in the index.
+ The \c url variable holds the base URL for the reference
+ documentation associated with the current project.
- For example:
+ The URL is stored in the generated index file for the
+ project. When we use the index on its own, QDoc will use this as
+ the base URL when constructing links to classes, functions, and
+ other things listed in the index.
- \code
- project = Qt
- description = Qt Reference Documentation
- url = http://qt.nokia.com/doc/4.0
-
- ...
- \endcode
-
- This makes sure that whenever \c qt.index is used to generate
- references to for example Qt classes, the base URL is
- \c http://qt.nokia.com/doc/4.0.
+ \code
+ project = Qt
+ description = Qt Reference Documentation
+ url = http://qt.nokia.com/doc/4.0
- See also \l indexes.
+ ...
+ \endcode
+ This makes sure that whenever \c qt.index is used to generate
+ references to for example Qt classes, the base URL is \c
+ http://qt.nokia.com/doc/4.0.
+ See also \l indexes.
\target howto
\section1 How to Support Derived Projects
@@ -8208,7 +8343,7 @@
\contentspage Table of Contents
\nextpage Topic Commands
- \title The QDoc Commands
+ \title Command Index
This is a complete, alphabetized list of the QDoc commands.
@@ -8227,6 +8362,7 @@
\o \l {07-0-qdoc-commands-includingexternalcode.html#codeline-command} {\\codeline},
\o \l {16-qdoc-commands-status.html#compat-command} {\\compat}
\o \l {15-qdoc-commands-navigation.html#contentspage-command} {\\contentspage}
+ \o \l {16-qdoc-commands-status.html#default-command} {\\default} \span {class="newStuff"} {(new)}
\o \l {04-qdoc-commands-textmarkup.html#div-command} {\\div} \span {class="newStuff"} {(new)}
\o \l {07-0-qdoc-commands-includingexternalcode.html#dots-command} {\\dots}
\o \l {12-0-qdoc-commands-miscellaneous.html#else-command} {\\else}
@@ -8247,6 +8383,7 @@
\o \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\include}
\o \l {15-qdoc-commands-navigation.html#indexpage-command} {\\indexpage}
\o \l {19-qdoc-commands-grouping.html#ingroup-command} {\\ingroup}
+ \o \l {18-qdoc-commands-relating.html#inherits-command}{\\inherits} \span {class="newStuff"} {(new)}
\o \l {19-qdoc-commands-grouping.html#inmodule-command} {\\inmodule}
\o \l {09-qdoc-commands-includingimages.html#inlineimage-command} {\\inlineimage}
\o \l {16-qdoc-commands-status.html#internal-command} {\\internal}
@@ -8276,6 +8413,13 @@
\o \l {07-0-qdoc-commands-includingexternalcode.html#printto-command} {\\printto}
\o \l {07-0-qdoc-commands-includingexternalcode.html#printuntil-command} {\\printuntil}
\o \l {13-qdoc-commands-topics.html#property-command} {\\property}
+ \o \l {13-qdoc-commands-topics.html#qmlattachedproperty-command} {\\qmlattachedproperty} \span {class="newStuff"} {(new)}
+ \o \l {13-qdoc-commands-topics.html#qmlattachedsignal-command} {\\qmlattachedsignal} \span {class="newStuff"} {(new)}
+ \o \l {13-qdoc-commands-topics.html#qmlbasictype-command} {\\qmlbasictype} \span {class="newStuff"} {(new)}
+ \o \l {13-qdoc-commands-topics.html#qmlclass-command} {\\qmlclass} \span {class="newStuff"} {(new)}
+ \o \l {13-qdoc-commands-topics.html#qmlmethod-command} {\\qmlmethod} \span {class="newStuff"} {(new)}
+ \o \l {13-qdoc-commands-topics.html#qmlproperty-command} {\\qmlproperty} \span {class="newStuff"} {(new)}
+ \o \l {13-qdoc-commands-topics.html#qmlsignal-command} {\\qmlsignal} \span {class="newStuff"} {(new)}
\o \l {11-qdoc-commands-specialcontent.html#quotation-command} {\\quotation}
\o \l {07-0-qdoc-commands-includingexternalcode.html#quotefile-command} {\\quotefile}
\o \l {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} {\\quotefromfile}
diff --git a/tools/qdoc3/htmlgenerator.cpp b/tools/qdoc3/htmlgenerator.cpp
index 69bd259..3e25cb7 100644
--- a/tools/qdoc3/htmlgenerator.cpp
+++ b/tools/qdoc3/htmlgenerator.cpp
@@ -79,9 +79,9 @@ QString HtmlGenerator::sinceTitles[] =
" New Properties",
" New Variables",
" New QML Elements",
- " New Qml Properties",
- " New Qml Signals",
- " New Qml Methods",
+ " New QML Properties",
+ " New QML Signals",
+ " New QML Methods",
""
};
generated by cgit v0.12 at 2024-11-19 15:37:19 (GMT)