Doc: Prepare for building modular QtCore docs.

This change fixes most qdoc errors in QtCore. There are about 900 left.
The main thing this change does is moving documentation from qtcore from
/doc/src to /src/corelib/doc.
Other issues resolved are mis-use of qdoc commands.

Change-Id: I002d01edfb13575e8bf27ce91596a577a92562d1
Reviewed-by: Lars Knoll <lars.knoll@nokia.com>
Reviewed-by: Jason McDonald <jason.mcdonald@nokia.com>
Reviewed-by: Jerome Pasion <jerome.pasion@nokia.com>

1 files changed, 138 insertions, 0 deletions

diff --git a/src/corelib/doc/src/implicit-sharing.qdoc b/src/corelib/doc/src/implicit-sharing.qdoc
new file mode 100644
index 0000000000..6fc60de35e
--- /dev/null
+++ b/src/corelib/doc/src/implicit-sharing.qdoc
@@ -0,0 +1,138 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/* TODO: Move some of the documentation from QSharedDataPointer into this
+   document. */
+
+/*!
+    \group shared
+    \title Implicitly Shared Classes
+*/
+
+/*!
+    \page implicit-sharing.html
+    \title Implicit Sharing
+    \ingroup qt-basic-concepts
+
+    \brief 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{Thread-Support in Qt Modules#Threads and Implicitly Shared Classes}
+    {Threads and Implicitly Shared Classes}.
+
+    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 code/doc_src_groups.cpp 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 code/doc_src_groups.cpp 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}.
+
+    \keyword implicitly shared classes
+    \annotatedlist shared
+*/