Added API Reference Style Guidelines

-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>

7 files changed, 617 insertions, 8 deletions

diff --git a/src/tools/qdoc/doc/config/qt-html-templates-online.qdocconf b/src/tools/qdoc/doc/config/qt-html-templates-online.qdocconf
index f799fb3549..d5e4908a70 100644
--- a/src/tools/qdoc/doc/config/qt-html-templates-online.qdocconf
+++ b/src/tools/qdoc/doc/config/qt-html-templates-online.qdocconf
@@ -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 \
diff --git a/src/tools/qdoc/doc/config/qt-html-templates.qdocconf b/src/tools/qdoc/doc/config/qt-html-templates.qdocconf
index 5172c2fd51..b199d6839d 100644
--- a/src/tools/qdoc/doc/config/qt-html-templates.qdocconf
+++ b/src/tools/qdoc/doc/config/qt-html-templates.qdocconf
@@ -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 \
diff --git a/src/tools/qdoc/doc/examples/cpp.qdoc b/src/tools/qdoc/doc/examples/cpp.qdoc
new file mode 100644
index 0000000000..c7d80e1381
--- /dev/null
+++ b/src/tools/qdoc/doc/examples/cpp.qdoc
@@ -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]
diff --git a/src/tools/qdoc/doc/examples/qml.qdoc b/src/tools/qdoc/doc/examples/qml.qdoc
new file mode 100644
index 0000000000..259136542b
--- /dev/null
+++ b/src/tools/qdoc/doc/examples/qml.qdoc
@@ -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]
diff --git a/src/tools/qdoc/doc/qdoc-guide.qdoc b/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc
index 64dc78cd2d..f0830c0ccf 100644
--- a/src/tools/qdoc/doc/qdoc-guide.qdoc
+++ b/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc
@@ -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
 
diff --git a/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc b/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc
new file mode 100644
index 0000000000..e893d351cc
--- /dev/null
+++ b/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc
@@ -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
+
+*/
+
diff --git a/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc b/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc
new file mode 100644
index 0000000000..4b73807f2b
--- /dev/null
+++ b/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc
@@ -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.
+
+*/
+