AuroraMiddleware/qt5base-lts
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc: split up Qdoc-manual

Browse Source 
qdoc-manual.qdoc is now an overview document
Each section is a separate qdoc file
Title modification in minimal qdocconf qdoc file

Task-number: QTBUG-31801

Change-Id: I9e50eb8c4f1f501e9c0bc768372d4393b73053ed
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>
Reviewed-by: Martin Smith <martin.smith@digia.com>
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
This commit is contained in:
Nico Vertriest 2013-09-09 13:22:12 +02:00 committed by The Qt Project
parent 6d1f8575a3
commit c9c435179e
18 changed files with 8859 additions and 8893 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
src/tools/qdoc/doc/config/qdoc.qdocconf
View File

@ -8,16 +8,16 @@ version = $QT_VERSION
sourcedirs = ..
exampledirs = .. \
../examples \
../../../../examples \
config
../examples
imagedirs = ../../../doc/src/templates/images \
../images \
../../../../widgets/doc/images \
imagedirs = ../images \
../../../../widgets/doc/images
# ../../../doc/src/templates/images
tagfile = ../html/qdoc.tags
examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml *.css *.qdoc *.qdocinc *.sample"
qhp.projects = QDoc
qhp.QDoc.file = qdoc.qhp

0
src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc → src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc.sample
View File

2
src/tools/qdoc/doc/examples/cpp.qdoc.sample
View File

@ -123,4 +123,4 @@ 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.
*/
//! [overloaded notifier]
//! [overloaded notifier]

16
src/tools/qdoc/doc/examples/examples.qdoc
View File

@ -36,7 +36,7 @@
and their public interfaces. The types are grouped into a module, the
\l{UI Components} module.
The \l{componentset/uicomponents.qdoc}{uicomponents.qdoc} file generates
The \l{componentset/uicomponents.qdoc.sample}{uicomponents.qdoc} file generates
the overview page for the \l{UI Components} module page.
The generated documentation is available in the \l{UI Components} module.
@ -82,3 +82,17 @@
inside C++ classes to define the public API of the QML type.
*/
/*!
\qmlmodule UIComponents 1.0
\title UI Components
\brief Basic set of UI components
This is a listing of a list of UI components implemented by QML types. These
files are available for general import and they are based off the \l{Qt
Quick Code Samples}.
This module is part of the \l{componentset}{UIComponents} example.
*/

67
src/tools/qdoc/doc/files/basicqt.qdoc.sample Normal file
View File

@ -0,0 +1,67 @@
/*!
\page basicqt.html
\contentspage {Basic Qt} {Contents}
\nextpage Getting Started
\indexpage Index
\startpage Basic Qt
\title Basic Qt
The Qt toolkit is a C++ class library and a set of tools for
building multiplatform GUI programs using a "write once,
compile anywhere approach".
Table of contents:
\list
\li \l {Getting Started}
\li \l {Creating Dialogs}
\li \l {Creating Main Windows}
\endlist
*/
/*!
\page gettingstarted.html
\previouspage Basic Qt
\contentspage {Basic Qt} {Contents}
\nextpage Creating Dialogs
\indexpage Index
\startpage Basic Qt
\title Getting Started
This chapter shows how to combine basic C++ with the
functionality provided by Qt to create a few small graphical
interface (GUI) applications.
*/
/ *!
\page creatingdialogs.html
\previouspage Getting Started
\contentspage {Basic Qt} {Contents}
\indexpage Index
\startpage Basic Qt
\title Creating Dialogs
This chapter will teach you how to create dialog boxes using Qt.
*/
/*!
\page index.html
\indexpage Index
\startpage Basic Qt
\title Index
\list
\li \l {Basic Qt}
\li \l {Creating Dialogs}
\li \l {Getting Started}
\endlist
*/

89
src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc
View File

