Tidy up and expand QSharedPointer documentation.

Also adds the 5.4.0 changes file.

Change-Id: I10967ca179b91229e7d1ee0fc666bbd8dbe54425
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

2 files changed, 50 insertions, 3 deletions

diff --git a/dist/changes-5.4.0 b/dist/changes-5.4.0
new file mode 100644
index 0000000000..c26e205bc0
--- /dev/null
+++ b/dist/changes-5.4.0
@@ -0,0 +1,26 @@
+Qt 5.4 introduces many new features and improvements as well as bugfixes
+over the 5.3.x series. For more details, refer to the online documentation
+included in this distribution. The documentation is also available online:
+
+  http://qt-project.org/doc/qt-5.4
+
+The Qt version 5.4 series is binary compatible with the 5.3.x series.
+Applications compiled for 5.3 will continue to run with 5.4.
+
+Some of the changes listed in this file include issue tracking numbers
+corresponding to tasks in the Qt Bug Tracker:
+
+  http://bugreports.qt-project.org/
+
+Each of these identifiers can be entered in the bug tracker to obtain more
+information about a particular change.
+
+****************************************************************************
+*                          Library                                         *
+****************************************************************************
+
+QtCore
+------
+
+ - Added QEnableSharedFromThis, a class that allows obtaining a
+   QSharedPointer for an object already managed by a shared pointer.
diff --git a/src/corelib/tools/qsharedpointer.cpp b/src/corelib/tools/qsharedpointer.cpp
index 180f45eb56..e0cd54022e 100644
--- a/src/corelib/tools/qsharedpointer.cpp
+++ b/src/corelib/tools/qsharedpointer.cpp
@@ -374,12 +374,12 @@
 /*!
     \class QEnableSharedFromThis
     \inmodule QtCore
-    \brief A base class that allows to obtain a QSharedPointer for an object already managed by a shared pointer
+    \brief A base class that allows obtaining a QSharedPointer for an object already managed by a shared pointer
     \since 5.4
 
     You can inherit this class when you need to create a QSharedPointer
-    from any instance of a class -- for instance, from within the
-    object itself. The key point is that the "obvious" technique of
+    from any instance of a class; for instance, from within the
+    object itself. The key point is that the technique of
     just returning QSharedPointer<T>(this) can not be used, because
     this winds up creating multiple distinct QSharedPointer objects
     with separate reference counts. For this reason you must never
@@ -406,6 +406,27 @@
         Q_ASSERT(p == y); // p and q must share ownership
     }
     \endcode
+
+    It is also possible to get a shared pointer from an object outside of
+    the class itself. This is especially useful in code that provides an
+    interface to scripts, where it is currently not possible to use shared
+    pointers. For example:
+
+    \code
+    class ScriptInterface : public QObject
+    {
+        Q_OBJECT
+
+        // ...
+
+    public slots:
+        void slotCalledByScript(Y *managedBySharedPointer)
+        {
+            QSharedPointer<Y> yPtr = managedBySharedPointer->sharedFromThis();
+            // Some other code unrelated to scripts that expects a QSharedPointer<Y> ...
+        }
+    };
+    \endcode
 */
 
 /*!