1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

qdoc3: qdoc user manual update

Browse Source 
Changed \bold to \b, \i to \e, and \o to \li.

Task-number:  QTBUG-24578

Change-Id: If02517164f30f05436596224c1b1895a86d9e9f8
Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com>
This commit is contained in:
Martin Smith 2012-03-08 11:57:34 +01:00 committed by Qt by Nokia
parent bc3a6c75f8
commit 11eed81ae9
9 changed files with 1046 additions and 815 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
src/tools/qdoc/doc/config/compat.qdocconf
View File

@ -1,28 +1,9 @@
alias.i = e
alias.include = input
macro.0 = "\\\\0"
macro.b = "\\\\b"
macro.n = "\\\\n"
macro.r = "\\\\r"
macro.i = "\\o"
macro.i11 = "\\o{1,1}"
macro.i12 = "\\o{1,2}"
macro.i13 = "\\o{1,3}"
macro.i14 = "\\o{1,4}"
macro.i15 = "\\o{1,5}"
macro.i16 = "\\o{1,6}"
macro.i17 = "\\o{1,7}"
macro.i18 = "\\o{1,8}"
macro.i19 = "\\o{1,9}"
macro.i21 = "\\o{2,1}"
macro.i31 = "\\o{3,1}"
macro.i41 = "\\o{4,1}"
macro.i51 = "\\o{5,1}"
macro.i61 = "\\o{6,1}"
macro.i71 = "\\o{7,1}"
macro.i81 = "\\o{8,1}"
macro.i91 = "\\o{9,1}"
macro.img = "\\image"
macro.endquote = "\\endquotation"
macro.relatesto = "\\relates"

4
src/tools/qdoc/doc/examples/componentset/ProgressBar.qml
View File

