QDoc can process QML types defined as C++ classes and QML types defined in
.qml
files. For C++ classes documented as QML types, the QDoc comments are in the
.cpp
file while QML types defined in QML are in the
.qml
file. The C++ classes must also be documented documented with the QML
topic commands
:
For QML types defined in
.qml
files, QDoc will parse the QML and determine the properties, signals, and the type within the QML definition. The QDoc block then needs to be immediately above the declaration. For QML types implemented in C++, QDoc will output warnings if the C++ class documentation does not exist. The class documentation may be marked as
internal
if it is not a public API.
The \qmltype command is for QML type documentation.
\qmltype TextEdit
\instantiates QQuickTextEdit
\inqmlmodule QtQuick
\ingroup qtquick-visual
\ingroup qtquick-input
\inherits Item
\brief Displays multiple lines of editable formatted text
TextEdit 项显示可编辑的格式化文本块。
它可以显示纯文本和富文本。例如：
\qml
TextEdit {
width: 240
text: "<b>Hello</b> <i>World!</i>"
font.family: "Helvetica"
font.pointSize: 20
color: "blue"
focus: true
}
\endqml
\image declarative-textedit.gif
... omitted detailed description
\sa Text, TextInput, {examples/quick/text/textselection}{Text Selection example}
The \instantiates accepts the C++ class which implements the QML type as the argument. For types implemented in QML, this is not needed.
The brief description provides a summary for the QML type. The brief does not need to be a complete sentence and may start with a verb. QDoc will append the brief description onto the QML type in tables and generated lists.
\qmltype ColorAnimation \brief Animates changes in color values
Here are some alternate verbs for the brief statement:
The detailed description follows the brief and may contain images, snippet, and link to other documentation.
The property description focuses on what the property does and may use the following style:
Property documentation usually starts with "This property..." but for certain properties, these are the common expressions:
true
when... and
false
when..." - for properties that are marked
只读
.
QML signals are documented either in the QML file or in the C++ implementation with the \qmlsignal command. Signal documentation must include the condition for emitting the signal, mention the corresponding signal handler, and document whether the signal accepts a parameter.
/*
This signal is emitted when the user clicks the button. A click is defined
as a press followed by a release. The corresponding handler is
\c onClicked.
*/
signal clicked()
These are the possible documentation styles for signals:
Typically, function documentation immediately precedes the implementation of the function in the
.cpp
file. The
topic command
for functions is
\fn
. For functions in QML or JavaScript, the documentation must reside immediately above the function declaration.
The function documentation starts with a verb, indicating the operation the function performs.
/*
\qmlmethod QtQuick2::ListModel::remove(int index, int count = 1)
Deletes the content at \a index from the model.
\sa clear()
*/
void QQuickListModel::remove(QQmlV8Function *args)
Some common verbs for function documentation:
The function documentation must document:
The \a command marks the parameter in the documentation. The return type documentation should link to the type documentation or be marked with the \c command in the case of boolean values.
QML enumerations are documented as QML properties with the
\qmlproperty
command. The type of the property is
enumeration
.
/*! \qmlproperty enumeration QtQuick2::Text::font.weight Sets the font's weight. The weight can be one of: \list \li Font.Light \li Font.Normal - the default \li Font.DemiBold \li Font.Bold \li Font.Black \endlist */
The QDoc comment lists the values of the enumeration. If the enumeration is implemented in C++, the documentation may link to the corresponding C++ enumeration. However, the QDoc comment should advise that the enumeration is a C++ enumeration.