/usr/share/qt5/doc/qdoc/qtwritingstyle-cpp.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 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 | <?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-cpp.qdoc -->
<title>C++ 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 >C++ 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="#class-documentation">Class Documentation</a></li>
<li class="level2"><a href="#the-brief-and-detailed-description">The Brief and Detailed Description</a></li>
<li class="level1"><a href="#member-functions">Member Functions</a></li>
<li class="level1"><a href="#properties">Properties</a></li>
<li class="level1"><a href="#signals-notifiers-and-slots">Signals, Notifiers, and Slots</a></li>
<li class="level1"><a href="#enums-namespaces-and-other-types">Enums, Namespaces, and Other Types</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">C++ Documentation Style</h1>
<span class="subtitle"></span>
<!-- $$$qtwritingstyle-cpp.html-description -->
<div class="descr"> <a name="details"></a>
<p>To generate the documentation, QDoc goes through the source code and generates documentation for C++ types such as classes. QDoc then associates member functions, properties, and other types to the appropriate class.</p>
<p>Note that the documentation must be in the implementation files such as <code>.cpp</code>.</p>
<a name="class-documentation"></a>
<h2 id="class-documentation">Class Documentation</h2>
<p>Class documentation is generated using the <a href="13-qdoc-commands-topics.html#class-command">\class</a> command and the name of the class as the first argument.</p>
<pre class="cpp">
/*!
\class QCache
\brief The QCache class is a template class that provides a cache.
\ingroup tools
\ingroup shared
\reentrant
QCache\<Key, T\> defines a cache that stores objects of type T
associated with keys of type Key. For example, here's the
definition of a cache that stores objects of type Employee
associated with an integer key:
\snippet code/doc_src_qcache.cpp 0
Here's how to insert an object in the cache:
\snippet code/doc_src_qcache.cpp 1
... detailed description ommitted
\sa QPixmapCache, QHash, QMap
*/
</pre>
<p><a href="14-qdoc-commands-contextcommands.html">Context commands</a> add information about the class, such as its module or which version the class was added.</p>
<p>Some common context commands are:</p>
<ul>
<li><a href="11-qdoc-commands-specialcontent.html#brief-command">\brief</a> - the class' brief description <b>(mandatory)</b></li>
<li><a href="16-qdoc-commands-status.html#since-command">\since</a> - the version to which the class was added <b>(mandatory)</b></li>
<li><a href="16-qdoc-commands-status.html#internal-command">\internal</a> - marks the class as internal. Internal classes do not appear in the public API documentation.</li>
</ul>
<a name="the-brief-and-detailed-description"></a>
<h3 >The Brief and Detailed Description</h3>
<p>The <i>brief description</i> is marked with the <a href="11-qdoc-commands-specialcontent.html#brief-command">\brief</a> command and it is for summarizing the purpose or functionality of the class. For C++ classes, QDoc will take the class and create annotated information for the class. The annotated information appears in lists and tables which display the class.</p>
<p>The C++ brief should start with:</p>
<pre class="cpp">
<span class="string">"The <C++ class name> class"</span>
</pre>
<p>The <i>detailed description</i> section starts after the brief description. It provides more information about the class. The detailed description may contain images, snippet code, or links to other relevant documents. There must be an empty line which separates the brief and detailed description.</p>
<a name="member-functions"></a>
<h2 id="member-functions">Member Functions</h2>
<p>Typically, function documentation immediately precedes the implementation of the function in the <code>.cpp</code> file. For function documentation that is not immediately above the implementation, the <a href="13-qdoc-commands-topics.html#fn-command">\fn</a> is needed.</p>
<pre class="cpp">
/*!
\fn QString &QString::remove(int position, int n)
Removes \a n characters from the string, starting at the given \a
position index, and returns a reference to the string.
If the specified \a position index is within the string, but \a
position + \a n is beyond the end of the string, the string is
truncated at the specified \a position.
\snippet qstring/main.cpp 37
\sa insert(), replace()
*/
QString &QString::remove(int pos, int len)
</pre>
<p>The function documentation starts with a verb, indicating the operation the function performs. This also applies to constructors and destructors.</p>
<p>Some common verbs for function documentation:</p>
<ul>
<li>"Constructs..." - 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>
<pre class="cpp">
/*!
Returns \c true if a QScroller object was already created for \a target; \c false otherwise.
\sa scroller()
*/
bool QScroller::hasScroller(QObject *target)
</pre>
<a name="properties"></a>
<h2 id="properties">Properties</h2>
<p>The property documentation resides immediately above the read function's implementation. The <a href="qdoc-guide-writing.html#writing-topic-commands">topic command</a> for properties is <a href="13-qdoc-commands-topics.html#property-command">\property</a>.</p>
<pre class="cpp">
/*!
\property QVariantAnimation::duration
\brief the duration of the animation
This property describes the duration in milliseconds of the
animation. The default duration is 250 milliseconds.
\sa QAbstractAnimation::duration()
*/
int QVariantAnimation::duration() const
</pre>
<p>Property documentation usually starts with "This property...", but these are alternate 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 read.</li>
<li>"Sets the..." - for properties that configure a type.</li>
</ul>
<p>Property documentation must include:</p>
<ul>
<li>description and behavior of the property</li>
<li>accepted values for the property</li>
<li>the default value of the property</li>
</ul>
<p>Similar to <a href="qtwritingstyle-cpp.html#member-functions">functions</a>, the default type may be linked or marked with the <code>\c</code> command.</p>
<p>An example of a value range style is:</p>
<blockquote><p>The values range from 0.0 (no blur) to maximumRadius (maximum blur). By default, the property is set to 0.0 (no blur).</p>
</blockquote>
<a name="signals-notifiers-and-slots"></a>
<h2 id="signals-notifiers-and-slots">Signals, Notifiers, and Slots</h2>
<p>The <a href="qdoc-guide-writing.html#writing-topic-commands">topic command</a> for signals, notifiers, and slots is <a href="13-qdoc-commands-topics.html#fn-command">\fn</a>. Signal documentation state when they are triggered or emitted.</p>
<pre class="cpp">
/*!
\fn QAbstractTransition::triggered()
This signal is emitted when the transition has been triggered (after
onTransition() has been called).
*/
</pre>
<p>Signal documentation typically begin with "This signal is triggered when...". Here are alternate styles:</p>
<ul>
<li>"This signal is triggered when..."</li>
<li>"Triggered when..."</li>
<li>"Emitted when..."</li>
</ul>
<p>For slots or notifiers, the condition when they are executed or triggered by a signal should be documented.</p>
<ul>
<li>"Executed when..."</li>
<li>"This slot is executed when..."</li>
</ul>
<p>For properties that have overloaded signals, QDoc groups the overloaded notifiers together. To refer to a specific version of a notifier or signal, simply refer to the property and mention that there are different versions of the notifier.</p>
<pre class="cpp">
/*!
\property QSpinBox::value
\brief the value of the spin box
setValue() will emit valueChanged() if the new value is different
from the old one. The \l{QSpinBox::}{value} property has a second notifier
signal which includes the spin box's prefix and suffix.
*/
</pre>
<a name="enums-namespaces-and-other-types"></a>
<h2 id="enums-namespaces-and-other-types">Enums, Namespaces, and Other Types</h2>
<p>Enums, namespaces, and macros have a <a href="qdoc-guide-writing.html#writing-topic-commands">topic command</a> for their documentation:</p>
<ul>
<li><a href="13-qdoc-commands-topics.html#enum-command">\enum</a></li>
<li><a href="13-qdoc-commands-topics.html#typedef-command">\typedef</a></li>
<li><a href="13-qdoc-commands-topics.html#macro-command">\macro</a></li>
</ul>
<p>The language style for these types mention that they are an enum or a macro and continues with the type description.</p>
<p>For enumerations, the <a href="10-qdoc-commands-tablesandlists.html#value-command">\value</a> command is for listing the values. QDoc creates a table of values for the enum.</p>
<pre class="cpp">
/*!
\enum QSql::TableType
This enum type describes types of SQL tables.
\value Tables All the tables visible to the user.
\value SystemTables Internal tables used by the database.
\value Views All the views visible to the user.
\value AllTables All of the above.
*/
</pre>
</div>
<!-- @@@qtwritingstyle-cpp.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>
|