Docs: Update the obsolete requirements for Q_OBJECT and Q_GADGET

Since 6.5, you can declare the Q_OBJECT macro in any class section, not
only in private. The docs are updated accordingly. The Q_OBJECT macro
specifies a private section on its own, thus making private all the
members declared after the macro. This is an important behavior change,
so the note about it was rewritten for clarity & moved a little bit up.

Fixes: QTBUG-125776
Pick-to: 6.5 6.6 6.7
Change-Id: Ifba063af7cf7fe7258b6183da5a4599784171052
Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>

src/corelib/doc/snippets/signalsandslots/signalsandslots.h

@@ -33,6 +33,8 @@ class Counter : public QObject
 {
     Q_OBJECT
 
+// Note. The Q_OBJECT macro starts a private section.
+// To declare public members, use the 'public:' access modifier.
 public:
     Counter() { m_value = 0; }
 

src/corelib/doc/src/objectmodel/metaobjects.qdoc

@@ -19,8 +19,7 @@
     \list 1
     \li The \l QObject class provides a base class for objects that can
        take advantage of the meta-object system.
-    \li The Q_OBJECT macro inside the private section of the class
+    \li The Q_OBJECT macro is used to enable meta-object features, such as
-       declaration is used to enable meta-object features, such as
        dynamic properties, signals, and slots.
     \li The \l{moc}{Meta-Object Compiler} (\c moc) supplies each
        QObject subclass with the necessary code to implement

src/corelib/doc/src/objectmodel/properties.qdoc

@@ -186,12 +186,11 @@
 
     \section1 A Simple Example
 
-    Suppose we have a class MyClass, which is derived from QObject and
+    Suppose we have a class \c MyClass, which is derived from QObject and which
-    which uses the Q_OBJECT macro in its private section. We want to
+    uses the Q_OBJECT macro. We want to declare a property in \c MyClass to keep
-    declare a property in MyClass to keep track of a priority
+    track of a priority value. The name of the property will be \c priority, and
-    value. The name of the property will be \e priority, and its type
+    its type will be an enumeration type named \c Priority, which is defined in
-    will be an enumeration type named \e Priority, which is defined in
+    \c MyClass.
-    MyClass.
 
     We declare the property with the Q_PROPERTY() macro in the private
     section of the class. The required \c READ function is named \c
@@ -200,7 +199,7 @@
     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
+    for the \c READ and \c WRITE functions. The declaration of \c MyClass
     then might look like this:
 
     \snippet code/doc_src_properties.cpp 5
@@ -213,24 +212,24 @@
     potentially forcing re-evaluation in other places if nothing has
     changed.
 
-    Given a pointer to an instance of MyClass or a pointer to a
+    Given a pointer to an instance of \c MyClass or a pointer to a
-    QObject that is an instance of MyClass, we have two ways to set
+    QObject that is an instance of \c MyClass, we have two ways to set
     its priority property:
 
     \snippet code/doc_src_properties.cpp 6
 
     In the example, the enumeration type that is the property type is
-    declared in MyClass and registered with the \l{Meta-Object System}
+    declared in \c MyClass and registered with the \l{Meta-Object System}
     using the Q_ENUM() macro. This makes the enumeration values
-    available as strings for use as in the call to \l{QObject::}{setProperty()}. Had
+    available as strings for use as in the call to \l{QObject::}{setProperty()}.
-    the enumeration type been declared in another class, its fully
+    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_ENUM() macro.
 
     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
+    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_FLAG()
     should be used to register this enumeration type.

src/corelib/kernel/qobject.cpp

@@ -4698,16 +4698,25 @@ QDebug operator<<(QDebug dbg, const QObject *o)
     \sa {Qt's Property System}
 */
 
-
 /*!
     \macro Q_OBJECT
     \relates QObject
 
-    The Q_OBJECT macro must appear in the private section of a class
+    The Q_OBJECT macro is used to enable meta-object features, such as dynamic
-    definition that declares its own signals and slots or that uses
+    properties, signals, and slots.
-    other services provided by Qt's meta-object system.
 
-    For example:
+    You can add the Q_OBJECT macro to any section of a class definition that
+    declares its own signals and slots or that uses other services provided by
+    Qt's meta-object system.
+
+//! [qobject-macros-private-access-specifier]
+    \note This macro expansion ends with a \c private: access specifier. If you
+    declare members immediately after this macro, those members will also be
+    private. To add public (or protected) members right after the macro, use a
+    \c {public:} (or \c {protected:}) access specifier.
+//! [qobject-macros-private-access-specifier]
+
+    Example:
 
     \snippet signalsandslots/signalsandslots.h 1
     \codeline
@@ -4715,15 +4724,8 @@ QDebug operator<<(QDebug dbg, const QObject *o)
     \snippet signalsandslots/signalsandslots.h 3
 
     \note This macro requires the class to be a subclass of QObject. Use
-    Q_GADGET or Q_GADGET_EXPORT instead of Q_OBJECT to enable the meta object system's support
+    Q_GADGET or Q_GADGET_EXPORT instead of Q_OBJECT to enable the meta object
-    for enums in a class that is not a QObject subclass.
+    system's support for enums in a class that is not a QObject subclass.
-
-//! [qobject-macros-private-access-specifier]
-    \note This macro expansion ends with a \c private: access specifier, which makes member
-    declarations immediately after the macro private, too. If you want add public (or protected)
-    members immediately after the macro, you need to use a \c public: (or \c protected:)
-    access specifier.
-//! [qobject-macros-private-access-specifier]
 
     \sa {Meta-Object System}, {Signals and Slots}, {Qt's Property System}
 */
@@ -4734,8 +4736,9 @@ QDebug operator<<(QDebug dbg, const QObject *o)
 
     The Q_GADGET macro is a lighter version of the Q_OBJECT macro for classes
     that do not inherit from QObject but still want to use some of the
-    reflection capabilities offered by QMetaObject. Just like the Q_OBJECT
+    reflection capabilities offered by QMetaObject.
-    macro, it must appear in the private section of a class definition.
+
+    \include qobject.cpp qobject-macros-private-access-specifier
 
     Q_GADGETs can have Q_ENUM, Q_PROPERTY and Q_INVOKABLE, but they cannot have
     signals or slots.
@@ -4744,8 +4747,6 @@ QDebug operator<<(QDebug dbg, const QObject *o)
     \c{staticMetaObject} is of type QMetaObject and provides access to the
     enums declared with Q_ENUM.
 
-    \include qobject.cpp qobject-macros-private-access-specifier
-
     \sa Q_GADGET_EXPORT
 */
 
@@ -4761,6 +4762,8 @@ QDebug operator<<(QDebug dbg, const QObject *o)
     enclosing class as a whole should not be (e.g. because it consists of mostly
     inline functions).
 
+    \include qobject.cpp qobject-macros-private-access-specifier
+
     For example:
 
     \code
@@ -4771,8 +4774,6 @@ QDebug operator<<(QDebug dbg, const QObject *o)
         ~~~
     \endcode
 
-    \include qobject.cpp qobject-macros-private-access-specifier
-
     \sa Q_GADGET, {Creating Shared Libraries}
 */