whytofly
/
qt6-bb10
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

qdoc: Updated qdoc manual and qdoc guide 

These documents now include the \qmltype and
\instantiates commands, and the \qmlclass command
is deprecated.

Task nr: QTBUG-26648

Change-Id: I62da273be51609e651e33b9088e1667e4c6c1e76
Reviewed-by: Jerome Pasion <jerome.pasion@nokia.com>
bb10
Martin Smith 2012-07-27 12:22:05 +02:00 committed by Qt by Nokia
parent 022f8ebd13
commit be46199c62
6 changed files with 143 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/tools/qdoc/doc/examples/componentset/ProgressBar.qml
View File

@ -41,7 +41,7 @@
import QtQuick 1.0
/*!
\qmlclass ProgressBar
\qmltype ProgressBar
\inqmlmodule UIComponents 1.0
\brief A component that shows the progress of an event

2
src/tools/qdoc/doc/examples/componentset/Switch.qml
View File

@ -41,7 +41,7 @@
import QtQuick 1.0
/*!
\qmlclass ToggleSwitch
\qmltype ToggleSwitch
\inqmlmodule UIComponents 1.0
\brief A component that can be turned on or off

2
src/tools/qdoc/doc/examples/componentset/TabWidget.qml
View File

@ -41,7 +41,7 @@
import QtQuick 1.0
/*!
\qmlclass TabWidget
\qmltype TabWidget
\inqmlmodule UIComponents 1.0
\brief A widget that places its children as tabs

2
src/tools/qdoc/doc/examples/examples.qdoc
View File

@ -43,7 +43,7 @@
\section1 QML Class
The QML types use the \l{qmlclass-command}{\\qmlclass} to document the
The QML types use the \l{qmltype-command}{\\qmltype} to document the
type. In addition, they have the \l{inmodule-command}{\\inmodule}
command in order for QDoc to associate them to the \c UIComponents module.

34
src/tools/qdoc/doc/qdoc-guide.qdoc
View File

@ -295,7 +295,7 @@
\list
\li \l{enum-command}{\\enum} - for enumeration documentation
\li \l{class-command}{\\class} - for C++ class documentation
\li \l{qmlclass-command}{\\qmlclass} - for QML type documentation
\li \l{qmltype-command}{\\qmltype} - for QML type documentation
\li \l{page-command}{\\page} - for creating a page.
\endlist
@ -453,13 +453,14 @@
\li \l{qmlattachedproperty-command}{\\qmlattachedproperty}
\li \l{qmlattachedsignal-command}{\\qmlattachedsignal}
\li \l{qmlbasictype-command}{\\qmlbasictype}
\li \l{qmlclass-command}{\\qmlclass} - creates a QML type documentation
\li \l{qmltype-command}{\\qmltype} - creates a QML type documentation
\li \l{qmlmethod-command}{\\qmlmethod}
\li \l{qmlproperty-command}{\\qmlproperty}
\li \l{qmlsignal-command}{\\qmlsignal}
\li \l{inherits-command}{\\inherits}
\li \l{qmlmodule-command}{\\qmlmodule}
\li \l{inqmlmodule-command}{\\inqmlmodule}
\li \l{instantiates-command}{\\instantiates}
\endlist
@ -467,18 +468,20 @@
the \l{qdoc-input-output-dir}{fileextension} variable.
To document a QML type, start by creating a QDoc comment that uses the
\l{qmlclass-command} {\\qmlclass} command as its topic command.
\l{qmltype-command} {\\qmltype} command as its topic command.
\section3 QML Parser
If your QML type is defined in a \e qml file, document it there.
If your QML type is represented by a C++ class, document it in the
\e cpp file for that C++ class. Don't document a QML type in a
\e{cpp} file if the QML type is defined in a \e{qml} file.
\e cpp file for that C++ class and include an
\l{instantiates-command}{\\instantiates} command to specify the
name of the C++ class. Don't document a QML type in a \e{cpp} file
if the QML type is defined in a \e{qml} file.
When documenting a QML type in a \e{qml} file, place each QDoc
comment directly above the entity to which the comment applies.
For example, place the QDoc comment containing the \e{\\qmlclass}
For example, place the QDoc comment containing the \e{\\qmltype}
command (the topic comment) directly above the outer QML type in
the \e{qml} file. Place the comment for documenting a QML property
directly above the property declaration, and so on for QML signal
@ -504,8 +507,8 @@
does not use the QML parser to parse these files (the C++ parser
is used), so these QML QDoc comments can appear anywhere in the
\e{cpp} file. Note that QML QDoc comments in \e cpp files \e must
use the QML topic commands. i.e., the \l{qmlclass-command}
{\\qmlclass} command \e must appear in the QDoc comment for the
use the QML topic commands. i.e., the \l{qmltype-command}
{\\qmltype} command \e must appear in the QDoc comment for the
QML type, and a \l{qmlproperty-command} {\\qmlproperty} command \e
must appear in each QML property QDoc comment.
@ -517,14 +520,15 @@
to the QtQuick2 module while there is also a QtQuick1 module for the older
types introduced in Qt 4.
Modules affect the way QDoc link and relate the types. The
\l{qmlclass-command}{\\qmlclass} topic command must have an
\l{inqmlmodule-command}{\\inqmlmodule} context command to relate the
type to a module. Similarly, a \l{qmlmodule-command}{\\qmlmodule} topic
command must exist in a separate \c .qdoc file to create the overview page
for the module. The overview page will list the related types.
QML modules allow grouping QML types. The \l{qmltype-command}
{\\qmltype} topic command must have an \l{inqmlmodule-command}
{\\inqmlmodule} context command to relate the type to a QML
module. Similarly, a \l{qmlmodule-command}{\\qmlmodule} topic
command must exist in a separate \c{.qdoc} file to create the
overview page for the module. The overview page will list the
QML types of the QML module.
The links to the QML types, must therefore, also contain the module name.
The links to the QML types must therefore also contain the module name.
For example, if a type called \c TabWidget is in the \c UIComponents
module, it must be linked as \c {UIComponents::TabWidget}.

127
src/tools/qdoc/doc/qdoc-manual.qdoc
View File

@ -3525,9 +3525,10 @@
* /
\endcode
This generates a list of all the classes in the \e{draganddrop} group.
A class in the \e{draganddrop} group will have the \\ingroup command
in its \\class or \\qmlclass comment.
This generates a list of all the C++ classes and/or QML types in
the \e{draganddrop} group. A C++ class or QML type in the
\e{draganddrop} group will have \e{\\ingroup draganddrop} in its
\e{\\class} or \e{\\qmltype} comment.
\target generatelist-command
@ -5428,6 +5429,9 @@
\target qmlclass-command
\section1 \\qmlclass
This command is deprecated. Use \l{qmltype-command} {\\qmltype}
instead.
The \\qmlclass command is for documenting a QML type that is
instantiated by a C++ class. The command has two arguments. The
first argument is the name of the QML type. The second argument
@ -5497,6 +5501,82 @@
\l{http://doc.qt.nokia.com/4.7/qml-textinput.html#select-method}
{TextInput} element.
\target qmltype-command
\section1 \\qmltype
The \\qmltype command is for documenting a QML type. The command
has one argument, which is the name of the QML type.
If the QML type is instantiated by a C++ class, that class must be
specified using the \l{instantiates-command} {\\instantiates}
context command.
\code
/ *!
\qmltype Transform
\instantiates QGraphicsTransform
\ingroup qml-transform-elements
\since 4.7
\brief The Transform elements provide a way to build
advanced transformations on Items.
The Transform element is a base type which cannot be
instantiated directly. The concrete Transform types are:
\list
\li \l Rotation
\li \l Scale
\li \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
The example generates the \l
{http://doc.qt.nokia.com/4.7/qml-transform.html} {QML Transform}
page. The \e{\\qmltype} comment includes \l{instantiates-command}
{\\instantiates} to specify that a Transform is instantiated by
the C++ class QGraphicsTransform. A \\qmltype comment should
always include a \l {since-command} {\\since} command, because all
QML types are new. It should also include a \l{brief-command}
{\\brief} description. And if a QML type is a member of a group of
QML types, the \\qmltype comment should include one or more
\l{ingroup-command} {\\ingroup} commands.
\target qmlmethod-command
\section1 \\qmlmethod
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.qt.nokia.com/4.7/qml-textinput.html#select-method}
{TextInput} element.
\target qmlproperty-command
\section1 \\qmlproperty
@ -5579,7 +5659,7 @@
colons (\c{::}).
\code
\qmlclass ClickableButton
\qmltype ClickableButton
\inqmlmodule ClickableComponents
A clickable button that responds to the \c click() event.
@ -5591,6 +5671,36 @@
The \l{componentset}{UIComponents} example demonstrates proper usage of
QDoc commands to document QML types and QML modules.
\target instantiates-command
\section1 \\instantiates
The \\instantiates command is used in the \l{qmltype-command} {QML
type} comment of an elemental QML type to specify the name of the
C++ class that instantiates the QML type.
If the QML type is not instantiated by a C++ class, this command
is not used.
\code
/ *!
\qmltype Transform
\instantiates QGraphicsTransform
\ingroup qml-transform-elements
\since 4.7
\brief The Transform elements provide a way to build
advanced transformations on Items.
The Transform element is a base type which cannot be
instantiated directly.
* /
\endcode
The example generates the \l
{http://doc.qt.nokia.com/4.7/qml-transform.html} {QML Transform}
page. The \e{\\qmltype} comment includes \l{instantiates-command}
{\\instantiates} to specify that a Transform is instantiated by
the C++ class QGraphicsTransform. A \\qmltype comment should
\target typedef-command
\section1 \\typedef
@ -6522,12 +6632,13 @@
The \\inherits command is for documenting that one QML type
inherits some other QML type. It must be included in the
inheriting element's \l{qmlclass-command}{\\qmlclass} comment.
inheriting element's \l{qmltype-command}{\\qmltype} comment.
The argument is the name of the inherited QML type.
\code
/ *!
\qmlclass PauseAnimation QDeclarativePauseAnimation
\qmltype PauseAnimation
\instantiates QDeclarativePauseAnimation
\ingroup qml-animation-transition
\since 4.7
\inherits Animation
@ -8686,12 +8797,14 @@
\li \l {13-qdoc-commands-topics.html#qmlattachedproperty-command} {\\qmlattachedproperty}
\li \l {13-qdoc-commands-topics.html#qmlattachedsignal-command} {\\qmlattachedsignal}
\li \l {13-qdoc-commands-topics.html#qmlbasictype-command} {\\qmlbasictype}
\li \l {13-qdoc-commands-topics.html#qmlclass-command} {\\qmlclass}
\li \l {13-qdoc-commands-topics.html#qmlclass-command} {\\qmlclass} \span {class="newStuff"} {(deprecated, use \\qmltype)}
\li \l {13-qdoc-commands-topics.html#qmltype-command} {\\qmltype} \span {class="newStuff"} {(new 27/7/2012)}
\li \l {13-qdoc-commands-topics.html#qmlmethod-command} {\\qmlmethod}
\li \l {13-qdoc-commands-topics.html#qmlproperty-command} {\\qmlproperty}
\li \l {13-qdoc-commands-topics.html#qmlsignal-command} {\\qmlsignal}
\li \l {13-qdoc-commands-topics.html#qmlmodule-command} {\\qmlmodule}
\li \l {13-qdoc-commands-topics.html#inqmlmodule-command} {\\inqmlmodule}
\li \l {13-qdoc-commands-topics.html#instantiates-command} {\\instantiates} \span {class="newStuff"} {(new 27/7/2012)}
\li \l {11-qdoc-commands-specialcontent.html#quotation-command} {\\quotation}
\li \l {07-0-qdoc-commands-includingexternalcode.html#quotefile-command} {\\quotefile}
\li \l {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} {\\quotefromfile}