Doc: there is no group of explicitly shared classes, only one class uses this.

Explain the implications in the QWebHistoryItem documentation, and get rid
of the "group".

4 files changed, 156 insertions, 116 deletions

diff --git a/doc/src/groups.qdoc b/doc/src/groups.qdoc
index 731ac58..f7296a3 100644
--- a/doc/src/groups.qdoc
+++ b/doc/src/groups.qdoc
@@ -202,20 +202,6 @@
 */
 
 /*!
-    \group explicitly-shared
-    \ingroup groups
-
-    \title Explicitly Shared Classes
-    \brief Classes that use explicit sharing to manage internal data.
-
-    \keyword explicit sharing
-    \keyword explicitly shared
-
-    Unlike many of Qt's data types, which use \l{implicit sharing}, these
-    classes use explicit sharing to manage internal data.
-*/
-
-/*!
     \group geomanagement
     \title Layout Classes
     \ingroup groups
@@ -377,103 +363,6 @@
 */
 
 /*!
-    \group shared
-    \title Implicitly Shared Classes
-    \ingroup architecture
-    \ingroup groups
-
-    \brief Classes that use reference counting for fast copying.
-
-    \keyword implicit data sharing
-    \keyword implicit sharing
-    \keyword implicitly shared
-    \keyword reference counting
-    \keyword shared implicitly
-    \keyword shared classes
-
-    Many C++ classes in Qt use implicit data sharing to maximize
-    resource usage and minimize copying. Implicitly shared classes are
-    both safe and efficient when passed as arguments, because only a
-    pointer to the data is passed around, and the data is copied only
-    if and when a function writes to it, i.e., \e {copy-on-write}.
-
-    \tableofcontents
-
-    \section1 Overview
-
-    A shared class consists of a pointer to a shared data block that
-    contains a reference count and the data.
-
-    When a shared object is created, it sets the reference count to 1. The
-    reference count is incremented whenever a new object references the
-    shared data, and decremented when the object dereferences the shared
-    data. The shared data is deleted when the reference count becomes
-    zero.
-
-    \keyword deep copy
-    \keyword shallow copy
-
-    When dealing with shared objects, there are two ways of copying an
-    object. We usually speak about \e deep and \e shallow copies. A deep
-    copy implies duplicating an object. A shallow copy is a reference
-    copy, i.e. just a pointer to a shared data block. Making a deep copy
-    can be expensive in terms of memory and CPU. Making a shallow copy is
-    very fast, because it only involves setting a pointer and incrementing
-    the reference count.
-
-    Object assignment (with operator=()) for implicitly shared objects is
-    implemented using shallow copies.
-
-    The benefit of sharing is that a program does not need to duplicate
-    data unnecessarily, which results in lower memory use and less copying
-    of data. Objects can easily be assigned, sent as function arguments,
-    and returned from functions.
-
-    Implicit sharing takes place behind the scenes; the programmer
-    does not need to worry about it. Even in multithreaded
-    applications, implicit sharing takes place, as explained in
-    \l{Threads and Implicit Sharing}.
-
-    \section1 Implicit Sharing in Detail
-
-    Implicit sharing automatically detaches the object from a shared
-    block if the object is about to change and the reference count is
-    greater than one. (This is often called \e {copy-on-write} or
-    \e {value semantics}.)
-
-    An implicitly shared class has total control of its internal data. In
-    any member functions that modify its data, it automatically detaches
-    before modifying the data.
-
-    The QPen class, which uses implicit sharing, detaches from the shared
-    data in all member functions that change the internal data.
-
-    Code fragment:
-    \snippet doc/src/snippets/code/doc_src_groups.qdoc 0
-
-    \section1 List of Classes
-
-    The classes listed below automatically detach from common data if
-    an object is about to be changed. The programmer will not even
-    notice that the objects are shared. Thus you should treat
-    separate instances of them as separate objects. They will always
-    behave as separate objects but with the added benefit of sharing
-    data whenever possible. For this reason, you can pass instances
-    of these classes as arguments to functions by value without
-    concern for the copying overhead.
-
-    Example:
-    \snippet doc/src/snippets/code/doc_src_groups.qdoc 1
-
-    In this example, \c p1 and \c p2 share data until QPainter::begin()
-    is called for \c p2, because painting a pixmap will modify it.
-
-    \warning Do not copy an implicitly shared container (QMap,
-    QVector, etc.) while you are iterating over it using an non-const
-    \l{STL-style iterator}.
-*/
-
-/*!
     \group ssl
     \title Secure Sockets Layer (SSL) Classes
     \ingroup groups
diff --git a/doc/src/implicit-sharing.qdoc b/doc/src/implicit-sharing.qdoc
new file mode 100644
index 0000000..85630dc
--- /dev/null
+++ b/doc/src/implicit-sharing.qdoc
@@ -0,0 +1,144 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://www.qtsoftware.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/* TODO: Move some of the documentation from QSharedDataPointer into this
+   document. */
+
+/*!
+    \group shared
+    \title Implicitly Shared Classes
+    \ingroup architecture
+    \ingroup groups
+
+    \brief Classes that use reference counting for fast copying.
+
+    \keyword implicit data sharing
+    \keyword implicit sharing
+    \keyword implicitly shared
+    \keyword reference counting
+    \keyword shared implicitly
+    \keyword shared classes
+
+    Many C++ classes in Qt use implicit data sharing to maximize
+    resource usage and minimize copying. Implicitly shared classes are
+    both safe and efficient when passed as arguments, because only a
+    pointer to the data is passed around, and the data is copied only
+    if and when a function writes to it, i.e., \e {copy-on-write}.
+
+    \tableofcontents
+
+    \section1 Overview
+
+    A shared class consists of a pointer to a shared data block that
+    contains a reference count and the data.
+
+    When a shared object is created, it sets the reference count to 1. The
+    reference count is incremented whenever a new object references the
+    shared data, and decremented when the object dereferences the shared
+    data. The shared data is deleted when the reference count becomes
+    zero.
+
+    \keyword deep copy
+    \keyword shallow copy
+
+    When dealing with shared objects, there are two ways of copying an
+    object. We usually speak about \e deep and \e shallow copies. A deep
+    copy implies duplicating an object. A shallow copy is a reference
+    copy, i.e. just a pointer to a shared data block. Making a deep copy
+    can be expensive in terms of memory and CPU. Making a shallow copy is
+    very fast, because it only involves setting a pointer and incrementing
+    the reference count.
+
+    Object assignment (with operator=()) for implicitly shared objects is
+    implemented using shallow copies.
+
+    The benefit of sharing is that a program does not need to duplicate
+    data unnecessarily, which results in lower memory use and less copying
+    of data. Objects can easily be assigned, sent as function arguments,
+    and returned from functions.
+
+    Implicit sharing takes place behind the scenes; the programmer
+    does not need to worry about it. Even in multithreaded
+    applications, implicit sharing takes place, as explained in
+    \l{Threads and Implicit Sharing}.
+
+    When implementing your own implicitly shared classes, use the
+    QSharedData and QSharedDataPointer classes.
+
+    \section1 Implicit Sharing in Detail
+
+    Implicit sharing automatically detaches the object from a shared
+    block if the object is about to change and the reference count is
+    greater than one. (This is often called \e {copy-on-write} or
+    \e {value semantics}.)
+
+    An implicitly shared class has total control of its internal data. In
+    any member functions that modify its data, it automatically detaches
+    before modifying the data.
+
+    The QPen class, which uses implicit sharing, detaches from the shared
+    data in all member functions that change the internal data.
+
+    Code fragment:
+    \snippet doc/src/snippets/code/doc_src_groups.qdoc 0
+
+
+    \section1 List of Classes
+
+    The classes listed below automatically detach from common data if
+    an object is about to be changed. The programmer will not even
+    notice that the objects are shared. Thus you should treat
+    separate instances of them as separate objects. They will always
+    behave as separate objects but with the added benefit of sharing
+    data whenever possible. For this reason, you can pass instances
+    of these classes as arguments to functions by value without
+    concern for the copying overhead.
+
+    Example:
+    \snippet doc/src/snippets/code/doc_src_groups.qdoc 1
+
+    In this example, \c p1 and \c p2 share data until QPainter::begin()
+    is called for \c p2, because painting a pixmap will modify it.
+
+    \warning Do not copy an implicitly shared container (QMap,
+    QVector, etc.) while you are iterating over it using an non-const
+    \l{STL-style iterator}.
+*/
diff --git a/src/3rdparty/webkit/WebKit/qt/Api/qwebhistory.cpp b/src/3rdparty/webkit/WebKit/qt/Api/qwebhistory.cpp
index e5eb308..1c1c72a 100644
--- a/src/3rdparty/webkit/WebKit/qt/Api/qwebhistory.cpp
+++ b/src/3rdparty/webkit/WebKit/qt/Api/qwebhistory.cpp
@@ -32,7 +32,6 @@
 
 /*!
   \class QWebHistoryItem
-  \ingroup explicitly-shared
   \since 4.4
   \brief The QWebHistoryItem class represents one item in the history of a QWebPage
 
@@ -52,13 +51,17 @@
   \row    \o userData()    \o The user specific data that was stored with the history item.
   \endtable
 
-  \note QWebHistoryItem objects are value based and \l{explicitly shared}.
+  \note QWebHistoryItem objects are value based, but \e{explicitly shared}. Changing
+  a QWebHistoryItem instance by calling setUserData() will change all copies of that
+  instance.
 
   \sa QWebHistory, QWebPage::history(), QWebHistoryInterface
 */
 
 /*!
-  Constructs a history item from \a other.
+  Constructs a history item from \a other. The new item and \a other
+  will share their data, and modifying either this item or \a other will
+  modify both instances.
 */
 QWebHistoryItem::QWebHistoryItem(const QWebHistoryItem &other)
     : d(other.d)
