Document Q_REVISION macro better

Previously it was only mentioned in properties.qdoc

Task-number: QTBUG-18802
Change-Id: Iab23128c1567974154cdcce7412b2e1468bb846a
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

8 files changed, 244 insertions, 5 deletions

diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp
index bafd3f8eb8..68df53e0da 100644
--- a/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp
+++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp
@@ -374,6 +374,7 @@ Q_PROPERTY(type name
            [WRITE setFunction]
            [RESET resetFunction]
            [NOTIFY notifySignal]
+           [REVISION int]
            [DESIGNABLE bool]
            [SCRIPTABLE bool]
            [STORED bool]
diff --git a/src/corelib/doc/snippets/qmetaobject-revision/main.cpp b/src/corelib/doc/snippets/qmetaobject-revision/main.cpp
new file mode 100644
index 0000000000..99a860b778
--- /dev/null
+++ b/src/corelib/doc/snippets/qmetaobject-revision/main.cpp
@@ -0,0 +1,72 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Research In Motion.
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QApplication>
+#include <QMetaObject>
+#include <QMetaMethod>
+#include <QMetaProperty>
+#include <QDebug>
+#include "window.h"
+
+void exposeMethod(const QMetaMethod &)
+{
+}
+
+void exposeProperty(const QMetaProperty &)
+{
+}
+
+int main(int argc, char *argv[])
+{
+    QApplication app(argc, argv);
+//! [Window class using revision]
+    Window window;
+    int expectedRevision = 0;
+    const QMetaObject *windowMetaObject = window.metaObject();
+    for (int i=0; i < windowMetaObject->methodCount(); i++)
+        if (windowMetaObject->method(i).revision() <= expectedRevision)
+            exposeMethod(windowMetaObject->method(i));
+    for (int i=0; i < windowMetaObject->propertyCount(); i++)
+        if (windowMetaObject->property(i).revision() <= expectedRevision)
+            exposeProperty(windowMetaObject->property(i));
+//! [Window class using revision]
+    window.show();
+    return app.exec();
+}
diff --git a/src/corelib/doc/snippets/qmetaobject-revision/qmetaobject-revision.pro b/src/corelib/doc/snippets/qmetaobject-revision/qmetaobject-revision.pro
new file mode 100644
index 0000000000..ec9d7db658
--- /dev/null
+++ b/src/corelib/doc/snippets/qmetaobject-revision/qmetaobject-revision.pro
@@ -0,0 +1,4 @@
+QT += widgets
+HEADERS   = window.h
+SOURCES   = main.cpp \
+            window.cpp
diff --git a/src/corelib/doc/snippets/qmetaobject-revision/window.cpp b/src/corelib/doc/snippets/qmetaobject-revision/window.cpp
new file mode 100644
index 0000000000..0315f831be
--- /dev/null
+++ b/src/corelib/doc/snippets/qmetaobject-revision/window.cpp
@@ -0,0 +1,66 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Research In Motion.
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "window.h"
+
+Window::Window()
+{
+}
+
+int Window::normalProperty()
+{
+    return 0;
+}
+
+int Window::newProperty()
+{
+    return 1;
+}
+
+void Window::normalMethod()
+{
+    show();
+}
+
+void Window::newMethod()
+{
+    // Can be hidden from users expecting the initial API
+    show();
+}
diff --git a/src/corelib/doc/snippets/qmetaobject-revision/window.h b/src/corelib/doc/snippets/qmetaobject-revision/window.h
new file mode 100644
index 0000000000..6e56f3dfef
--- /dev/null
+++ b/src/corelib/doc/snippets/qmetaobject-revision/window.h
@@ -0,0 +1,63 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Research In Motion.
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef WINDOW_H
+#define WINDOW_H
+
+#include <QWidget>
+
+//! [Window class with revision]
+class Window : public QWidget
+{
+    Q_OBJECT
+    Q_PROPERTY(int normalProperty READ normalProperty)
+    Q_PROPERTY(int newProperty READ newProperty REVISION 1)
+
+public:
+    Window();
+    int normalProperty();
+    int newProperty();
+public slots:
+    void normalMethod();
+    Q_REVISION(1) void newMethod();
+};
+//! [Window class with revision]
+
+#endif
diff --git a/src/corelib/doc/src/objectmodel/properties.qdoc b/src/corelib/doc/src/objectmodel/properties.qdoc
index 721b98c0f7..65e23d9dc7 100644
--- a/src/corelib/doc/src/objectmodel/properties.qdoc
+++ b/src/corelib/doc/src/objectmodel/properties.qdoc
@@ -101,7 +101,8 @@
 
     \li A \c REVISION number is optional. If included, it defines
     the property and its notifier signal to be used in a particular
-    revision of the API that is exposed to QML.
+    revision of the API (usually for exposure to QML). If not included, it
+    defaults to 0.
 
     \li The \c DESIGNABLE attribute indicates whether the property
     should be visible in the property editor of GUI design tool (e.g.,
diff --git a/src/corelib/kernel/qmetaobject.cpp b/src/corelib/kernel/qmetaobject.cpp
index 4399349352..b581be821b 100644
--- a/src/corelib/kernel/qmetaobject.cpp
+++ b/src/corelib/kernel/qmetaobject.cpp
@@ -1904,9 +1904,9 @@ int QMetaMethod::methodIndex() const
     return QMetaMethodPrivate::get(this)->ownMethodIndex() + mobj->methodOffset();
 }
 
+// This method has been around for a while, but the documentation was marked \internal until 5.1
 /*!
-    \internal
-
+    \since 5.1
     Returns the method revision if one was
     specified by Q_REVISION, otherwise returns 0.
  */
@@ -2550,7 +2550,7 @@ static QByteArray qualifiedName(const QMetaEnum &e)
 
     A property has a name() and a type(), as well as various
     attributes that specify its behavior: isReadable(), isWritable(),
-    isDesignable(), isScriptable(), and isStored().
+    isDesignable(), isScriptable(), revision(), and isStored().
 
     If the property is an enumeration, isEnumType() returns true; if the
     property is an enumeration that is also a flag (i.e. its values
@@ -2994,8 +2994,9 @@ int QMetaProperty::notifySignalIndex() const
     }
 }
 