@ -51,7 +51,7 @@
documentation and an example of a QML type documentation.
For specific QDoc information, consult the
\l{Table of Contents}{QDoc Manual}.
\l{QDoc Manual}.
\section1 Chapters
\list 1
@ -62,7 +62,6 @@
\li \l{C++ Documentation Style}
\li \l{QML Documentation Style}
\endlist
\li \l{Configuration File Example}
\li \l{QML Documentation Example}
\endlist
@ -155,7 +154,7 @@
\section2 Qt Help Framework Configuration
QDoc will also export a \l{Qt Help Project} file, in a \c qhp file.
QDoc will also export a \e {Qt Help Project} file, in a \c qhp file.
The qhp file is then used by the \c qhelpgenerator to package the
documentation into a \c qch file. Qt Creator and Qt Assistant reads the qch
file to display the documentation.
@ -268,6 +267,7 @@
\nextpage Categories of Documentation
\section1 QDoc Comments
Documentation is contained within qdoc \e comments, delimited by
\beginqdoc and \endqdoc comments. Note that these are valid comments
in C++, QML, and JavaScript.
@ -402,7 +402,7 @@
\page qdoc-categories.html
\title Categories of Documentation
\previouspage Writing Documentation
\nextpage Configuration File Example
\nextpage QML Documentation Example
\brief Describes the different types such as How-To's, Tutorials, Overviews,
Examples, and Class Documentation.
@ -532,7 +532,7 @@
A QML type belongs to a \e module. The module
may include all the related types for a platform or contain a certain
version of \l{Qt Quick}. For example, the Qt Quick 2 \l{QML Elements} belong
version of \l{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.
@ -624,87 +624,10 @@
\l{Input and Output Directories}{exampledirs} variable to find the Qt
Project (\c .pro) file to generate the example files. The generated HTML
will have the filename, \c {declarative-ui-components-tabwidget.html}. QDoc
will also list all of the example code. For reference, view QDoc's generated
page for the \l{UI Components: Tab Widget Example}{Tab Widget} example.
will also list all of the example code.
\note The example's project file must be the same as the
directory name.
*/
/*!
\example config
\title Configuration File Example
\previouspage Categories of Documentation
\brief configuration files for the QDoc Manual and QDoc Guide
The QDoc Manual uses these \c qdocconf files to generate the QDoc Guide and
the \l{Table of Contents}{QDoc Manual}.
\note The configuration files are similar to the Qt Reference Documentation
and the QDoc Manual do not use all of the variables. The variables are
included to demonstrate a full project scenario.
\section1 Macros and other Definitions
\list
\li \l{config/compat.qdocconf}
\li \l{config/macros.qdocconf}
\li \l{config/qt-cpp-ignore.qdocconf}
\li \l{config/qt-defines.qdocconf}
\endlist
QDoc allows macros to help with aliasing and for inputting special HTML
characters within the documentation. Macros are a form of workarounds if
QDoc is unable to resolve formatting issues such as when QDoc should
disregard QDoc comments in documentation paragraphs.
QDoc is also aware of the common C++ and Qt preprocessors and can decide
which documentation to generate according to the definitions in the
configuration files.
\section1 Project Information
\list
\li \l{config/qdoc-online.qdocconf}
\li \l{config/qdoc.qdocconf}
\li \l{config/qdoc-project.qdocconf}
\endlist
These configuration files dictate how QDoc will generate the project.
Depending which configuration file QDoc processes, the formatting and the
information about the project will be different. If QDoc processes
\c{qdoc-online.qdocconf}, QDoc will generate the HTML version of the manual
will have the style suitable for online viewing.
Additionally, the settings for creating the
\l{The Qt Help Framework}{Qt Help File} is in the configuration.
\note The project file uses variables used during Qt's
\l{Configuration Options for Qt}{configuration} step.
\section1 HTML Styles
\list
\li \l{config/qt-html-default-styles.qdocconf}
\li \l{config/qt-html-online-styles.qdocconf}
\li \l{config/qt-html-templates-online.qdocconf}
\li \l{config/qt-html-templates.qdocconf}
\endlist
These files indicate which styles QDoc should use for the HTML formats.
Typically, there are two templates, one for online viewing and one for
offline. Qt Creator is able to fit more content in a page with the offline
template. The templates store HTML information as strings and QDoc will copy
the template to each HTML page.
\section1 Project File
\list
\li \l{config/config.pro}
\endlist
Every example page (such as this one) needs a Qt project file. QDoc will
use the project file to determine which files are part of the example. QDoc
will then create a page listing all the files that are part of the example.
\note the directory name of the example and the name of the project file
must match. The example directory is found using the
\l{qdoc-input-output-dir}{exampledirs} variable.
*/

6
src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc
View File

@ -107,7 +107,7 @@ marked with the \l{c-command}{\\c} command in the case of boolean values.
\section1 Properties
The property documentation resides immediately above the read function's
implementation. The \l{topic-commands}{topic command} for properties is
implementation. The \l{writing-topic-commands}{topic command} for properties is
\l{property-command}{\\property}.
\snippet examples/cpp.qdoc.sample property
@ -138,7 +138,7 @@ The values range from 0.0 (no blur) to maximumRadius (maximum blur). By default,
\endquotation
\section1 Signals, Notifiers, and Slots
The \l{topic-commands}{topic command} for signals, notifiers, and slots
The \l{writing-topic-commands}{topic command} for signals, notifiers, and slots
is \l{fn-command}{\\fn}. Signal documentation state when they are triggered
or emitted.
@ -168,7 +168,7 @@ the notifier.
\section1 Enums, Namespaces, and other Types
Enums, namespaces, and macros have a \l{topic-command} for their documentation:
Enums, namespaces, and macros have a \l{writing-topic-commands}{topic command} for their documentation:
\list
\li \l{enum-command}{\\enum}
\li \l{typedef-command}{\\typedef}

164
src/tools/qdoc/doc/qdoc-manual-DITA.qdoc Normal file
View File

@ -0,0 +1,164 @@
/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page 21-0-qdoc-creating-dita-maps.html
\previouspage Miscellaneous
\contentspage QDoc Manual
\nextpage The QDoc Configuration File
\title Creating DITA Maps
You can create DITA map files using three new qdoc commands, the \l{ditamap-command}
{ditamap} command, the \l{topicref-command} {topicref} command, and the \l{mapref-command}
{mapref} command. How these DITA maps will be used automatically or manually by the
documentation build process is still under consideration. This section will be updated
as the decisions are made.
\section1 What is a DITA map?
A complete description of DITA can be found at the
\l{http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita}
{OASIS Darwin Information Typing Architecture} site.
An explanation of the DITA map is found at that site
\l{http://docs.oasis-open.org/dita/v1.2/os/spec/langref/map.html}{here}.
\target ditamap-command
\section1 \\ditamap
The \\ditamap command is for creating a DITA map using qdoc commands.
The \\ditamap command is a kind of \\page command that produces a
\e{.ditamap} instead of a \e{.html} or \e{.xml} file. The file that
is created actually contains XML text, but the \e{.ditamap} suffix is
used to identify the file as containing a DITA MAP.
The argument is the name of the file to be created. In the following
example, the file \e{creator.ditamap} is output:
\code
\ditamap creator.ditamap
\endcode
\target topicref-command
\section1 \\topicref \\endtopicref
The \\topicref \\endtopicref commands are for creating a topicref
in the ditamap. The \\endtopicref command is required because
\\topicref commands can be nested.
\\topicref has two arguments. The first argument becomes the value
of the \e navtitle attribute. Normally, you use the title of the
topic being referenced. This title is often what will appear in a
table of contents constructed from the ditamap.
The second argument is the name of the page being referenced. The
second argument is actually optional, for example if you are using
a topicref as a container for other topicrefs and maprefs. It is
also optional if you want qdoc to find the page name for you by
looking up the title in its internal data structure. It is recommended
that you provide the second parameter if you know the page name.
\code
\topicref {QML Module QtQuick 2} {qtquick-2.xml}
\mapref {Creator Manual} {creator-manual.ditamap} \endmapref
\topicref {QML Mouse Events} {qtquick2-mouseevents.xml} \endtopicref
\topicref {Property Binding} {qtquick2-propertybinding.xml} \endtopicref
\endtopicref
\endcode
\target mapref-command
\section1 \\mapref
The \\mapref command is for creating a mapref in the ditamap. A
mapref refers to another ditamap, which you want to include in
your ditamap. Like the \\topicref command, the \\mapref command
has two arguments, but for the \\mapref command, both arguments
are required. The arguments are essentially the same as described
for \\topicref, but for \\mapref, the second command must be the
name of another ditamap, i.e. it must have the \e{.ditamap}
suffix. You must provide the file name. qdoc can't look up the
file name for you.
\code
\mapref {Creator Manual} {creator-manual.ditamap} \endmapref
\endcode
\section1 An example ditamap page
The following example uses the three qdoc ditamap commands described above.
\code
\ditamap creator.ditamap
\title The DITA Map for Creator
\topicref {QML Module QtQuick 1}
\topicref {QML Mouse Events} \endtopicref
\topicref {Property Binding} \endtopicref
\endtopicref
\topicref {QML Module QtQuick 2} {qtquick-2.xml}
\mapref {Creator Manual} {creator-manual.ditamap} \endmapref
\topicref {QML Mouse Events} {qtquick2-mouseevents.xml} \endtopicref
\topicref {Property Binding} {qtquick2-propertybinding.xml} \endtopicref
\endtopicref
\topicref {QML Module QtQuick.Particles 2} {qtquick-particles-2.xml}
\topicref {Age} {qml-qtquick-particles2-age.xml} \endtopicref
\endtopicref
\endcode
\section1 The resulting ditamap file
This is the \e{.ditamap} file you get when you input the qdoc
ditamap page shown above. Note that you can write ditamap files
directly in XML just as easily as you can write them using the
qdoc commands. The choice is yours.
\code
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
<topicmeta>
<shortdesc>The DITA Map for Creator</shortdesc>
</topicmeta>
<topicref navtitle="QML Module QtQuick 1" href="qtquick-1.xml">
<topicref navtitle="QML Mouse Events" href="qtquick2-mouseevents.xml"/>
<topicref navtitle="Property Binding" href="qtquick2-propertybinding.xml"/>
</topicref>
<topicref navtitle="QML Module QtQuick 2" href="qtquick-2.xml">
<mapref navtitle="Creator Manual" href="creator-manual.ditamap"/>
<topicref navtitle="QML Mouse Events" href="qtquick2-mouseevents.xml"/>
<topicref navtitle="Property Binding" href="qtquick2-propertybinding.xml"/>
</topicref>
<topicref navtitle="QML Module QtQuick.Particles 2" href="qtquick-particles-2.xml">
<topicref navtitle="Age" href="qml-qtquick-particles2-age.xml"/>
</topicref>
</map>
\endcode
*/

159
src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc Normal file
View File

@ -0,0 +1,159 @@
/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page 27-qdoc-commands-alphabetical.html
\previouspage Introduction to QDoc
\contentspage QDoc Manual
\nextpage Topic Commands
\title Command Index
This is a complete, alphabetized list of the QDoc commands.
\list
\li \l {04-qdoc-commands-textmarkup.html#a-command} {\\a}
\li \l {11-qdoc-commands-specialcontent.html#abstract-command} {\\abstract}
\li \l {12-0-qdoc-commands-miscellaneous.html#annotatedlist-command} {\\annotatedlist}
\li \l {04-qdoc-commands-textmarkup.html#b-command} {\\b} \span {class="newStuff"} {(new 5/3/2012)}
\li \l {04-qdoc-commands-textmarkup.html#b-command} {\\bold} \span {class="newStuff"} {(deprecated, use \\b)}
\li \l {11-qdoc-commands-specialcontent.html#brief-command} {\\brief}
\li \l {04-qdoc-commands-textmarkup.html#c-command} {\\c}
\li \l {09-qdoc-commands-includingimages.html#caption-command} {\\caption}
\li \l {05-qdoc-commands-documentstructure.html#chapter-command} {\\chapter}
\li \l {13-qdoc-commands-topics.html#class-command} {\\class}
\li \l {06-qdoc-commands-includecodeinline.html#code-command} {\\code}
\li \l {07-0-qdoc-commands-includingexternalcode.html#codeline-command} {\\codeline},
\li \l {16-qdoc-commands-status.html#compat-command} {\\compat}
\li \l {15-qdoc-commands-navigation.html#contentspage-command} {\\contentspage}
\li \l {16-qdoc-commands-status.html#default-command} {\\default}
\li \l {21-0-qdoc-creating-dita-maps.html#ditamap-command} {\\ditamap} \span {class="newStuff"} {(new 05/03/12)}
\li \l {04-qdoc-commands-textmarkup.html#div-command} {\\div}
\li \l {07-0-qdoc-commands-includingexternalcode.html#dots-command} {\\dots}
\li \l {04-qdoc-commands-textmarkup.html#e-command} {\\e} \span {class="newStuff"} {(new 5/3/2012)}
\li \l {12-0-qdoc-commands-miscellaneous.html#else-command} {\\else}
\li \l {12-0-qdoc-commands-miscellaneous.html#endif-command} {\\endif}
\li \l {13-qdoc-commands-topics.html#enum-command} {\\enum}
\li \l {13-qdoc-commands-topics.html#example-command} {\\example}
\li \l {13-qdoc-commands-topics.html#externalpage-command} {\\externalpage}
\li \l {13-qdoc-commands-topics.html#fn-command} {\\fn}
\li \l {11-qdoc-commands-specialcontent.html#footnote-command} {\\footnote}
\li \l {12-0-qdoc-commands-miscellaneous.html#generatelist-command} {\\generatelist}
\li \l {13-qdoc-commands-topics.html#group-command} {\\group}
\li \l {10-qdoc-commands-tablesandlists.html#header-command} {\\header}
\li \l {13-qdoc-commands-topics.html#headerfile-command} {\\headerfile}
\li \l {04-qdoc-commands-textmarkup.html#e-command} {\\i} \span {class="newStuff"} {(deprecated, use \\e)}
\li \l {12-0-qdoc-commands-miscellaneous.html#if-command} {\\if}
\li \l {09-qdoc-commands-includingimages.html#image-command} {\\image}
\li \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\include}
\li \l {15-qdoc-commands-navigation.html#indexpage-command} {\\indexpage}
\li \l {19-qdoc-commands-grouping.html#ingroup-command} {\\ingroup}
\li \l {18-qdoc-commands-relating.html#inherits-command}{\\inherits}
\li \l {09-qdoc-commands-includingimages.html#inlineimage-command} {\\inlineimage}
\li \l {19-qdoc-commands-grouping.html#inmodule-command} {\\inmodule}
\li \l {13-qdoc-commands-topics.html#inqmlmodule-command} {\\inqmlmodule}
\li \l {13-qdoc-commands-topics.html#instantiates-command} {\\instantiates} \span {class="newStuff"} {(new 27/7/2012)}
\li \l {16-qdoc-commands-status.html#internal-command} {\\internal}
\li \l {08-qdoc-commands-creatinglinks.html#keyword-command} {\\keyword}
\li \l {08-qdoc-commands-creatinglinks.html#l-command} {\\l}
\li \l {11-qdoc-commands-specialcontent.html#legalese-command} {\\legalese}
\li \l {10-qdoc-commands-tablesandlists.html#li-command} {\\li} \span {class="newStuff"} {(new 5/3/2012)}
\li \l {10-qdoc-commands-tablesandlists.html#list-command} {\\list}
\li \l {13-qdoc-commands-topics.html#macro-command} {\\macro}
\li \l {19-qdoc-commands-grouping.html#mainclass-command} {\\mainclass}
\li \l {21-0-qdoc-creating-dita-maps.html#mapref-command} {\\mapref} \span {class="newStuff"} {(new 05/03/12)}
\li \l {12-0-qdoc-commands-miscellaneous.html#meta-command} {\\meta}
\li \l {13-qdoc-commands-topics.html#module-command} {\\module}
\li \l {13-qdoc-commands-topics.html#namespace-command} {\\namespace}
\li \l {15-qdoc-commands-navigation.html#nextpage-command} {\\nextpage}
\li \l {06-qdoc-commands-includecodeinline.html#newcode-command} {\\newcode}
\li \l {17-qdoc-commands-thread.html#nonreentrant-command} {\\nonreentrant}
\li \l {11-qdoc-commands-specialcontent.html#note-command} {\\note}
\li \l {10-qdoc-commands-tablesandlists.html#li-command} {\\o} \span {class="newStuff"} {(deprecated, use \\li)}
\li \l {16-qdoc-commands-status.html#obsolete-command} {\\obsolete}
\li \l {06-qdoc-commands-includecodeinline.html#oldcode-command} {\\oldcode}
\li \l {12-0-qdoc-commands-miscellaneous.html#omit-command} {\\omit}
\li \l {10-qdoc-commands-tablesandlists.html#omitvalue-command} {\\omitvalue}
\li \l {18-qdoc-commands-relating.html#overload-command} {\\overload}
\li \l {13-qdoc-commands-topics.html#page-command} {\\page}
\li \l {05-qdoc-commands-documentstructure.html#part-command} {\\part}
\li \l {16-qdoc-commands-status.html#preliminary-command} {\\preliminary}
\li \l {15-qdoc-commands-navigation.html#previouspage-command} {\\previouspage}
\li \l {07-0-qdoc-commands-includingexternalcode.html#printline-command} {\\printline}
\li \l {07-0-qdoc-commands-includingexternalcode.html#printto-command} {\\printto}
\li \l {07-0-qdoc-commands-includingexternalcode.html#printuntil-command} {\\printuntil}
\li \l {13-qdoc-commands-topics.html#property-command} {\\property}
\li \l {13-qdoc-commands-topics.html#qmlattachedproperty-command} {\\qmlattachedproperty}
\li \l {13-qdoc-commands-topics.html#qmlattachedsignal-command} {\\qmlattachedsignal}
\li \l {13-qdoc-commands-topics.html#qmlbasictype-command} {\\qmlbasictype}
\li \l {13-qdoc-commands-topics.html#qmlclass-command} {\\qmlclass} \span {class="newStuff"} {(deprecated, use \\qmltype)}
\li \l {13-qdoc-commands-topics.html#qmltype-command} {\\qmltype} \span {class="newStuff"} {(new 27/7/2012)}
\li \l {13-qdoc-commands-topics.html#qmlmethod-command} {\\qmlmethod}
\li \l {13-qdoc-commands-topics.html#qmlproperty-command} {\\qmlproperty}
\li \l {13-qdoc-commands-topics.html#qmlsignal-command} {\\qmlsignal}
\li \l {13-qdoc-commands-topics.html#qmlmodule-command} {\\qmlmodule}
\li \l {11-qdoc-commands-specialcontent.html#quotation-command} {\\quotation}
\li \l {07-0-qdoc-commands-includingexternalcode.html#quotefile-command} {\\quotefile}
\li \l {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} {\\quotefromfile}
\li \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\raw} \span {class="newStuff"} {(avoid)}
\li \l {17-qdoc-commands-thread.html#reentrant-command} {\\reentrant}
\li \l {18-qdoc-commands-relating.html#reimp-command} {\\reimp}
\li \l {18-qdoc-commands-relating.html#relates-command} {\\relates}
\li \l {10-qdoc-commands-tablesandlists.html#row-command} {\\row}
\li \l {08-qdoc-commands-creatinglinks.html#sa-command} {\\sa}
\li \l {05-qdoc-commands-documentstructure.html#sectionOne-command} {\\section1}
\li \l {05-qdoc-commands-documentstructure.html#sectionTwo-command} {\\section2}
\li \l {05-qdoc-commands-documentstructure.html#sectionThree-command} {\\section3}
\li \l {05-qdoc-commands-documentstructure.html#sectionFour-command} {\\section4}
\li \l {13-qdoc-commands-topics.html#service-command} {\\service}
\li \l {16-qdoc-commands-status.html#since-command} {\\since}
\li \l {07-0-qdoc-commands-includingexternalcode.html#skipline-command} {\\skipline}
\li \l {07-0-qdoc-commands-includingexternalcode.html#skipto-command} {\\skipto}
\li \l {07-0-qdoc-commands-includingexternalcode.html#skipuntil-command} {\\skipuntil}
\li \l {07-0-qdoc-commands-includingexternalcode.html#snippet-command} {\\snippet},
\li \l {04-qdoc-commands-textmarkup.html#span-command} {\\span}
\li \l {15-qdoc-commands-navigation.html#startpage-command} {\\startpage}
\li \l {04-qdoc-commands-textmarkup.html#sub-command} {\\sub}
\li \l {20-qdoc-commands-namingthings.html#subtitle-command} {\\subtitle}
\li \l {04-qdoc-commands-textmarkup.html#sup-command} {\\sup}
\li \l {10-qdoc-commands-tablesandlists.html#table-command} {\\table}
\li \l {11-qdoc-commands-specialcontent.html#tableofcontents-command} {\\tableofcontents}
\li \l {08-qdoc-commands-creatinglinks.html#target-command} {\\target}
\li \l {17-qdoc-commands-thread.html#threadsafe-command} {\\threadsafe}
\li \l {20-qdoc-commands-namingthings.html#title-command} {\\title}
\li \l {21-0-qdoc-creating-dita-maps.html#topicref-command} {\\topicref} \span {class="newStuff"} {(new 05/03/12)}
\li \l {04-qdoc-commands-textmarkup.html#tt-command} {\\tt}
\li \l {13-qdoc-commands-topics.html#typedef-command} {\\typedef}
\li \l {04-qdoc-commands-textmarkup.html#uicontrol-command} {\\uicontrol} {(new 25/3/2012)}
\li \l {04-qdoc-commands-textmarkup.html#underline-command} {\\underline}
\li \l {13-qdoc-commands-topics.html#variable-command} {\\variable}
\li \l {10-qdoc-commands-tablesandlists.html#value-command} {\\value}
\li \l {11-qdoc-commands-specialcontent.html#warning-command} {\\warning}
\endlist
*/

1076
src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc Normal file
View File

File diff suppressed because it is too large Load Diff

181
src/tools/qdoc/doc/qdoc-manual-intro.qdoc Normal file
View File

@ -0,0 +1,181 @@
/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page 01-qdoc-manual.html
\contentspage QDoc Manual
\previouspage QDoc Manual
\nextpage Command Index
\title Introduction to QDoc
QDoc is a tool used by Qt Developers to generate documentation for
software projects. It works by extracting \e {QDoc comments} from
project source files and then formatting these comments as HTML
pages or DITA XML documents. QDoc finds QDoc comments in \c
{.cpp} files and in \c {.qdoc} files. QDoc does not look for QDoc
comments in \c {.h} files. A QDoc comment always begins with an
exclamation mark (\b{!})). For example:
\code
/ *!
\class QObject
\brief The QObject class is the base class of all Qt objects.
\ingroup objectmodel
\reentrant
QObject is the heart of the Qt \l{Object Model}. The
central feature in this model is a very powerful mechanism
for seamless object communication called \l{signals and
slots}. You can connect a signal to a slot with connect()
and destroy the connection with disconnect(). To avoid
never ending notification loops you can temporarily block
signals with blockSignals(). The protected functions
connectNotify() and disconnectNotify() make it possible to
track connections.
QObjects organize themselves in \l {Object Trees &
Ownership} {object trees}. When you create a QObject with
another object as parent, the object will automatically
add itself to the parent's \c children() list. The parent
takes ownership of the object. It will automatically
delete its children in its destructor. You can look for an
object by name and optionally type using findChild() or
findChildren().
Every object has an objectName() and its class name can be
found via the corresponding metaObject() (see
QMetaObject::className()). You can determine whether the
object's class inherits another class in the QObject
inheritance hierarchy by using the \c inherits() function.
....
* /
\endcode
From the QDoc comment above, QDoc generates the HTML page
\l {http://qt-project.org/doc/qt-5.0/qtcore/qobject.html#details}
{QObject Class Reference}.
This manual explains how to use the QDoc commands in QDoc comments
to embed good documentation in your source files. It also explains
how to make a \l {The QDoc Configuration File} {QDoc configuration
file}, which you will pass to QDoc on the command line.
\section1 Running QDoc
The current name of the QDoc program is \c {qdoc}. To run qdoc
from the command line, give it the name of a configuration file:
\quotation
\c {$ ../../bin/qdoc ./config.qdocconf}
\endquotation
QDoc recognizes the \c {.qdocconf} suffix as a \l{The QDoc
Configuration File} {QDoc configuration file}. The configuration
file is where you tell QDoc where to find the project source
files, header files, and \c {.qdoc} files. It is also where you
tell QDoc what kind of output to generate (HTML, DITA XML,...),
and where to put the generated documentation. The configuration
file also contains other information for QDoc.
See \l{The QDoc Configuration File} for instructions on how to
set up a QDoc configuration file.
\section1 How QDoc works
QDoc begins by reading the configuration file you specified on the
command line. It stores all the variables from the configuration
file for later use. One of the first variables it uses is \c
{outputformats}. This variable tells QDoc which output generators
it will run. The default value is \e {HTML}, so if you don't set
\c {outputformats} in your configuration file, QDoc will generate
HTML output. That's usually what you will want anyway, but you can
also specify \e {DITAXML} to get DITA XML output instead.
Next, QDoc uses the values of the
\l {22-qdoc-configuration-generalvariables.html#headerdirs-variable}
{headerdirs} variable and/or the \l
{22-qdoc-configuration-generalvariables.html#headers-variable}
{headers} variable to find and parse all the header files for your
project. QDoc does \e not scan header files for QDoc comments. It
parses the header files to build a master tree of all the items
that should be documented, in other words, the items that QDoc should find
QDoc comments for.
After parsing all the header files and building the master tree of
items to be documented, QDoc uses the value of the \l
{22-qdoc-configuration-generalvariables.html#sourcedirs-variable}
{sourcedirs} variable and/or the value of the \l
{22-qdoc-configuration-generalvariables.html#sources-variable}
{sources} variable to find and parse all the \c {.cpp} and \c
{.qdoc} files for your project. These are the files QDoc scans for
\e {QDoc comments}. Remember that a QDoc comment begins with
an exclamation mark: \b {/*!} .
For each QDoc comment it finds, it searches the master tree for
the item where the documentation belongs. Then it interprets the
qdoc commands in the comment and stores the interpreted commands
and the comment text in the tree node for the item.
Finally, QDoc traverses the master tree. For each node, if the
node has stored documentation, QDoc calls the output generator
specified by the \c {outputformats} variable to format and write
the documentation in the directory specified in the configuration
file in the \l
{22-qdoc-configuration-generalvariables.html#outputdir-variable}
{outputdir} variable.
\section1 Command Types
QDoc interprets three types of commands:
\list
\li \l {Topic Commands}
\li \l {Context Commands}
\li \l {Markup Commands}
\endlist
Topic commands identify the element you are documenting, for example
a C++ class, function, type, or an extra page of text
that doesn't map to an underlying C++ element.
Context commands tell QDoc how the element being documented
relates to other documented elements, for example, next and previous page
links, inclusion in page groups, or library modules. Context
commands can also provide information about the documented element
that QDoc can't get from the source files, for example, whether the
element is thread-safe, whether it is an overloaded or reimplemented function,
or whether it has been deprecated.
Markup commands tell QDoc how text and image elements in the
document should be rendered, or about the document's outline
structure.
*/

3967
src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc Normal file
View File

File diff suppressed because it is too large Load Diff

78
src/tools/qdoc/doc/qdoc-manual-qdocconf-minimal.qdoc
View File

@ -1,78 +0,0 @@
/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qdoc-manual-qdocconf-minimal
\title Minimal qdocconf file
\brief Describes a qdocconf file with a minimal number of statements
The full contents of the minimal qdocconf file:
\code
#include(compat.qdocconf)
headerdirs = .
sourcedirs = .
exampledirs = .
imagedirs = ./images
\endcode
\title Statements with Comments
\code
#include(compat.qdocconf)
\endcode
In order to avoid compatibility issues between different versions of QDoc,
it is advised to include compat.qdocconf.
\code
headerdirs = .
\endcode
The header files associated with the .cpp source files can be found in the
current directory.
\code
#sourcedirs = .
\endcode
The .cpp or .qdoc files can be found in the current directory.
\code
exampledirs = .
\endcode
The source code of the example files can be found in the current directory.
\code
imagedirs = ./images
\endcode
The images used in the documentation can be found in subdirectory \e images.
\note Please take care with this minimal qdocconf file. Using it in the wrong directory could cause qdoc to include a large number of files.
*/

1603
src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc Normal file
View File

File diff suppressed because it is too large Load Diff

1608
src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc Normal file
View File

File diff suppressed because it is too large Load Diff

8719
src/tools/qdoc/doc/qdoc-manual.qdoc
View File

File diff suppressed because it is too large Load Diff

3
src/tools/qdoc/doc/qdoc-minimum-qdocconf.qdoc
View File

@ -26,7 +26,8 @@
****************************************************************************/
/*!
\page qdoc-minimum-qdocconf.html
\title A minimal qdocconf file with Comments
\target minimal-qdocconf
\title A minimal qdocconf file
\brief Describes a minimal .qdocconf file

2
src/tools/qdoc/doc/qtgui-qdocconf.qdoc
View File

@ -289,7 +289,7 @@ When executed, QDoc will ignore the directories listed.
exampledirs += ../../../examples/gui \
snippets
\endcode
\sa examples
\sa {examples-variable}{examples}
\sa examplesinstallpath
Add the two directories specified to the list of directories containing the source