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

Added API Reference Style Guidelines

Browse Source 
-added C++ and QML language guidelines as part of QDoc Guide
    -included snippets
-fixed links in the HTML template of the QDoc Guide
-compiles when the main QDoc manual is compiled

Change-Id: Iadd799712eef80e905d092396cb7a1e25a863b43
Reviewed-by: Geir Vattekar <geir.vattekar@nokia.com>
Reviewed-by: Qt Doc Bot <qt_docbot@qt-project.org>
Reviewed-by: Martin Smith <martin.smith@nokia.com>
This commit is contained in:
Jerome Pasion 2012-08-13 12:01:05 +02:00 committed by Qt by Nokia
parent df175f190d
commit 8c4ac07258
7 changed files with 617 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
src/tools/qdoc/doc/config/qt-html-templates-online.qdocconf
View File

@ -4,8 +4,8 @@ HTML.postheader = \
" <div class=\"header\" id=\"qtdocheader\">\n" \
" <div class=\"content\"> \n" \
" <div id=\"nav-logo\">\n" \
" <a href=\"index.html\">Home</a></div>\n" \
" <a href=\"index.html\" class=\"qtref\"><span>QDoc Reference Documentation</span></a>\n" \
" <a href=\"qdoc-index.html\">Home</a></div>\n" \
" <a href=\"qdoc-index.html\" class=\"qtref\"><span>QDoc Reference Documentation</span></a>\n" \
" <div id=\"narrowsearch\"></div>\n" \
" <div id=\"nav-topright\">\n" \
" <ul>\n" \
@ -19,7 +19,7 @@ HTML.postheader = \
" </div>\n" \
" <div id=\"shortCut\">\n" \
" <ul>\n" \
" <li class=\"shortCut-topleft-inactive\"><span><a href=\"index.html\">Qt 4.7</a></span></li>\n" \
" <li class=\"shortCut-topleft-inactive\"><span><a href=\"qdoc-index.html\">Qt 4.7</a></span></li>\n" \
" <li class=\"shortCut-topleft-active\"><a href=\"http://doc.qt.nokia.com\">ALL VERSIONS" \
" </a></li>\n" \
" </ul>\n" \
@ -35,7 +35,7 @@ HTML.postheader = \
" <div class=\"toolbar\">\n" \
" <div class=\"breadcrumb toolblock\">\n" \
" <ul>\n" \
" <li class=\"first\"><a href=\"index.html\">Home</a></li>\n" \
" <li class=\"first\"><a href=\"qdoc-index.html\">Home</a></li>\n" \
" <!-- Breadcrumbs go here -->\n"
HTML.postpostheader = \
@ -85,7 +85,7 @@ HTML.footer = \
# Files not referenced in any qdoc file.
# See also extraimages.HTML
qhp.QDoc.extraFiles = index.html \
qhp.QDoc.extraFiles = qdoc-index.html \
images/bg_l.png \
images/bg_l_blank.png \
images/bg_ll_blank.png \

6
src/tools/qdoc/doc/config/qt-html-templates.qdocconf
View File

@ -3,11 +3,11 @@ include(qt-html-default-styles.qdocconf)
HTML.postheader = \
"<div class=\"header\" id=\"qtdocheader\">\n" \
" <div class=\"content\"> \n" \
" <a href=\"index.html\" class=\"qtref\"><span>QDoc Reference Documentation</span></a>\n" \
" <a href=\"qdoc-index.html\" class=\"qtref\"><span>QDoc Reference Documentation</span></a>\n" \
" </div>\n" \
" <div class=\"breadcrumb toolblock\">\n" \
" <ul>\n" \
" <li class=\"first\"><a href=\"index.html\">Home</a></li>\n" \
" <li class=\"first\"><a href=\"qdoc-index.html\">Home</a></li>\n" \
" <!-- Breadcrumbs go here -->\n"
HTML.postpostheader = \
@ -44,7 +44,7 @@ HTML.footer = \
# Files not referenced in any qdoc file.
# See also extraimages.HTML
qhp.QDoc.extraFiles = index.html \
qhp.QDoc.extraFiles = qdoc-index.html \
images/arrow_down.png \
images/breadcrumb.png \
images/bullet_gt.png \

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

