|
|
| (10 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| {{Cleanup | reason=Auto-imported from ExpressionEngine.}}
| | [[Category:Writing Guidelines]] |
| | | This page is now at [[QML Documentation Style]] |
| = QML Documentation Style =
| |
| This page is part of the [[QtWritingGuidelines| Qt Writing Guidelines]].
| |
| | |
| Though there are exceptions, these guidelines should be followed. Keeping that in mind, at least '''be consistent within the page'''. Meaning, the class member documentation should have the same style.
| |
| | |
| 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 [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html topic commands]:
| |
| | |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlattachedproperty ]
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlattachedsignal ]
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlattachedsignal ]
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmltype ]
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlmethod ]
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlproperty ]
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlsignal ]
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlmodule ]
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#inqmlmodule ]
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#instantiates ]
| |
| | |
| 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.
| |
| | |
| == QML Module Versions ==
| |
| | |
| QDoc considers the version specified in the command as the import statement. Types which belong to the module do not need to specify the version, only the module name.
| |
| | |
| <code>
| |
| | |
| /*!
| |
| QtQuick.Controls 1.1
| |
| #this is the same as the import statement
| |
| | |
| */
| |
| | |
| /*!
| |
| Button
| |
| QtQuick.Controls
| |
| #QDoc will associate this Button to whatever version QtQuick.Controls has. (only one version per release)
| |
| | |
| */
| |
| </code>
| |
| | |
| There are two versions important for the user to know: Qt version and QML module version.
| |
| | |
| Use
| |
| ''' "5.3" for "<qml module> <version>" for and the members.
| |
| | |
| "QtQuick 2.3" in a property documentation block will generate: "This property was introduced in QtQuick 2.3"
| |
| | |
| == QML Types ==
| |
| | |
| The [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmltype-command ] command is for QML type documentation.
| |
| | |
| <code>
| |
| TextEdit
| |
| QQuickTextEdit
| |
| QtQuick
| |
| 4.8
| |
| qtquick-visual
| |
| qtquick-input
| |
| Item
| |
| Displays multiple lines of editable formatted text
| |
| | |
| The TextEdit item displays a block of editable, formatted text.
| |
| | |
| It can display both plain and rich text. For example:
| |
| | |
| TextEdit {
| |
| width: 240
| |
| text: "<b>Hello</b> <i>World!</i>"
| |
| font.family: "Helvetica"
| |
| font.pointSize: 20
| |
| color: "blue"
| |
| focus: true
| |
| }
| |
|
| |
| | |
| declarative-textedit.gif
| |
| | |
| … omitted detailed description
| |
| | |
| Text, TextInput, {examples/quick/text/textselection}{Text Selection example}
| |
| </code>
| |
| | |
| Some commonly used commands and [http://doc-snapshot.qt.io/qt5-stable/14-qdoc-commands-contextcommands.html context commands]:
| |
| * [http://doc-snapshot.qt.io/qt5-stable/11-qdoc-commands-specialcontent.html#brief-command ] - the brief description '''mandatory'''
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#inqmlmodule-command ] '''mandatory'''
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#instantiates-command ] - accepts the C++ class which implements the QML type as the argument. For types implemented in QML, this is not needed.
| |
| * [http://doc-snapshot.qt.io/qt5-stable/16-qdoc-commands-status.html#since-command ] - Add the Qt version the type was introduced in. '''mandatory''' (see '''Note:''' below about backdating APIs)
| |
| | |
| '''Note:''' It was decided that we will not backdate APIs, so only add the with the version number of an upcoming release. See https://codereview.qt.io/#change,43797
| |
| | |
| 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. '''Don't forget the period at the end.'''
| |
| | |
| <code>
| |
| ColorAnimation
| |
| Animates changes in color values.
| |
| </code>
| |
| | |
| Here are some alternate verbs for the brief statement:
| |
| * "Provides…"
| |
| * "Specifies…"
| |
| * "Describes…"
| |
| | |
| The '''detailed description''' follows the brief and may contain images, snippet, and link to other documentation.
| |
| | |
| == Properties ==
| |
| | |
| The property description focuses on what the property ''does''. Property documentation usually starts with "This property…" but for certain properties, these are the common expressions:
| |
| * "This property holds…"
| |
| * "This property describes…"
| |
| * "This property represents…"
| |
| * "Returns rue when… and alse when…" - for properties that are marked ''read-only''.
| |
| * "Sets the…" - for properties that configure a type.
| |
| | |
| == Aliases ==
| |
| | |
| The QDoc parser cannot guess the type of the alias, therefore, the type must be fully documented with the [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlproperty ] command.
| |
| | |
| == Signals and Handlers Documentation ==
| |
| | |
| QML signals are documented either in the QML file or in the C++ implementation with the [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlsignal-command ] command. Signal documentation must include the condition for emitting the signal, mention the corresponding signal handler, and document whether the signal accepts a parameter.
| |
| | |
| <code>
| |
| /*
| |
| 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
| |
| nClicked.
| |
| */
| |
| </code>
| |
| | |
| These are the possible documentation styles for signals:
| |
| ''' "This signal is triggered when…"
| |
| * "Triggered when…"
| |
| * "Emitted when…"
| |
| | |
| == Read-Only Properties ==
| |
| | |
| To mark that a property is a ''read-only'' property, typethe * command in the property documentation. QDoc then notes that the property is a read-only property.
| |
| | |
| For properties that are declared in QML files with the '''readonly''' keyword, QDoc can detect that it is a read-only property and will automatically add the read-only marking.
| |
| | |
| == Methods and JavaScript Functions ==
| |
| | |
| Typically, function documentation immediately precedes the implementation of the function in the ''.cpp'' file. The [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html topic command] for functions is [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlmethod-command ]. 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.
| |
| | |
| <code>
| |
| /*
| |
| QtQuick2::ListModel::remove(int index, int count = 1)
| |
| | |
| Deletes the content at index from the model.
| |
| | |
| clear()
| |
| */
| |
| void QQuickListModel::remove(QQmlV8Function '''args)
| |
| </code>
| |
| | |
| Some common verbs for function documentation:
| |
| ''' "Copies…" - for constructors
| |
| * "Destroys…" - for destructors
| |
| * "Returns…" - for accessor functions
| |
| | |
| The function documentation must document:
| |
| * the return type
| |
| * the parameters
| |
| * the actions of the functions
| |
| | |
| The [http://doc-snapshot.qt.io/qt5-stable/04-qdoc-commands-textmarkup.html#a-command ] command marks the parameter in the documentation. The return type documentation should link to the type documentation or be marked with the [http://doc-snapshot.qt.io/qt5-stable/04-qdoc-commands-textmarkup.html#c-command ] command in the case of boolean values.
| |
| | |
| == Enumerations ==
| |
| | |
| QML enumerations are documented as QML properties with the [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlproperty-command ] command. The type of the property is ''enumeration''.
| |
| | |
| <code>
| |
| /*!
| |
| enumeration QtQuick2::Text::font.weight
| |
| | |
| Sets the font's weight.
| |
| | |
| The weight can be one of:
| |
| | |
| Font.Light
| |
| Font.Normal - the default
| |
| Font.DemiBold
| |
| Font.Bold
| |
| Font.Black
| |
| */
| |
| </code>
| |
| | |
| To begin the description, use:
| |
| ''' "This enumeration…"
| |