/usr/share/qt5/doc/qdoc/qtwritingstyle-qml.html is in qttools5-doc-html 5.9.5-0ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qtwritingstyle-qml.qdoc -->
<title>QML Documentation Style | QDoc Manual 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.9</td><td ><a href="qdoc-index.html">QDoc Manual</a></td><td >QML Documentation Style</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.5 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#qml-types">QML Types</a></li>
<li class="level1"><a href="#properties">Properties</a></li>
<li class="level1"><a href="#signals-and-handlers-documentation">Signals and Handlers Documentation</a></li>
<li class="level1"><a href="#methods-and-javascript-functions">Methods and JavaScript Functions</a></li>
<li class="level1"><a href="#enumerations">Enumerations</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">QML Documentation Style</h1>
<span class="subtitle"></span>
<!-- $$$qtwritingstyle-qml.html-description -->
<div class="descr"> <a name="details"></a>
<p>QDoc can process QML types defined as C++ classes and QML types defined in <code>.qml</code> files. For C++ classes documented as QML types, the QDoc comments are in the <code>.cpp</code> file while QML types defined in QML are in the <code>.qml</code> file. The C++ classes must also be documented documented with the QML <a href="13-qdoc-commands-topics.html">topic commands</a>:</p>
<ul>
<li><a href="13-qdoc-commands-topics.html#qmlattachedproperty-command">\qmlattachedproperty</a></li>
<li><a href="13-qdoc-commands-topics.html#qmlattachedsignal-command">\qmlattachedsignal</a></li>
<li><a href="13-qdoc-commands-topics.html#qmlbasictype-command">\qmlbasictype</a></li>
<li><a href="13-qdoc-commands-topics.html#qmltype-command">\qmltype</a></li>
<li><a href="13-qdoc-commands-topics.html#qmlmethod-command">\qmlmethod</a></li>
<li><a href="13-qdoc-commands-topics.html#qmlproperty-command">\qmlproperty</a></li>
<li><a href="13-qdoc-commands-topics.html#qmlsignal-command">\qmlsignal</a></li>
<li><a href="13-qdoc-commands-topics.html#qmlmodule-command">\qmlmodule</a></li>
<li><a href="13-qdoc-commands-topics.html#inqmlmodule-command">\inqmlmodule</a></li>
<li><a href="13-qdoc-commands-topics.html#instantiates-command">\instantiates</a></li>
</ul>
<p>For QML types defined in <code>.qml</code> 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 <a href="16-qdoc-commands-status.html#internal-command">internal</a> if it is not a public API.</p>
<a name="qml-types"></a>
<h2 id="qml-types">QML Types</h2>
<p>The <a href="13-qdoc-commands-topics.html#qmltype-command">\qmltype</a> command is for QML type documentation.</p>
<pre class="cpp">
\qmltype TextEdit
\instantiates QQuickTextEdit
\inqmlmodule QtQuick
\ingroup qtquick-visual
\ingroup qtquick-input
\inherits Item
\brief 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:
\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}
</pre>
<p>The <a href="13-qdoc-commands-topics.html#instantiates-command">\instantiates</a> accepts the C++ class which implements the QML type as the argument. For types implemented in QML, this is not needed.</p>
<p>The <i>brief description</i> 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.</p>
<pre class="cpp">
\qmltype ColorAnimation
\brief Animates changes in color values
</pre>
<p>Here are some alternate verbs for the brief statement:</p>
<ul>
<li>"Provides..."</li>
<li>"Specifies..."</li>
<li>"Describes..."</li>
</ul>
<p>The <i>detailed description</i> follows the brief and may contain images, snippet, and link to other documentation.</p>
<a name="properties"></a>
<h2 id="properties">Properties</h2>
<p>The property description focuses on what the property <i>does</i> and may use the following style:</p>
<p>Property documentation usually starts with "This property..." but for certain properties, these are the common expressions:</p>
<ul>
<li>"This property holds..."</li>
<li>"This property describes..."</li>
<li>"This property represents..."</li>
<li>"Returns <code>true</code> when... and <code>false</code> when..." - for properties that are marked <code>read-only</code>.</li>
<li>"Sets the..." - for properties that configure a type.</li>
</ul>
<a name="signals-and-handlers-documentation"></a>
<h2 id="signals-and-handlers-documentation">Signals and Handlers Documentation</h2>
<p>QML signals are documented either in the QML file or in the C++ implementation with the <a href="13-qdoc-commands-topics.html#qmlsignal-command">\qmlsignal</a> command. Signal documentation must include the condition for emitting the signal, mention the corresponding signal handler, and document whether the signal accepts a parameter.</p>
<pre class="cpp">
/*
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()
</pre>
<p>These are the possible documentation styles for signals:</p>
<ul>
<li>"This signal is triggered when..."</li>
<li>"Triggered when..."</li>
<li>"Emitted when..."</li>
</ul>
<a name="methods-and-javascript-functions"></a>
<h2 id="methods-and-javascript-functions">Methods and JavaScript Functions</h2>
<p>Typically, function documentation immediately precedes the implementation of the function in the <code>.cpp</code> file. The <a href="13-qdoc-commands-topics.html">topic command</a> for functions is <a href="13-qdoc-commands-topics.html#fn-command">\fn</a>. For functions in QML or JavaScript, the documentation must reside immediately above the function declaration.</p>
<p>The function documentation starts with a verb, indicating the operation the function performs.</p>
<pre class="cpp">
/*
\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)
</pre>
<p>Some common verbs for function documentation:</p>
<ul>
<li>"Copies..." - for constructors</li>
<li>"Destroys..." - for destructors</li>
<li>"Returns..." - for accessor functions</li>
</ul>
<p>The function documentation must document:</p>
<ul>
<li>the return type</li>
<li>the parameters</li>
<li>the actions of the functions</li>
</ul>
<p>The <a href="04-qdoc-commands-textmarkup.html#a-command">\a</a> command marks the parameter in the documentation. The return type documentation should link to the type documentation or be marked with the <a href="04-qdoc-commands-textmarkup.html#c-command">\c</a> command in the case of boolean values.</p>
<a name="enumerations"></a>
<h2 id="enumerations">Enumerations</h2>
<p>QML enumerations are documented as QML properties with the <a href="13-qdoc-commands-topics.html#qmlproperty-command">\qmlproperty</a> command. The type of the property is <code>enumeration</code>.</p>
<pre class="cpp">
/*!
\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
*/
</pre>
<p>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.</p>
</div>
<!-- @@@qtwritingstyle-qml.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|