@ -0,0 +1,126 @@
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** 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$
**
****************************************************************************/
//![class]
/*!
\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
*/
//![class]
//![function]
/*!
\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)
//! [function]
//! [return]
/*!
Returns \c true if a QScroller object was already created for \a target; \c false otherwise.
\sa scroller()
*/
bool QScroller::hasScroller(QObject *target)
//! [return]
//! [property]
/*!
\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
//! [property]
//! [signals]
/*!
\fn QAbstractTransition::triggered()
This signal is emitted when the transition has been triggered (after
onTransition() has been called).
*/
//! [signals]
//! [enums]
/*!
\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.
*/
//! [enums]
//! [overloaded notifier]
/*!
\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.
*/
//! [overloaded notifier]

116
src/tools/qdoc/doc/examples/qml.qdoc Normal file
View File

@ -0,0 +1,116 @@
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** 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$
**
****************************************************************************/
//![qmltype]
\qmltype TextEdit
\instantiates QQuickTextEdit
\inqmlmodule QtQuick 2
\ingroup qtquick-visual
\ingroup qtquick-input
\inherits Item
\brief Displays multiple lines of editable formatted text
The TextEdit item displays a block of editable, formatted text.
It can display both plain and rich text. For example:
\qml
TextEdit {
width: 240
text: "<b>Hello</b> <i>World!</i>"
font.family: "Helvetica"
font.pointSize: 20
color: "blue"
focus: true
}
\endqml
\image declarative-textedit.gif
... omitted detailed description
\sa Text, TextInput, {examples/quick/text/textselection}{Text Selection example}
//![qmltype]
//![function]
/*
\qmlmethod QtQuick2::ListModel::remove(int index, int count = 1)
Deletes the content at \a index from the model.
\sa clear()
*/
void QQuickListModel::remove(QQmlV8Function *args)
//! [function]
//! [return]
/*
Returns \c true if a QScroller object was already created for \a target; \c false otherwise.
\sa scroller()
*/
bool QScroller::hasScroller(QObject *target)
//! [return]
//! [property]
/*
\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
//! [property]
//! [signals]
/*
This signal is emitted when the user clicks the button. A click is defined
as a press followed by a release. The corresponding handler is
\c onClicked.
*/
signal clicked()
//! [signals]
//! [enums]
/*!
\qmlproperty enumeration QtQuick2::Text::font.weight
Sets the font's weight.
The weight can be one of:
\list
\li Font.Light
\li Font.Normal - the default
\li Font.DemiBold
\li Font.Bold
\li Font.Black
\endlist
*/
//! [enums]

16
src/tools/qdoc/doc/qdoc-guide.qdoc → src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc
View File

@ -58,6 +58,10 @@
\li \l{Creating QDoc Configuration Files}
\li \l{Writing Documentation}
\li \l{Categories of Documentation}
\list
\li \l{C++ Documentation Style}
\li \l{QML Documentation Style}
\endlist
\li \l{Configuration File Example}
\li \l{QML Documentation Example}
\endlist
@ -439,6 +443,18 @@
\note QDoc uses the header files to inform itself about the class and will
not properly process QDoc comments in header files.
\section2 Language Styles
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.
\list
\li \l{C++ Documentation Style}
\li \l{QML Documentation Style}
\endlist
\keyword qml-documentation
\section2 Documenting QML Types

187
src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc Normal file
View File

