From fd529383c4491580db344fb3d8035bd0ad3cb5e0 Mon Sep 17 00:00:00 2001
From: David Boddie <dboddie@trolltech.com>
Date: Fri, 4 Sep 2009 20:46:10 +0200
Subject: Doc: Added info on Q_FLAGS() by providing an example with more
 context.

Reviewed-by: Trust Me
As-seen-on: qt-interest
---
 .../snippets/code/src_corelib_kernel_qobject.cpp   | 22 +++++++++++++++++++---
 src/corelib/kernel/qobject.cpp                     | 14 +++++++++++---
 2 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/doc/src/snippets/code/src_corelib_kernel_qobject.cpp b/doc/src/snippets/code/src_corelib_kernel_qobject.cpp
index 2c18036..c200c30 100644
--- a/doc/src/snippets/code/src_corelib_kernel_qobject.cpp
+++ b/doc/src/snippets/code/src_corelib_kernel_qobject.cpp
@@ -404,9 +404,25 @@ public:
 //! [38]
 
 
-//! [39]
-Q_FLAGS(Options Alignment)
-//! [39]
+//! [39a]
+class QLibrary : public QObject
+{
+    ...
+    Q_FLAGS(LoadHint LoadHints)
+    ...
+//! [39a]
+
+//! [39b]
+    ...
+public:
+    enum LoadHint {
+        ResolveAllSymbolsHint = 0x01,
+        ExportExternalSymbolsHint = 0x02,
+        LoadArchiveMemberHint = 0x04
+    };
+    Q_DECLARE_FLAGS(LoadHints, LoadHint)
+    ...
+//! [39b]
 
 
 //! [40]
diff --git a/src/corelib/kernel/qobject.cpp b/src/corelib/kernel/qobject.cpp
index c0c97b8..e93c6ee 100644
--- a/src/corelib/kernel/qobject.cpp
+++ b/src/corelib/kernel/qobject.cpp
@@ -3965,11 +3965,19 @@ QDebug operator<<(QDebug dbg, const QObject *o) {
     \relates QObject
 
     This macro registers one or several \l{QFlags}{flags types} to the
-    meta-object system.
+    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.
 
-    Example:
+    For example, in QLibrary, the \l{QLibrary::LoadHints}{LoadHints} flag is
+    declared in the following way:
+
+    \snippet doc/src/snippets/code/src_corelib_kernel_qobject.cpp 39a
+
+    The declaration of the flags themselves is performed in the public section
+    of the QLibrary class itself, using the \l Q_DECLARE_FLAGS() macro:
 
-    \snippet doc/src/snippets/code/src_corelib_kernel_qobject.cpp 39
+    \snippet doc/src/snippets/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()
-- 
cgit v0.12