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>

1 files changed, 187 insertions, 0 deletions

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
+
+*/
+