From 8c4ac07258c7d6f89617858ba86dedd1078d6abe Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Mon, 13 Aug 2012 12:01:05 +0200 Subject: [PATCH] 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 Reviewed-by: Qt Doc Bot Reviewed-by: Martin Smith --- .../config/qt-html-templates-online.qdocconf | 10 +- .../doc/config/qt-html-templates.qdocconf | 6 +- src/tools/qdoc/doc/examples/cpp.qdoc | 126 ++++++++++++ src/tools/qdoc/doc/examples/qml.qdoc | 116 +++++++++++ .../qdoc/doc/{ => qdoc-guide}/qdoc-guide.qdoc | 16 ++ .../doc/qdoc-guide/qtwritingstyle-cpp.qdoc | 187 ++++++++++++++++++ .../doc/qdoc-guide/qtwritingstyle-qml.qdoc | 164 +++++++++++++++ 7 files changed, 617 insertions(+), 8 deletions(-) create mode 100644 src/tools/qdoc/doc/examples/cpp.qdoc create mode 100644 src/tools/qdoc/doc/examples/qml.qdoc rename src/tools/qdoc/doc/{ => qdoc-guide}/qdoc-guide.qdoc (98%) create mode 100644 src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc create mode 100644 src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc 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 = \ "
\n" \ "
\n" \ "
\n" \ - " Home
\n" \ - " QDoc Reference Documentation\n" \ + " Home
\n" \ + " QDoc Reference Documentation\n" \ "
\n" \ "
\n" \ "
    \n" \ @@ -19,7 +19,7 @@ HTML.postheader = \ "
\n" \ "
\n" \ " \n" \ @@ -35,7 +35,7 @@ HTML.postheader = \ "
\n" \ "
\n" \ "
    \n" \ - "
  • Home
    • \n" \ + "
  • Home
    • \n" \ " \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 = \ "
    \n" \ "
    \n" \ - " QDoc Reference Documentation\n" \ + " QDoc Reference Documentation\n" \ "
    \n" \ "
    \n" \ "
      \n" \ - "
    • Home
      • \n" \ + "
    • Home
      • \n" \ " \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\ 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: "Hello World!" + 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 similarity index 98% rename from src/tools/qdoc/doc/qdoc-guide.qdoc rename to 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 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. + +*/ +