@ -0,0 +1,187 @@
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** 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$
**
****************************************************************************/
/*!
\page qtwritingstyle-cpp.html
\title C++ Documentation Style
\brief Style guidelines for C++ documentation
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.
Note that the documentation must be in the implementation files such as \c .cpp.
\section1 Class Documentation
Class documentation is generated using the \l{class-command}{\\class} command and
the name of the class as the first argument.
\snippet examples/cpp.qdoc class
\l{Context commands} add information about the class, such as its module or
which version the class was added.
Some common context commands are:
\list
\li \l{brief-command}{\\brief} - the class' brief description \b (mandatory)
\li \l{since-command}{\\since} - the version to which the class was added \b (mandatory)
\li \l{internal-command}{\\internal} - marks the class as internal. Internal
classes do not appear in the public API documentation.
\endlist
\section2 The Brief and Detailed Description
The \e{brief description} is marked with the \l{brief-command}{\\brief} 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.
The C++ brief should start with:
\code
"The <C++ class name> class"
\endcode
The \e{detailed description} 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.
\section1 Member Functions
Typically, function documentation immediately precedes the implementation of the
function in the \c .cpp file. For function documentation that is not immediately
above the implementation, the \l{fn-command}{\\fn} is needed.
\snippet examples/cpp.qdoc function
The function documentation starts with a verb, indicating the operation the
function performs. This also applies to constructors and destructors.
Some common verbs for function documentation:
\list
\li "Constructs..." - for constructors
\li "Destroys..." - for destructors
\li "Returns..." - for accessor functions
\endlist
The function documentation must document:
\list
\li the return type
\li the parameters
\li the actions of the functions
\endlist
The \l{a-command}{\\a} command marks the parameter in the documentation.
The return type documentation should link to the type documentation or be
marked with the \l{c-command}{\\c} command in the case of boolean values.
\snippet examples/cpp.qdoc return
\section1 Properties
The property documentation resides immediately above the read function's
implementation. The \l{topic-commands}{topic command} for properties is
\l{property-command}{\\property}.
\snippet examples/cpp.qdoc property
Property documentation usually starts with "This property...", but these are
alternate expressions:
\list
\li "This property holds..."
\li "This property describes..."
\li "This property represents..."
\li "Returns \c true when... and \c false when..." - for properties that
are read.
\li "Sets the..." - for properties that configure a type.
\endlist
Property documentation must include:
\list
\li description and behavior of the property
\li accepted values for the property
\li the default value of the property
\endlist
Similar to \l{Member Functions}{functions}, the default type may be linked
or marked with the \c{\c} command.
An example of a value range style is:
\quotation
The values range from 0.0 (no blur) to maximumRadius (maximum blur). By default, the property is set to 0.0 (no blur).
\endquotation
\section1 Signals, Notifiers, and Slots
The \l{topic-commands}{topic command} for signals, notifiers, and slots
is \l{fn-command}{\\fn}. Signal documentation state when they are triggered
or emitted.
\snippet examples/cpp.qdoc signals
Signal documentation typically begin with "This signal is triggered when...".
Here are alternate styles:
\list
\li "This signal is triggered when..."
\li "Triggered when..."
\li "Emitted when..."
\endlist
For slots or notifiers, the condition when they are executed or triggered by
a signal should be documented.
\list
\li "Executed when..."
\li "This slot is executed when..."
\endlist
For properties that have overloaded signals, QDoc groups the overloaded
notifiers together. To refer to a specifc version of a notifier or signal,
simply refer to the property and mention that there are different versions of
the notifier.
\snippet examples/cpp.qdoc overloaded notifier
\section1 Enums, Namespaces, and other Types
Enums, namespaces, and macros have a \l{topic-command} for their documentation:
\list
\li \l{enum-command}{\\enum}
\li \l{typedef-command}{\\typedef}
\li \l{macro-command}{\\macro}
\endlist
The language style for these types mention that they are an enum or a macro and
continues with the type description.
For enumerations, the \l{value-command}{\\value} command is for listing the
values. QDoc creates a table of values for the enum.
\snippet examples/cpp.qdoc enums
*/

164
src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc Normal file
View File

