|
|
| (14 intermediate revisions by 7 users not shown) |
| Line 1: |
Line 1: |
| h1. QML 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 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":http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html:
| |
| | |
| * "":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<br />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>
| |
| | |
| /*!<br /> QtQuick.Controls 1.1<br /> #this is the same as the import statement
| |
| | |
| '''/
| |
| <br />/'''!<br /> Button<br /> QtQuick.Controls<br /> #QDoc will associate this Button to whatever version QtQuick.Controls has. (only one version per release)
| |
| | |
| '''/<br /></code>
| |
| <br />There are two versions important for the user to know: Qt version and QML module version.
| |
| <br />Use<br />''' "5.3&quot; for "<qml module&gt; <version&gt;" for and the members.
| |
| | |
| "QtQuick 2.3&quot; in a property documentation block will generate: "This property was introduced in QtQuick 2.3&quot;
| |
| | |
| == QML Types ==
| |
| | |
| The "":http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#qmltype-command command is for QML type documentation.
| |
| | |
| <code><br /> TextEdit<br /> QQuickTextEdit<br /> QtQuick<br /> 4.8<br /> qtquick-visual<br /> qtquick-input<br /> Item<br /> 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 {<br /> width: 240<br /> text: "<b&gt;Hello&lt;/b&gt; <i&gt;World!</i&gt;"<br /> font.family: "Helvetica&quot;<br /> font.pointSize: 20<br /> color: "blue&quot;<br /> focus: true<br /> }<br />
| |
| | |
| declarative-textedit.gif
| |
| | |
| … omitted detailed description
| |
| | |
| Text, TextInput, {examples/quick/text/textselection}{Text Selection example}<br /></code>
| |
| | |
| Some commonly used commands and "context commands&quot;:http://doc-snapshot.qt.io/qt5-stable/14-qdoc-commands-contextcommands.html:<br />* "":http://doc-snapshot.qt.io/qt5-stable/11-qdoc-commands-specialcontent.html#brief-command - the brief description '''mandatory'''<br />* "":http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html#inqmlmodule-command '''mandatory'''<br />* "":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.<br />* "":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><br />ColorAnimation<br />Animates changes in color values.<br /></code>
| |
| | |
| Here are some alternate verbs for the brief statement:<br />* "Provides…"<br />* "Specifies…"<br />* "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:<br />* "This property holds…"<br />* "This property describes…"<br />* "This property represents…"<br />* "Returns rue when… and alse when…" - for properties that are marked ''read-only''.<br />* "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><br />/*<br /> This signal is emitted when the user clicks the button. A click is defined<br /> as a press followed by a release. The corresponding handler is<br /> nClicked.<br />'''/<br /></code>
| |
| <br />These are the possible documentation styles for signals:<br />''' "This signal is triggered when…"<br />* "Triggered when…"<br />* "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 "topic command&quot;:http://doc-snapshot.qt.io/qt5-stable/13-qdoc-commands-topics.html 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><br />/*<br /> QtQuick2::ListModel::remove(int index, int count = 1)
| |
| | |
| Deletes the content at index from the model.
| |
| | |
| clear()<br />*/<br />void QQuickListModel::remove(QQmlV8Function '''args)<br /></code>
| |
| <br />Some common verbs for function documentation:<br />''' "Copies…" - for constructors<br />* "Destroys…" - for destructors<br />* "Returns…" - for accessor functions
| |
| | |
| The function documentation must document:<br />* the return type<br />* the parameters<br />* 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><br />/*!<br />enumeration QtQuick2::Text::font.weight
| |
| | |
| Sets the font's weight.
| |
| | |
| The weight can be one of:
| |
| | |
| Font.Light<br />Font.Normal - the default<br />Font.DemiBold<br />Font.Bold<br />Font.Black<br />'''/<br /></code>
| |
| <br />To begin the description, use:<br />''' "This enumeration…"
| |