<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qdoc-guide.qdoc -->
<title>Categories of Documentation | 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 >Categories of Documentation</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<link rel="prev" href="qdoc-guide-writing.html" />
<link rel="next" href="qdoc-componentset-example.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="qdoc-guide-writing.html">Writing Documentation</a>
<span class="naviSeparator"> ◦ </span>
<a class="nextPage" href="qdoc-componentset-example.html">QML Documentation Example</a>
</p><p/>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#api-documentation">API Documentation</a></li>
<li class="level2"><a href="#language-styles">Language Styles</a></li>
<li class="level2"><a href="#documenting-qml-types">Documenting QML Types</a></li>
<li class="level1"><a href="#articles-overviews">Articles & Overviews</a></li>
<li class="level1"><a href="#tutorials-how-to-s-faq-s">Tutorials, How-To's, FAQ's</a></li>
<li class="level1"><a href="#code-examples">Code Examples</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Categories of Documentation</h1>
<span class="subtitle"></span>
<!-- $$$qdoc-categories.html-description -->
<div class="descr"> <a name="details"></a>
<p>There are several types of predefined documentation <i>categories</i> or <i>types</i>:</p>
<ul>
<li>How-To's</li>
<li>Tutorial</li>
<li>Overview</li>
<li>Article</li>
<li>FAQ (Frequently Asked Questions)</li>
<li>C++ API Documentation</li>
<li>QML Type Documentation</li>
<li>Code Example</li>
</ul>
<p>QDoc has the ability to format a page depending on the type. Further, stylesheets can provide additional control on the display of each category.</p>
<a name="api-documentation"></a>
<h2 id="api-documentation">API Documentation</h2>
<p>QDoc excels in the creation of API documentation given a set of source code and documentation in QDoc comments. Specifically, QDoc is aware of Qt's architecture and can validate the existence of Qt C++ class, function, or property documentation. QDoc gives warnings and errors if it cannot associate a documentation with a code entity or if a code entity does not have documentation.</p>
<p>In general, every Qt code entity such as properties, classes, methods, signals, and enumerations have a corresponding <a href="qdoc-guide-writing.html#qdoc-topics">topic command</a>. QDoc will associate the documentation to the source using C++ naming rules.</p>
<p>QDoc will parse the header files (typically <code>.h</code> files) to build a tree of the class structures. Then QDoc will parse the source files and documentation files to attach documentation to the class structure. Afterwards, QDoc will generate a page for the class.</p>
<p><b>Note: </b>QDoc uses the header files to inform itself about the class and will not properly process QDoc comments in header files.</p><a name="language-styles"></a>
<h3 >Language Styles</h3>
<p>To produce quality API documentation, the Qt API references follow a particular language guidelines. While the contents of this page demonstrates how to create API documentation, the style guidelines demonstrate how the reference materials follow a consistent use of language.</p>
<ul>
<li><a href="qtwritingstyle-cpp.html">C++ Documentation Style</a></li>
<li><a href="qtwritingstyle-qml.html">QML Documentation Style</a></li>
</ul>
<a name="documenting-qml-types"></a>
<h3 >Documenting QML Types</h3>
<p>In the world of QML, there are additional entities we need to document such as QML signals, attached properties, and QML methods. Internally, they use Qt technologies, however, QML API documentation requires different layout and naming conventions from the Qt C++ API documentation.</p>
<p>A list of QML related QDoc commands:</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> - creates a QML type documentation</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="18-qdoc-commands-relating.html#inherits-command">\inherits</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><b>Note: </b>Remember to enable QML parsing by including the <code>*.qml</code> filetype in the <a href="qdoc-guide-conf.html#qdoc-input-output-dir">fileextension</a> variable.</p><p>To document a QML type, start by creating a QDoc comment that uses the <a href="13-qdoc-commands-topics.html#qmltype-command">\qmltype</a> command as its topic command.</p>
<a name="qml-parser"></a>
<h4 >QML Parser</h4>
<p>If your QML type is defined in a <i>qml</i> file, document it there. If your QML type is represented by a C++ class, document it in the <i>cpp</i> file for that C++ class and include an <a href="13-qdoc-commands-topics.html#instantiates-command">\instantiates</a> command to specify the name of the C++ class. Don't document a QML type in a <i>cpp</i> file if the QML type is defined in a <i>qml</i> file.</p>
<p>When documenting a QML type in a <i>qml</i> file, place each QDoc comment directly above the entity to which the comment applies. For example, place the QDoc comment containing the <i>\qmltype</i> command (the topic comment) directly above the outer QML type in the <i>qml</i> file. Place the comment for documenting a QML property directly above the property declaration, and so on for QML signal handlers and QML methods. Note that when documenting QML properties in a <i>qml</i> file, you don't normally include the <i>\qmlproperty</i> command as a topic command (which you must do when documenting QML types in <i>cpp</i> files), because the QML parser automatically associates each QDoc comment with the next QML declaration it parses. The same is true for QML signal handler and QML method comments. But it is sometimes useful to include one or more <i>\qmlproperty</i> commands in the comment, e.g. when the property type is another QML type and you want the user to only use certain properties within that other QML type, but not all of them. But when documenting a property that has an alias, place the QDoc comment for it directly above the alias declaration. In these cases, the QDoc comment <i>must</i> contain a <i>\qmlproperty</i> command, because that is the only way QDoc can know the type of the aliased property.</p>
<p>When documenting a QML type in the <i>cpp</i> file of its corresponding C++ class (if it has one), you normally place each QDoc comment directly above the entity it documents. However, QDoc does not use the QML parser to parse these files (the C++ parser is used), so these QML QDoc comments can appear anywhere in the <i>cpp</i> file. Note that QML QDoc comments in <i>cpp</i> files <i>must</i> use the QML topic commands. i.e., the <a href="13-qdoc-commands-topics.html#qmltype-command">\qmltype</a> command <i>must</i> appear in the QDoc comment for the QML type, and a <a href="13-qdoc-commands-topics.html#qmlproperty-command">\qmlproperty</a> command <i>must</i> appear in each QML property QDoc comment.</p>
<a name="qml-modules"></a>
<h4 >QML Modules</h4>
<p>A QML type belongs to a <i>module</i>. The module may include all the related types for a platform or contain a certain version of Qt Quick. For example, the Qt Quick 2 QML types belong to the Qt Quick 2 module while there is also a Qt Quick 1 module for the older types introduced in Qt 4.</p>
<p>QML modules allow grouping QML types. The <a href="13-qdoc-commands-topics.html#qmltype-command">\qmltype</a> topic command must have an <a href="13-qdoc-commands-topics.html#inqmlmodule-command">\inqmlmodule</a> context command to relate the type to a QML module. Similarly, a <a href="13-qdoc-commands-topics.html#qmlmodule-command">\qmlmodule</a> topic command must exist in a separate <code>.qdoc</code> file to create the overview page for the module. The overview page will list the QML types of the QML module.</p>
<p>The links to the QML types must therefore also contain the module name. For example, if a type called <code>TabWidget</code> is in the <code>UIComponents</code> module, it must be linked as <code>UIComponents::TabWidget</code>.</p>
<p>The <a href="qdoc-componentset-example.html">UIComponents</a> example demonstrates proper usage of QDoc commands to document QML types and QML modules.</p>
<a name="read-only-and-internal-qml-properties"></a>
<h4 >Read-only and Internal QML Properties</h4>
<p>QDoc detects QML properties that are marked as <code>readonly</code>. Note that the property must be initialized with a value.</p>
<pre class="cpp">
readonly property <span class="type">int</span> sampleReadOnlyProperty: <span class="number">0</span>
</pre>
<p>For example, the example <a href="qml-uicomponents-tabwidget.html">TabWidget</a> type has a fictitious read-only property <code>sampleReadOnlyProperty</code>. Its declaration has the <code>readonly</code> identifier and it has an initial value.</p>
<p>Properties and signals that are not meant for the public interface may be marked with the <a href="16-qdoc-commands-status.html#internal-command">\internal</a> command. QDoc will not publish the documentation in the generated outputs.</p>
<a name="articles-overviews"></a>
<h2 id="articles-overviews">Articles & Overviews</h2>
<p>Articles and overviews are a style of writing best used for providing summary detail on a topic or concept. It may introduce a technology or discuss how a concept may be applied, but without discussing exact steps in too much detail. However, this type of content could provide the entry point for readers to find instructional and reference materials that do, such as tutorials, examples and class documentation. An example of an overview might be a product page, such as a top level discussion of Qt Quick, individual modules, design principles, or tools.</p>
<p>To signify that a document is an article, you append the article keyword to the \page command:</p>
<pre class="cpp">
/*!
\page overview-qt-technology.html overview
\title Overview of a Qt Technology
\brief provides a technology never seen before.
*/
</pre>
<p>The <a href="qdoc-guide-writing.html#writing-topic-commands">writing topic commands</a> section has a listing of the available \page command arguments.</p>
<a name="tutorials-how-to-s-faq-s"></a>
<h2 id="tutorials-how-to-s-faq-s">Tutorials, How-To's, FAQ's</h2>
<p>Tutorials, How-To's, and FAQ's are all instructional material, in that they instruct or prescribe to the reader. Tutorials are content designed to guide the reader along a progressive learning path for a concept or technology. How-To's and FAQ's (<i>Frequently Asked Questions</i>) provide guidance by presenting material in the form of answers to commonly asked topics. How-To's and FAQ's are designed for easy reference and are not necessarily presented in a linear progression.</p>
<p>To create these types, mark the pages by providing a <code>type</code> argument to the <a href="13-qdoc-commands-topics.html#page-command">\page</a> command. The <code>type</code> argument is the second argument, with the file name being the first.</p>
<pre class="cpp">
/*!
\page altruism-faq.html faq
\title Altruism Frequently Asked Questions
\brief All the questions about altruism, answered.
...
*/
</pre>
<p>The <a href="qdoc-guide-writing.html#writing-topic-commands">writing topic commands</a> section has a listing of the available \page command arguments.</p>
<a name="code-examples"></a>
<h2 id="code-examples">Code Examples</h2>
<p>Examples are an effective way to demonstrate practical usage of a given technology or concept. When it comes to middleware this is usually in the form of an application using simple code and clear explanations of what the code is doing. Any module, API, project, pattern etc. should have at least one good example.</p>
<p>An example may have an accompanying tutorial. The tutorial instructs and describes the code, while the code example is the code content that users may study. Code examples may have accompanying text that are not in the tutorial.</p>
<p>QDoc will create a page containing the example code with a description using the <a href="13-qdoc-commands-topics.html#example-command">\example</a> command.</p>
<pre class="cpp">
/*!
\title UI Components: Tab Widget Example
\example declarative/ui-components/tabwidget
This example shows how to create a tab widget. It also demonstrates how
\l {Property aliases}{property aliases} and
\l {Introduction to the QML Language#Default Properties}{default properties} can be used to collect and
assemble the child items declared within an \l Item.
\image qml-tabwidget-example.png
*/
</pre>
<p>QDoc will use the directory specified in the input <a href="qdoc-guide-conf.html#input-and-output-directories">exampledirs</a> variable to find the Qt Project (<code>.pro</code>) file to generate the example files. The generated HTML will have the filename, <code>declarative-ui-components-tabwidget.html</code>. QDoc will also list all of the example code.</p>
<p><b>Note: </b>The example's project file must be the same as the directory name.</p></div>
<!-- @@@qdoc-categories.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="qdoc-guide-writing.html">Writing Documentation</a>
<span class="naviSeparator"> ◦ </span>
<a class="nextPage" href="qdoc-componentset-example.html">QML Documentation Example</a>
</p>
</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>