+// This method has been around for a while, but the documentation was marked \internal until 5.1
 /*!
-    \internal
+    \since 5.1
 
     Returns the property revision if one was
     specified by REVISION, otherwise returns 0.
diff --git a/src/corelib/kernel/qobject.cpp b/src/corelib/kernel/qobject.cpp
index 583e580762..527a842d17 100644
--- a/src/corelib/kernel/qobject.cpp
+++ b/src/corelib/kernel/qobject.cpp
@@ -4103,6 +4103,37 @@ QDebug operator<<(QDebug dbg, const QObject *o) {
 */
 
 /*!
+    \macro Q_REVISION
+    \relates QObject
+
+    Apply this macro to definitions of member functions to tag them with a
+    revision number in the meta-object system. The macro is written before
+    the return type, as shown in the following example:
+
+    \snippet qmetaobject-revision/window.h Window class with revision
+
+    This is useful when using the meta-object system to dynamically expose
+    objects to another API, as you can match the version expected by multiple
+    versions of the other API. Consider the following simplified example:
+
+    \snippet qmetaobject-revision/main.cpp Window class using revision
+
+    Using the same Window class as the previous example, the newProperty and
+    newMethod would only be exposed in this code when the expected version is
+    1 or greater.
+
+    Since all methods are considered to be in revision 0 if untagged, a tag
+    of Q_REVISION(0) is invalid and ignored.
+
+    This tag is not used by the meta-object system itself. Currently this is only
+    used by the QtQml module.
+
+    For a more generic string tag, see \l QMetaMethod::tag()
+
+    \sa QMetaMethod::revision()
+*/
+
+/*!
     \macro Q_SET_OBJECT_NAME(Object)
     \relates QObject
     \since 5.0