From ef7260c41b3ffac6459af04c144c521b110527a0 Mon Sep 17 00:00:00 2001
From: Harald Fernengel <harald@trolltech.com>
Date: Tue, 16 Jun 2009 11:42:05 +0200
Subject: doc: document QScopedPointer with forward declared classes

Also some small doc cleanups
---
 .../code/src_corelib_tools_qscopedpointer.cpp        | 20 +++++++++++++++++++-
 src/corelib/tools/qscopedpointer.cpp                 | 17 ++++++++++++++++-
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp b/doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp
index 05377dd..7de42b7 100644
--- a/doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp
+++ b/doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp
@@ -3,7 +3,6 @@ void myFunction(bool useSubClass)
 {
     MyClass *p = useSubClass ? new MyClass() : new MySubClass;
     QIODevice *device = handsOverOwnership();
-    QIODevi
 
     if (m_value > 3) {
         delete p;
@@ -62,3 +61,22 @@ if (scopedPointer) {
     ...
 }
 //! [3]
+
+//! [4]
+class MyPrivateClass; // forward declare MyPrivateClass
+
+class MyClass
+{
+private:
+    QScopedPointer<MyPrivateClass> privatePtr; // QScopedPointer to forward declared class
+
+public:
+    MyClass(); // OK
+    inline ~MyClass() {} // VIOLATION - Destructor must not be inline
+
+private:
+    Q_DISABLE_COPY(MyClass) // OK - copy constructor and assignment operators
+                             // are now disabled, so the compiler won't implicitely
+                             // generate them.
+};
+//! [4]
diff --git a/src/corelib/tools/qscopedpointer.cpp b/src/corelib/tools/qscopedpointer.cpp
index 6a1ffb6..912edb6 100644
--- a/src/corelib/tools/qscopedpointer.cpp
+++ b/src/corelib/tools/qscopedpointer.cpp
@@ -80,6 +80,21 @@
 
     \note QScopedPointer does not work with arrays.
 
+    \section1 Forward Declared Pointers
+
+    Classes that are forward declared can be used within QScopedPointer, as
+    long as the destructor of the forward declared class is available whenever
+    a QScopedPointer needs to clean up.
+
+    Concretely, this means that all classes containing a QScopedPointer that
+    points to a forward declared class must have non-inline constructors,
+    destructors and assignment operators:
+
+    \snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 4
+
+    Otherwise, the compiler output a warning about not being able to destruct
+    \c MyPrivateClass.
+
     \sa QSharedPointer
 */
 
@@ -142,7 +157,7 @@
 
 
 /*!
-    \fn bool QScopedPointer::operator!=(const QScopedPointer<T> *other) const
+    \fn bool QScopedPointer::operator!=(const QScopedPointer<T> &other) const
 
     Inequality operator. Returns true if the scoped pointer \a other
     is not pointing to the same object as this pointer, otherwise returns false.
-- 
cgit v0.12