|
|
| (15 intermediate revisions by 7 users not shown) |
| Line 1: |
Line 1: |
| =<span class="caps">QML</span> Documentation Style=
| | [[Category:Writing Guidelines]] |
| | | This page is now at [[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 <span class="caps">QML</span> types defined as C++ classes and <span class="caps">QML</span> types defined in ''.qml'' files. For C++ classes documented as <span class="caps">QML</span> types, the QDoc comments are in the ''.cpp'' file while <span class="caps">QML</span> types defined in <span class="caps">QML</span> are in the ''.qml'' file. The C++ classes must also be documented documented with the <span class="caps">QML</span> [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html topic commands] ''[doc-snapshot.qt.io]'':
| |
| | |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlattachedproperty \qmlattachedproperty] ''[doc-snapshot.qt.io]''
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlattachedsignal \qmlattachedsignal] ''[doc-snapshot.qt.io]''
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlattachedsignal \qmlbasictype] ''[doc-snapshot.qt.io]''
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmltype \qmltype] ''[doc-snapshot.qt.io]''
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlmethod \qmlmethod] ''[doc-snapshot.qt.io]''
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlproperty \qmlproperty] ''[doc-snapshot.qt.io]''
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlsignal \qmlsignal] ''[doc-snapshot.qt.io]''
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlmodule \qmlmodule] ''[doc-snapshot.qt.io]''
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#inqmlmodule \inqmlmodule] ''[doc-snapshot.qt.io]''
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#instantiates \instantiates] ''[doc-snapshot.qt.io]''
| |
| | |
| For <span class="caps">QML</span> types defined in ''.qml'' files, QDoc will parse the <span class="caps">QML</span> and determine the properties, signals, and the type within the <span class="caps">QML</span> definition. The QDoc<br /> block then needs to be immediately above the declaration. For <span class="caps">QML</span> types implemented in C++, QDoc will output warnings if the C++ class documentation does not exist.
| |
| | |
| ==<span class="caps">QML</span> Module Versions==
| |
| | |
| QDoc considers the version specified in the \qmlmodule command as the import statement. Types which belong to the module do not need to specify the version, only the module name.
| |
| | |
| There are two versions important for the user to know: Qt version and <span class="caps">QML</span> module version.
| |
| | |
| Use
| |
| | |
| * “\since 5.3” for \qmltype
| |
| * “\since <qml module> <version>” for \qmlproperty and the members.
| |
| | |
| “\since QtQuick 2.3” in a property documentation block will generate: “This property was introduced in QtQuick 2.3”
| |
| | |
| ==<span class="caps">QML</span> Types==
| |
| | |
| The [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmltype-command \qmltype] ''[doc-snapshot.qt.io]'' command is for <span class="caps">QML</span> type documentation.
| |
| | |
| Some commonly used commands and [http://doc-snapshot.qt.io/qt5-stable/14-qdoc-commands-contextcommands.html context commands] ''[doc-snapshot.qt.io]'':
| |
| | |
| * [http://doc-snapshot.qt.io/qt5-stable/11-qdoc-commands-specialcontent.html#brief-command \brief] ''[doc-snapshot.qt.io]'' – the brief description '''mandatory'''
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#inqmlmodule-command \inqmlmodule] ''[doc-snapshot.qt.io]'' '''mandatory'''
| |
| * [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#instantiates-command \instantiates] ''[doc-snapshot.qt.io]'' – accepts the C++ class which implements the <span class="caps">QML</span> type as the argument. For types implemented in <span class="caps">QML</span>, this is not needed.
| |
| * [http://doc-snapshot.qt.io/qt5-stable/16-qdoc-commands-status.html#since-command \since] ''[doc-snapshot.qt.io]'' – Add the Qt version the type was introduced in. '''mandatory''' (see '''Note:''' below about backdating <span class="caps">API</span>s)
| |
| | |
| '''Note:''' It was decided that we will not backdate <span class="caps">API</span>s, so only add the \since with the version number of an upcoming release. See https://codereview.qt.io/#change,43797
| |
| | |
| The '''brief description''' provides a summary for the <span class="caps">QML</span> 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 <span class="caps">QML</span> type in tables and generated lists. '''Don’t forget the period at the end.'''
| |
| | |
| 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 \c true when… and \c false 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 \qmlproperty] ''[doc-snapshot.qt.io]'' command.
| |
| | |
| ==Signals and Handlers Documentation==
| |
| | |
| <span class="caps">QML</span> signals are documented either in the <span class="caps">QML</span> file or in the C++ implementation with the [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlsignal-command \qmlsignal] ''[doc-snapshot.qt.io]'' command. Signal documentation must include the condition for emitting the signal, mention the corresponding signal handler, and document whether the signal accepts a parameter.
| |
| | |
| 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 '''\readonly''' command in the property documentation. QDoc then notes that the property is a read-only property.
| |
| | |
| For properties that are declared in <span class="caps">QML</span> 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] ''[doc-snapshot.qt.io]'' for functions is [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlmethod-command \qmlmethod] ''[doc-snapshot.qt.io]''. For functions in <span class="caps">QML</span> or JavaScript, the documentation must reside immediately above the function declaration.
| |
| | |
| The function documentation starts with a verb, indicating the operation the function performs.
| |
| | |
| 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 \a] ''[doc-snapshot.qt.io]'' 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 \c] ''[doc-snapshot.qt.io]'' command in the case of boolean values.
| |
| | |
| ==Enumerations==
| |
| | |
| <span class="caps">QML</span> enumerations are documented as <span class="caps">QML</span> properties with the [http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmlproperty-command \qmlproperty] ''[doc-snapshot.qt.io]'' command. The type of the property is ''enumeration''.
| |
| | |
| To begin the description, use:
| |
| | |
| * “This enumeration…”
| |
| | |
| 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.
| |