@ -0,0 +1,164 @@
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** 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$
**
****************************************************************************/
/*!
\page qtwritingstyle-qml.html
\title QML Documentation Style
\brief Style guidelines for QML documentation
QDoc can process QML types defined as C++ classes and QML types defined in
\c .qml files. For C++ classes documented as QML types, the QDoc comments are
in the \c .cpp file while QML types defined in QML are in the \c .qml
file. The C++ classes must also be documented
documented with the QML \l{topic-commands}{topic commands}:
\list
\li \l{qmlattachedproperty-command}{\\qmlattachedproperty}
\li \l{qmlattachedsignal-command}{\\qmlattachedsignal}
\li \l{qmlbasictype-command}{\\qmlbasictype}
\li \l{qmltype-command}{\\qmltype}
\li \l{qmlmethod-command}{\\qmlmethod}
\li \l{qmlproperty-command}{\\qmlproperty}
\li \l{qmlsignal-command}{\\qmlsignal}
\li \l{qmlmodule-command}{\\qmlmodule}
\li \l{inqmlmodule-command}{\\inqmlmodule}
\li \l{instantiates-command}{\\instantiates}
\endlist
For QML types defined in \c .qml files, QDoc will parse the QML and determine
the properties, signals, and the type within the QML definition. The QDoc
block then needs to be immediately above the declaration. For QML types
implemented in C++, QDoc will output warnings if the C++ class documentation
does not exist. The class documentation may be marked as
\l{internal-command}{internal} if it is not a public API.
\section1 QML Types
The \l{qmltype-command}{\\qmltype} command is for QML type documentation.
\snippet examples/qml.qdoc qmltype
The \l{instantiates-command}{\\instantiates} accepts the C++ class which
implements the QML type as the argument. For types implemented in QML, this
is not needed.
The \e{brief description} provides a summary for the QML type. The brief does
not need to be a complete sentence and may start with a verb. QDoc will append
the brief description onto the QML type in tables and generated lists.
\code
\qmltype ColorAnimation
\brief Animates changes in color values
\endcode
Here are some alternate verbs for the brief statement:
\list
\li "Provides..."
\li "Specifies..."
\li "Describes..."
\endlist
The \e{detailed description} follows the brief and may contain images, snippet,
and link to other documentation.
\section1 Properties
The property description focuses on what the property \e does and may use the
following style:
Property documentation usually starts with "This property..." but for certain
properties, these are the common expressions:
\list
\li "This property holds..."
\li "This property describes..."
\li "This property represents..."
\li "Returns \c true when... and \c false when..." - for properties that
are marked \c{read-only}.
\li "Sets the..." - for properties that configure a type.
\endlist
\section1 Signals and Handlers Documentation
QML signals are documented either in the QML file or in the C++ implementation
with the \l{qmlsignal-command}{\\qmlsignal} command. Signal documentation
must include the condition for emitting the signal, mention the corresponding
signal handler, and document whether the signal accepts a parameter.
\snippet examples/qml.qdoc signals
These are the possible documentation styles for signals:
\list
\li "This signal is triggered when..."
\li "Triggered when..."
\li "Emitted when..."
\endlist
\section1 Methods and JavaScript Functions
Typically, function documentation immediately precedes the implementation of the
function in the \c .cpp file. The \l{topic-commands}{topic command} for
functions is \l{fn-command}{\\fn}. For functions in QML or JavaScript, the
documentation must reside immediately above the function declaration.
The function documentation starts with a verb, indicating the operation the
function performs.
\snippet examples/qml.qdoc function
Some common verbs for function documentation:
\list
\li "Copies..." - for constructors
\li "Destroys..." - for destructors
\li "Returns..." - for accessor functions
\endlist
The function documentation must document:
\list
\li the return type
\li the parameters
\li the actions of the functions
\endlist
The \l{a-command}{\\a} command marks the parameter in the documentation.
The return type documentation should link to the type documentation or be
marked with the \l{c-command}{\\c} command in the case of boolean values.
\section1 Enumerations
QML enumerations are documented as QML properties with the
\l{qmlproperty-command}{\\qmlproperty} command. The type of the property
is \c enumeration.
\snippet examples/qml.qdoc enums
The QDoc comment lists the values of the enumeration. If the enumeration is
implemented in C++, the documentation may link to the corresponding C++
enumeration. However, the QDoc comment should advise that the enumeration
is a C++ enumeration.
*/