QMLDocumentationStyle: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
 
No edit summary
 
(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 &lt;qml module&gt; &lt;version&gt;” 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.

Latest revision as of 12:18, 6 December 2024

This page is now at QML Documentation Style

Retrieved from "https://wiki.qt.io/index.php?title=QMLDocumentationStyle&oldid=43451"