<?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>Writing 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 >Writing 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-conf.html" />
<link rel="next" href="qdoc-categories.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="qdoc-guide-conf.html">Creating QDoc Configuration Files</a>
<span class="naviSeparator"> ◦ </span>
<a class="nextPage" href="qdoc-categories.html">Categories of Documentation</a>
</p><p/>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#qdoc-comments">QDoc Comments</a></li>
<li class="level1"><a href="#qdoc-commands">QDoc Commands</a></li>
<li class="level2"><a href="#qdoc-topics">QDoc Topics</a></li>
<li class="level2"><a href="#topic-contexts">Topic Contexts</a></li>
<li class="level2"><a href="#documentation-markup">Documentation Markup</a></li>
<li class="level1"><a href="#anatomy-of-documentation">Anatomy of Documentation</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Writing Documentation</h1>
<span class="subtitle"></span>
<!-- $$$qdoc-guide-writing.html-description -->
<div class="descr"> <a name="details"></a>
<a name="qdoc-comments"></a>
<h2 id="qdoc-comments">QDoc Comments</h2>
<p>Documentation is contained within QDoc <i>comments</i>, delimited by /*! and */ comments. Note that these are valid comments in C++, QML, and JavaScript.</p>
<p>Within a QDoc comment, <code>//!</code> is used as a single-line documentation comment; the comment itself and anything after it, until a newline, is omitted from the generated output.</p>
<p>QDoc will parse C++ and QML files to look for qdoc comments. To explicitly omit a certain file type, omit it from the <a href="qdoc-guide-conf.html#input-and-output-directories">configuration</a> file.</p>
<a name="qdoc-commands"></a>
<h2 id="qdoc-commands">QDoc Commands</h2>
<p>QDoc uses <i>commands</i> to retrieve information about the documentation. <code>Topic</code> commands determine the type of documentation element, the <code>context</code> commands provide hints and information about a topic, and <code>markup</code> commands provide information on how QDoc should format a piece of documentation.</p>
<a name="writing-topic-commands"></a><a name="qdoc-topics"></a>
<h3 >QDoc Topics</h3>
<p>Each qdoc comment must have a <i>topic</i> type. A topic distinguishes it from other topics. To specify a topic type, use one of the several <a href="13-qdoc-commands-topics.html">topic commands</a>.</p>
<p>QDoc will collect similar topics and create a page for each one. For example, all the enumerations, properties, functions, and class description of a particular C++ class will reside in one page. A generic page is specified using the <a href="13-qdoc-commands-topics.html#page-command">\page</a> command and the filename is the argument.</p>
<p>Example of topic commands:</p>
<ul>
<li><a href="13-qdoc-commands-topics.html#enum-command">\enum</a> - for enumeration documentation</li>
<li><a href="13-qdoc-commands-topics.html#class-command">\class</a> - for C++ class documentation</li>
<li><a href="13-qdoc-commands-topics.html#qmltype-command">\qmltype</a> - for QML type documentation</li>
<li><a href="13-qdoc-commands-topics.html#page-command">\page</a> - for creating a page.</li>
</ul>
<p>The <a href="13-qdoc-commands-topics.html#page-command">\page</a> command is for creating articles that are not part of source documentation. The command can also accept two arguments: the file name of the article and the documentation type. The possible types are:</p>
<ul>
<li><code>howto</code></li>
<li><code>overview</code></li>
<li><code>tutorial</code></li>
<li><code>faq</code></li>
<li><code>article</code> - <i>default</i> when there is no type</li>
</ul>
<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="13-qdoc-commands-topics.html">Topic Commands</a> page has information on all of the available topic commands.</p>
<a name="writing-context"></a><a name="topic-contexts"></a>
<h3 >Topic Contexts</h3>
<p>Context commands give QDoc a hint about the <i>context</i> of the topic. For example, if a C++ function is obsolete, then it should be marked obsolete with the <a href="16-qdoc-commands-status.html#obsolete-command">\obsolete</a> command. Likewise, <a href="15-qdoc-commands-navigation.html#nextpage-command">page navigation</a> and <a href="20-qdoc-commands-namingthings.html#title-command">page title</a> give extra page information to QDoc.</p>
<p>QDoc will create additional links or pages for these contexts. For example, a group is created using the <a href="13-qdoc-commands-topics.html#group-command">\group</a> command and the members have the <a href="19-qdoc-commands-grouping.html#ingroup-command">\ingroup</a> command. The group name is supplied as an argument.</p>
<p>The <a href="14-qdoc-commands-contextcommands.html">Context Commands</a> page has a listing of all the available context commands.</p>
<a name="writing-markup"></a><a name="documentation-markup"></a>
<h3 >Documentation Markup</h3>
<p>QDoc can do <i>markup</i> of text similar to other markup or documentation tools. QDoc can mark a section of text in <b>bold</b>, when the text is marked up with the <a href="04-qdoc-commands-textmarkup.html#b-command">\b</a> command.</p>
<pre class="cpp">
\b{This} text will be in \b{bold}<span class="operator">.</span>
</pre>
<p>The <a href="03-qdoc-commands-markup.html">Markup Commands</a> page has a full listing of the available markup commands.</p>
<a name="anatomy-of-documentation"></a>
<h2 id="anatomy-of-documentation">Anatomy of Documentation</h2>
<p>Essentially, for QDoc to create a page, there must be some essential ingredients present.</p>
<ul>
<li>Assign a topic to a QDoc comment - A comment could be a page, a property documentation, a class documentation, or any of the available <a href="13-qdoc-commands-topics.html">topic commands</a>.</li>
<li>Give the topic a context - QDoc can associate certain topics to other pages such as associating obsolete functions when the documentation is marked with <a href="16-qdoc-commands-status.html#obsolete-command">\obsolete</a>.</li>
<li>Mark sections of the document with <a href="03-qdoc-commands-markup.html">markup commands</a> - QDoc can create layouts and format the documentation for the documentation.</li>
</ul>
<p>In Qt, the QVector3D class was documented with the following QDoc comment:</p>
<pre class="cpp">
/*!
\class QVector3D
\brief The QVector3D class represents a vector or vertex in 3D space.
\since 4.6
\ingroup painting-3D
Vectors are one of the main building blocks of 3D representation and
drawing. They consist of three coordinates, traditionally called
x, y, and z.
The QVector3D class can also be used to represent vertices in 3D space.
We therefore do not need to provide a separate vertex class.
\note By design values in the QVector3D instance are stored as \c float.
This means that on platforms where the \c qreal arguments to QVector3D
functions are represented by \c double values, it is possible to
lose precision.
\sa QVector2D, QVector4D, QQuaternion
*/
</pre>
<p>It has a constructor, QVector3D::QVector3D(), which was documented with the following QDoc comment:</p>
<pre class="cpp">
/*!
\fn QVector3D::QVector3D(const QPoint& point)
Constructs a vector with x and y coordinates from a 2D \a point, and a
z coordinate of 0.
*/
</pre>
<p>The different comments may reside in different files and QDoc will collect them depending on their topic and their context. The resulting documentation from the snippets are generated into the QVector3D class documentation.</p>
<p>Note that if the documentation immediately precedes the function or class in the source code, then it does not need to have a topic. QDoc will assume that the documentation above the code is the documentation for that code.</p>
<p>An article is created using <a href="13-qdoc-commands-topics.html#page-command">\page</a> command. The first argument is the HTML file that QDoc will create. The topic is supplemented with context commands, the <a href="20-qdoc-commands-namingthings.html#title-command">\title</a> and <a href="15-qdoc-commands-navigation.html#nextpage-command">\nextpage</a> commands. There are several other QDoc commands such as the <a href="10-qdoc-commands-tablesandlists.html#list-command">\list</a> command.</p>
<pre class="cpp">
/*!
\page generic-guide.html
\title Generic QDoc Guide
\nextpage Creating QDoc Configuration Files
There are three essential materials for generating documentation with qdoc:
\list
\li \c qdoc binary
\li \c qdocconf configuration files
\li \c Documentation in \c C++, \c QML, and \c .qdoc files
\endlist
*/
</pre>
<p>The section on <a href="qdoc-guide-writing.html#qdoc-topics">topic commands</a> gives an overview on several other topic types.</p>
</div>
<!-- @@@qdoc-guide-writing.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="qdoc-guide-conf.html">Creating QDoc Configuration Files</a>
<span class="naviSeparator"> ◦ </span>
<a class="nextPage" href="qdoc-categories.html">Categories of Documentation</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>
distrib
>
Mageia
>
6
>
x86_64
>
media
>
core-updates
>
by-pkgid
>
749fcc421771b410525f39bd88a5732d
>
files
>
63
