Document Q_ENUM and Q_FLAG

[ChangeLog][QtCore] Q_ENUMS and Q_FLAGS have been deprecated, and replaced
by Q_ENUM and Q_FLAG macros. These two new macros automatically register the
enum with the Qt metatype system, allowing automatic conversion to or from
string in QVariant, or to show the strings by QDebug operators. They also
enable the new QMetaEnum::fromType function.

Change-Id: I80cccd7ad3fc46b11aee2fe50681a8126debf972
Reviewed-by: Marc Mutz <marc.mutz@kdab.com>
Reviewed-by: Shawn Rutledge <shawn.rutledge@digia.com>

4 files changed, 74 insertions, 22 deletions

diff --git a/src/corelib/doc/snippets/code/doc_src_properties.cpp b/src/corelib/doc/snippets/code/doc_src_properties.cpp
index d07c7cb947..8978d1a067 100644
--- a/src/corelib/doc/snippets/code/doc_src_properties.cpp
+++ b/src/corelib/doc/snippets/code/doc_src_properties.cpp
@@ -93,13 +93,13 @@ class MyClass : public QObject
 {
     Q_OBJECT
     Q_PROPERTY(Priority priority READ priority WRITE setPriority NOTIFY priorityChanged)
-    Q_ENUMS(Priority)
 
 public:
     MyClass(QObject *parent = 0);
     ~MyClass();
 
     enum Priority { High, Low, VeryHigh, VeryLow };
+    Q_ENUM(Priority)
 
     void setPriority(Priority priority)
     {
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 0bf67fce31..b0048014a4 100644
--- a/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp
+++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp
@@ -376,38 +376,37 @@ Q_PROPERTY(QString title READ title WRITE setTitle USER true)
 class MyClass : public QObject
 {
     Q_OBJECT
-    Q_ENUMS(Priority)
 
 public:
     MyClass(QObject *parent = 0);
     ~MyClass();
 
     enum Priority { High, Low, VeryHigh, VeryLow };
+    Q_ENUM(Priority)
     void setPriority(Priority priority);
     Priority priority() const;
 };
 //! [38]
 
 
-//! [39a]
+//! [39]
 class QLibrary : public QObject
 {
-    ...
-    Q_FLAGS(LoadHint LoadHints)
-    ...
-//! [39a]
+    Q_OBJECT
 
-//! [39b]
-    ...
 public:
+    ...
+
     enum LoadHint {
         ResolveAllSymbolsHint = 0x01,
         ExportExternalSymbolsHint = 0x02,
         LoadArchiveMemberHint = 0x04
     };
     Q_DECLARE_FLAGS(LoadHints, LoadHint)
+    Q_FLAG(LoadHints)
     ...
-//! [39b]
+}
+//! [39]
 
 
 //! [40]
diff --git a/src/corelib/doc/src/objectmodel/properties.qdoc b/src/corelib/doc/src/objectmodel/properties.qdoc
index 5db1410e6f..abb0720fe9 100644
--- a/src/corelib/doc/src/objectmodel/properties.qdoc
+++ b/src/corelib/doc/src/objectmodel/properties.qdoc
@@ -207,7 +207,7 @@
     section of the class. The required \c READ function is named \c
     priority, and we include a \c WRITE function named \c setPriority.
     The enumeration type must be registered with the \l {Meta-Object
-    System} using the Q_ENUMS() macro. Registering an enumeration type
+    System} using the Q_ENUM() macro. Registering an enumeration type
     makes the enumerator names available for use in calls to
     QObject::setProperty(). We must also provide our own declarations
     for the \c READ and \c WRITE functions. The declaration of MyClass
@@ -228,18 +228,18 @@
 
     In the example, the enumeration type that is the property type is
     declared in MyClass and registered with the \l{Meta-Object System}
-    using the Q_ENUMS() macro. This makes the enumeration values
+    using the Q_ENUM() macro. This makes the enumeration values
     available as strings for use as in the call to \l{QObject::}{setProperty()}. Had
     the enumeration type been declared in another class, its fully
     qualified name (i.e., OtherClass::Priority) would be required, and
     that other class would also have to inherit QObject and register
-    the enumeration type there using the Q_ENUMS() macro.
+    the enumeration type there using the Q_ENUM() macro.
 
-    A similar macro, Q_FLAGS(), is also available. Like Q_ENUMS(), it
+    A similar macro, Q_FLAG(), is also available. Like Q_ENUM(), it
     registers an enumeration type, but it marks the type as being a
     set of \e flags, i.e. values that can be OR'd together. An I/O
     class might have enumeration values \c Read and \c Write and then
-    QObject::setProperty() could accept \c{Read | Write}. Q_FLAGS()
+    QObject::setProperty() could accept \c{Read | Write}. Q_FLAG()
     should be used to register this enumeration type.
 
     \section1 Dynamic Properties
diff --git a/src/corelib/kernel/qobject.cpp b/src/corelib/kernel/qobject.cpp
index 265cc68db5..40279cf2b3 100644
--- a/src/corelib/kernel/qobject.cpp
+++ b/src/corelib/kernel/qobject.cpp
@@ -4178,6 +4178,7 @@ QDebug operator<<(QDebug dbg, const QObject *o)
 /*!
     \macro Q_ENUMS(...)
     \relates QObject
+    \obsolete
 
     This macro registers one or several enum types to the meta-object
     system.
@@ -4191,35 +4192,87 @@ QDebug operator<<(QDebug dbg, const QObject *o)
     defining it. In addition, the class \e defining the enum has to
     inherit QObject as well as declare the enum using Q_ENUMS().
 
+    In new code, you should prefer the use of the Q_ENUM() macro, which makes the
+    type available also to the meta type system.
+    For instance, QMetaEnum::fromType() will not work with types declared with Q_ENUMS().
+
     \sa {Qt's Property System}
 */
 
 /*!
     \macro Q_FLAGS(...)
     \relates QObject
+    \obsolete
 
-    This macro registers one or several \l{QFlags}{flags types} to the
+    This macro registers one or several \l{QFlags}{flags types} with the
     meta-object system. It is typically used in a class definition to declare
     that values of a given enum can be used as flags and combined using the
     bitwise OR operator.
 
+    \note This macro takes care of registering individual flag values
+    with the meta-object system, so it is unnecessary to use Q_ENUMS()
+    in addition to this macro.
+
+    In new code, you should prefer the use of the Q_FLAG() macro, which makes the
+    type available also to the meta type system.
+
+    \sa {Qt's Property System}
+*/
+
+/*!
+    \macro Q_ENUM(...)
+    \relates QObject
+    \since 5.5
+
+    This macro registers an enum type with the meta-object system.
+    It must be placed after the enum declaration in a class that has the Q_OBJECT or the
+    Q_GADGET macro.
+
+    For example:
+
+    \snippet code/src_corelib_kernel_qobject.cpp 38
+
+    Enumerations that are declared with Q_ENUM have their QMetaEnum registered in the
+    enclosing QMetaObject. You can also use QMetaEnum::fromType() to get the QMetaEnum.
+
+    Registered enumerations are automatically registered also to the Qt meta
+    type system, making them known to QMetaType without the need to use
+    Q_DECLARE_METATYPE(). This will enable useful features; for example, if used
+    in a QVariant, you can convert them to strings. Likewise, passing them to
+    QDebug will print out their names.
+
+    \sa {Qt's Property System}
+*/
+
+
+/*!
+    \macro Q_FLAG(...)
+    \relates QObject
+    \since 5.5
+
+    This macro registers a single \l{QFlags}{flags types} with the
+    meta-object system. It is typically used in a class definition to declare
+    that values of a given enum can be used as flags and combined using the
+    bitwise OR operator.
+
+    The macro must be placed after the enum declaration.
+
     For example, in QLibrary, the \l{QLibrary::LoadHints}{LoadHints} flag is
     declared in the following way:
 
-    \snippet code/src_corelib_kernel_qobject.cpp 39a
+    \snippet code/src_corelib_kernel_qobject.cpp 39
 
     The declaration of the flags themselves is performed in the public section
-    of the QLibrary class itself, using the \l Q_DECLARE_FLAGS() macro:
+    of the QLibrary class itself, using the \l Q_DECLARE_FLAGS() macro.
 
-    \snippet code/src_corelib_kernel_qobject.cpp 39b
-
-    \note This macro takes care of registering individual flag values
-    with the meta-object system, so it is unnecessary to use Q_ENUMS()
+    \note The Q_FLAG macro takes care of registering individual flag values
+    with the meta-object system, so it is unnecessary to use Q_ENUM()
     in addition to this macro.
 
     \sa {Qt's Property System}
 */
 
+
 /*!
     \macro Q_OBJECT
     \relates QObject