@ -83,12 +83,12 @@ Item {
QDoc will not publish the documentation within omit and endomit.
\endomit
\sa secondcolor
\sa secondColor
*/
property alias color: gradient1.color
/*!
\qmlproperty color ProgressBar::secondcolor
\qmlproperty color ProgressBar::secondColor
The second color of the ProgressBar's gradient.
Must bind to a color type.

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

@ -34,12 +34,12 @@
In particular, there are sample components that are documented with QDoc
commands comments. There are documentation comments for the QML components
and their public interfaces. The components are grouped into a module, the
\l {UI Components} module.
\l{UI Components} module.
The \l{componentset/uicomponents.qdoc}{uicomponents.qdoc} file generates
the overview page for the \l {UI Components} module page.
the overview page for the \l{UI Components} module page.
The generated documentation is available in the \l {UI Components} module.
The generated documentation is available in the \l{UI Components} module.
\section1 QML Class

8
src/tools/qdoc/doc/examples/layoutmanagement.qdocinc
View File

@ -6,8 +6,8 @@ the layout of child widgets.
By specifying the logical layout once, you get the following benefits:
\list
\o Positioning of child widgets.
\o Sensible default sizes for windows.
\o Sensible minimum sizes for windows.
\o ...
\li Positioning of child widgets.
\li Sensible default sizes for windows.
\li Sensible minimum sizes for windows.
\li ...
\endlist

251
src/tools/qdoc/doc/examples/mainwindow.cpp Normal file
View File

@ -0,0 +1,251 @@
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the tools applications of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** GNU Lesser General Public License Usage
** This file may be used under the terms of the GNU Lesser General Public
** License version 2.1 as published by the Free Software Foundation and
** appearing in the file LICENSE.LGPL included in the packaging of this
** file. Please review the following information to ensure the GNU Lesser
** General Public License version 2.1 requirements will be met:
** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights. These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU General
** Public License version 3.0 as published by the Free Software Foundation
** and appearing in the file LICENSE.GPL included in the packaging of this
** file. Please review the following information to ensure the GNU General
** Public License version 3.0 requirements will be met:
** http://www.gnu.org/copyleft/gpl.html.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms and
** conditions contained in a signed written agreement between you and Nokia.
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
#include <QtWidgets>
#include "mainwindow.h"
#include "scribblearea.h"
//! [0]
MainWindow::MainWindow()
{
scribbleArea = new ScribbleArea;
setCentralWidget(scribbleArea);
createActions();
createMenus();
setWindowTitle(tr("Scribble"));
resize(500, 500);
}
//! [0]
//! [1]
void MainWindow::closeEvent(QCloseEvent *event)
//! [1] //! [2]
{
if (maybeSave()) {
event->accept();
} else {
event->ignore();
}
}
//! [2]
//! [3]
void MainWindow::open()
//! [3] //! [4]
{
if (maybeSave()) {
QString fileName = QFileDialog::getOpenFileName(this,
tr("Open File"), QDir::currentPath());
if (!fileName.isEmpty())
scribbleArea->openImage(fileName);
}
}
//! [4]
//! [5]
void MainWindow::save()
//! [5] //! [6]
{
QAction *action = qobject_cast<QAction *>(sender());
QByteArray fileFormat = action->data().toByteArray();
saveFile(fileFormat);
}
//! [6]
//! [7]
void MainWindow::penColor()
//! [7] //! [8]
{
QColor newColor = QColorDialog::getColor(scribbleArea->penColor());
if (newColor.isValid())
scribbleArea->setPenColor(newColor);
}
//! [8]
//! [9]
void MainWindow::penWidth()
//! [9] //! [10]
{
bool ok;
int newWidth = QInputDialog::getInteger(this, tr("Scribble"),
tr("Select pen width:"),
scribbleArea->penWidth(),
1, 50, 1, &ok);
if (ok)
scribbleArea->setPenWidth(newWidth);
}
//! [10]
//! [11]
void MainWindow::about()
//! [11] //! [12]
{
QMessageBox::about(this, tr("About Scribble"),
tr("<p>The <b>Scribble</b> example shows how to use QMainWindow as the "
"base widget for an application, and how to reimplement some of "
"QWidget's event handlers to receive the events generated for "
"the application's widgets:</p><p> We reimplement the mouse event "
"handlers to facilitate drawing, the paint event handler to "
"update the application and the resize event handler to optimize "
"the application's appearance. In addition we reimplement the "
"close event handler to intercept the close events before "
"terminating the application.</p><p> The example also demonstrates "
"how to use QPainter to draw an image in real time, as well as "
"to repaint widgets.</p>"));
}
//! [12]
//! [13]
void MainWindow::createActions()
//! [13] //! [14]
{
openAct = new QAction(tr("&Open..."), this);
openAct->setShortcuts(QKeySequence::Open);
connect(openAct, SIGNAL(triggered()), this, SLOT(open()));
foreach (QByteArray format, QImageWriter::supportedImageFormats()) {
QString text = tr("%1...").arg(QString(format).toUpper());
QAction *action = new QAction(text, this);
action->setData(format);
connect(action, SIGNAL(triggered()), this, SLOT(save()));
saveAsActs.append(action);
}
printAct = new QAction(tr("&Print..."), this);
connect(printAct, SIGNAL(triggered()), scribbleArea, SLOT(print()));
exitAct = new QAction(tr("E&xit"), this);
exitAct->setShortcuts(QKeySequence::Quit);
connect(exitAct, SIGNAL(triggered()), this, SLOT(close()));
penColorAct = new QAction(tr("&Pen Color..."), this);
connect(penColorAct, SIGNAL(triggered()), this, SLOT(penColor()));
penWidthAct = new QAction(tr("Pen &Width..."), this);
connect(penWidthAct, SIGNAL(triggered()), this, SLOT(penWidth()));
clearScreenAct = new QAction(tr("&Clear Screen"), this);
clearScreenAct->setShortcut(tr("Ctrl+L"));
connect(clearScreenAct, SIGNAL(triggered()),
scribbleArea, SLOT(clearImage()));
aboutAct = new QAction(tr("&About"), this);
connect(aboutAct, SIGNAL(triggered()), this, SLOT(about()));
aboutQtAct = new QAction(tr("About &Qt"), this);
connect(aboutQtAct, SIGNAL(triggered()), qApp, SLOT(aboutQt()));
}
//! [14]
//! [15]
void MainWindow::createMenus()
//! [15] //! [16]
{
saveAsMenu = new QMenu(tr("&Save As"), this);
foreach (QAction *action, saveAsActs)
saveAsMenu->addAction(action);
fileMenu = new QMenu(tr("&File"), this);
fileMenu->addAction(openAct);
fileMenu->addMenu(saveAsMenu);
fileMenu->addAction(printAct);
fileMenu->addSeparator();
fileMenu->addAction(exitAct);
optionMenu = new QMenu(tr("&Options"), this);
optionMenu->addAction(penColorAct);
optionMenu->addAction(penWidthAct);
optionMenu->addSeparator();
optionMenu->addAction(clearScreenAct);
helpMenu = new QMenu(tr("&Help"), this);
helpMenu->addAction(aboutAct);
helpMenu->addAction(aboutQtAct);
menuBar()->addMenu(fileMenu);
menuBar()->addMenu(optionMenu);
menuBar()->addMenu(helpMenu);
}
//! [16]
//! [17]
bool MainWindow::maybeSave()
//! [17] //! [18]
{
if (scribbleArea->isModified()) {
QMessageBox::StandardButton ret;
ret = QMessageBox::warning(this, tr("Scribble"),
tr("The image has been modified.\n"
"Do you want to save your changes?"),
QMessageBox::Save | QMessageBox::Discard
| QMessageBox::Cancel);
if (ret == QMessageBox::Save) {
return saveFile("png");
} else if (ret == QMessageBox::Cancel) {
return false;
}
}
return true;
}
//! [18]
//! [19]
bool MainWindow::saveFile(const QByteArray &fileFormat)
//! [19] //! [20]
{
QString initialPath = QDir::currentPath() + "/untitled." + fileFormat;
QString fileName = QFileDialog::getSaveFileName(this, tr("Save As"),
initialPath,
tr("%1 Files (*.%2);;All Files (*)")
.arg(QString(fileFormat.toUpper()))
.arg(QString(fileFormat)));
if (fileName.isEmpty()) {
return false;
} else {
return scribbleArea->saveImage(fileName, fileFormat);
}
}
//! [20]

4
src/tools/qdoc/doc/examples/minimum.qdocconf
View File

@ -36,7 +36,3 @@ exampledirs = .
# directories containing the images used in the documentation.
imagedirs = ./images

8
src/tools/qdoc/doc/examples/samples.qdocinc
View File

@ -39,7 +39,7 @@
The QVector3D class can also be used to represent vertices in 3D space.
We therefore do not need to provide a separate vertex class.
\bold{Note:} By design values in the QVector3D instance are stored as \c float.
\b{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.
@ -65,9 +65,9 @@
There are three essential materials for generating documentation with qdoc:
\list
\o \c qdoc binary
\o \c qdocconf configuration files
\o \c Documentation in \c C++, \c QML, and \c .qdoc files
\li \c qdoc binary
\li \c qdocconf configuration files
\li \c Documentation in \c C++, \c QML, and \c .qdoc files
\endlist
*/
//! [sample-page]

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

@ -39,9 +39,9 @@
There are three essential materials for generating documentation with qdoc:
\list
\o \c QDoc binary
\o \c qdocconf configuration files
\o \c Documentation in \c C++, \c QML, and \c .qdoc files
\li \c QDoc binary
\li \c qdocconf configuration files
\li \c Documentation in \c C++, \c QML, and \c .qdoc files
\endlist
This section intends to cover the basic necessities for creating a
@ -55,11 +55,11 @@
\section1 Chapters
\list 1
\o \l{Creating QDoc Configuration Files}
\o \l{Writing Documentation}
\o \l{Categories of Documentation}
\o \l{Configuration File Example}
\o \l{QML Documentation Example}
\li \l{Creating QDoc Configuration Files}
\li \l{Writing Documentation}
\li \l{Categories of Documentation}
\li \l{Configuration File Example}
\li \l{QML Documentation Example}
\endlist
*/
@ -236,9 +236,6 @@
HTML file, which will appear as the Greek \pi symbol when viewed in
browsers.
There is quite a long list of macros for inserting text and
\l{alias-variable}{aliases} available.
\section2 QML Additions
QDoc is able to parse QML files for QDoc comments. QDoc will parse files
@ -296,21 +293,21 @@
Example of topic commands:
\list
\o \l{enum-command}{\\enum} - for enumeration documentation
\o \l{class-command}{\\class} - for C++ class documentation
\o \l{qmlclass-command}{\\qmlclass} - for QML component documentation
\o \l{page-command}{\\page} - for creating a page.
\li \l{enum-command}{\\enum} - for enumeration documentation
\li \l{class-command}{\\class} - for C++ class documentation
\li \l{qmlclass-command}{\\qmlclass} - for QML component documentation
\li \l{page-command}{\\page} - for creating a page.
\endlist
The \l{page-command}{\\page} 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:
\list
\o \c howto
\o \c overview
\o \c tutorial
\o \c faq
\o \c article - \e default when there is no type
\li \c howto
\li \c overview
\li \c tutorial
\li \c faq
\li \c article - \e default when there is no type
\endlist
\snippet examples/samples.qdocinc sample-faq
@ -338,12 +335,12 @@
\target writing-markup
\section2 Documentation Markup
QDoc can provide \e markup to content similar to other markup or
documentation tools. QDoc can mark a section of text in \bold{bold} when
the text is marked up with the \l{bold-command}{\\bold} command.
QDoc can do \e markup of text similar to other markup or
documentation tools. QDoc can mark a section of text in \b{bold},
when the text is marked up with the \l{b-command}{\\b} command.
\code
\bold{This} text will be in \bold{bold}.
\b{This} text will be in \b{bold}.
\endcode
The \l{Markup Commands} page has a full listing of the available markup
@ -355,15 +352,15 @@
ingredients present.
\list
\o Assign a topic to a QDoc comment - A comment could be a page, a
\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
\l{Topic Commands}{topic commands}.
\o Give the topic a context - QDoc can associate certain topics to other
\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 \l{obsolete-command}{\\obsolete}.
\o Mark sections of the document with
\li Mark sections of the document with
\l{Markup Commands}{markup commands} - QDoc can create layouts and
format the documentation for the documentation.
\endlist
@ -408,14 +405,14 @@
There are several types of predefined documentation \e categories or
\e types:
\list
\o How-To's
\o Tutorial
\o Overview
\o Article
\o FAQ (Frequently Asked Questions)
\o C++ API Documentation
\o QML Component Documentation
\o Code Example
\li How-To's
\li Tutorial
\li Overview
\li Article
\li FAQ (Frequently Asked Questions)
\li C++ API Documentation
\li QML Component Documentation
\li Code Example
\endlist
QDoc has the ability to format a page depending on the type. Further,
@ -453,42 +450,64 @@
A list of QML related QDoc commands:
\list
\o \l{qmlattachedproperty-command}{\\qmlattachedproperty}
\o \l{qmlattachedsignal-command}{\\qmlattachedsignal}
\o \l{qmlbasictype-command}{\\qmlbasictype}
\o \l{qmlclass-command}{\\qmlclass} - creates a QML component documentation
\o \l{qmlmethod-command}{\\qmlmethod}
\o \l{qmlproperty-command}{\\qmlproperty}
\o \l{qmlsignal-command}{\\qmlsignal}
\o \l{inherits-command}{\\inherits}
\o \l{qmlmodule-command}{\\qmlmodule}
\o \l{inqmlmodule-command}{\\inqmlmodule}
\li \l{qmlattachedproperty-command}{\\qmlattachedproperty}
\li \l{qmlattachedsignal-command}{\\qmlattachedsignal}
\li \l{qmlbasictype-command}{\\qmlbasictype}
\li \l{qmlclass-command}{\\qmlclass} - creates a QML component documentation
\li \l{qmlmethod-command}{\\qmlmethod}
\li \l{qmlproperty-command}{\\qmlproperty}
\li \l{qmlsignal-command}{\\qmlsignal}
\li \l{inherits-command}{\\inherits}
\li \l{qmlmodule-command}{\\qmlmodule}
\li \l{inqmlmodule-command}{\\inqmlmodule}
\endlist
\note Remember to enable QML parsing by including the \c{*.qml} filetype in
the \l{qdoc-input-output-dir}{fileextension} variable.
Essentially, to create an API documentation of a QML component, create
a QDoc comment with a \l{qmlclass-command}{\\qmlclass} command. Similar to
C++ API documentation, QML API are documented using their corresponding QDoc
commands.
To document a QML type, start by creating a QDoc comment that uses the
\l{qmlclass-command} {\\qmlclass} command as its topic command.
\section3 QML Parser
You may either document a QML component rom a C++ class or from a QML file.
QDoc supports both types and can parse both C++ and QML files.
If your QML type is defined in a \e qml file, document it there.
If your QML type is represented by a C++ class, document it in the
\e cpp file for that C++ class. Don't document a QML type in a
\e{cpp} file if the QML type is defined in a \e{qml} file.
In a QML file, you may simply place the QDoc comment above the property,
signal, handler, or method. QDoc will collect the comments and form the API
documentation. Additionally, QDoc can detect
\l{qml-property-aliases}{property-aliases}, but the property type must be
manually declared using the \l{qmlproperty-command}{\\qmlproperty} command.
When documenting a QML type in a \e{qml} file, place each QDoc
comment directly above the entity to which the comment applies.
For example, place the QDoc comment containing the \e{\\qmlclass}
command (the topic comment) directly above the outer QML type in
the \e{qml} 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 \e{qml} file, you don't normally include the
\e{\\qmlproperty} command as a topic command (which you must do
when documenting QML types in \e{cpp} 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 \e{\\qmlproperty} 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 \e must contain a \e{\\qmlproperty}
command, because that is the only way QDoc can know the type of
the aliased property.
QML components in C++ classes have their documentation above their property
or method documentation. However, the QML commands must be used instead of
the C++ documentation topic commands. Instead of the \c {\\class}
command, use the \l{qmlclass-command}{\\qmlclass} command.
When documenting a QML type in the \e cpp 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
\e{cpp} file. Note that QML QDoc comments in \e cpp files \e must
use the QML topic commands. i.e., the \l{qmlclass-command}
{\\qmlclass} command \e must appear in the QDoc comment for the
QML type, and a \l{qmlproperty-command} {\\qmlproperty} command \e
must appear in each QML property QDoc comment.
\section3 QML Modules
@ -500,14 +519,14 @@
Modules affect the way Qdoc link and relate the components. The
\l{qmlclass-command}{\\qmlclass} topic command must have an
\l{inqmlmodule-command}{\\inqmlmodule} context command to relate the
component to a module. Similarly, a \l{qmlmodule-command}{\\qmlmodule} topic
\l{inqmlmodule-command}{\\inqmlmodule} context command to relate the
component to a module. Similarly, a \l{qmlmodule-command}{\\qmlmodule} topic
command must exist in a separate \c .qdoc file to create the overview page
for the module. The overview page will list the related components.
The links to the components, must therefore, also contain the module name.
For example, if a component called \c TabWidget is in the \c UIComponents
module, it must be linked as \c {UIComponents::TabWidget}.
module, it must be linked as \c {UIComponents::TabWidget}.
The \l{componentset}{UIComponents} example demonstrates proper usage of
QDoc commands to document QML components and QML modules.
@ -607,10 +626,10 @@
\section1 Macros and other Definitions
\list
\o \l{config/compat.qdocconf}
\o \l{config/macros.qdocconf}
\o \l{config/qt-cpp-ignore.qdocconf}
\o \l{config/qt-defines.qdocconf}
\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
@ -624,9 +643,9 @@
\section1 Project Information
\list
\o \l{config/qdoc-online.qdocconf}
\o \l{config/qdoc.qdocconf}
\o \l{config/qdoc-project.qdocconf}
\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.
@ -643,10 +662,10 @@
\section1 HTML Styles
\list
\o \l{config/qt-html-default-styles.qdocconf}
\o \l{config/qt-html-online-styles.qdocconf}
\o \l{config/qt-html-templates-online.qdocconf}
\o \l{config/qt-html-templates.qdocconf}
\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.
@ -657,7 +676,7 @@
\section1 Project File
\list
\o \l{config/config.pro}
\li \l{config/config.pro}
\endlist
Every example page (such as this one) needs a Qt project file. QDoc will

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

File diff suppressed because it is too large Load Diff