@@ -66,7 +69,9 @@ QWebHistoryItem::QWebHistoryItem(const QWebHistoryItem &other)
 }
 
 /*!
-  Assigns the \a other history item to this.
+  Assigns the \a other history item to this. This item and \a other
+  will share their data, and modifying either this item or \a other will
+  modify both instances.
 */
 QWebHistoryItem &QWebHistoryItem::operator=(const QWebHistoryItem &other)
 {
@@ -163,6 +168,8 @@ QVariant QWebHistoryItem::userData() const
   \since 4.5
 
  Stores user specific data \a userData with the history item.
+ 
+ \note All copies of this item will be modified.
 
  \sa userData()
 */
diff --git a/src/corelib/tools/qshareddata.cpp b/src/corelib/tools/qshareddata.cpp
index 3cd37a7..6cd220c 100644
--- a/src/corelib/tools/qshareddata.cpp
+++ b/src/corelib/tools/qshareddata.cpp
@@ -51,7 +51,7 @@ QT_BEGIN_NAMESPACE
 
   QSharedData is designed to be used with QSharedDataPointer or
   QExplicitlySharedDataPointer to implement custom \l{implicitly
-  shared} or \l {explicitly shared} classes. QSharedData provides
+  shared} or explicitly shared classes. QSharedData provides
   \l{thread-safe} reference counting.
 
  See QSharedDataPointer and QExplicitlySharedDataPointer for details.