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, 124 insertions, 0 deletions

diff --git a/src/corelib/doc/src/objectmodel/object.qdoc b/src/corelib/doc/src/objectmodel/object.qdoc
new file mode 100644
index 0000000000..4e212b37dd
--- /dev/null
+++ b/src/corelib/doc/src/objectmodel/object.qdoc
@@ -0,0 +1,124 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \page object.html
+    \title Object Model
+    \ingroup qt-basic-concepts
+    \brief A description of the powerful features made possible by Qt's dynamic object model.
+
+    The standard C++ object model provides very efficient runtime
+    support for the object paradigm. But its static nature is
+    inflexibile in certain problem domains. Graphical user interface
+    programming is a domain that requires both runtime efficiency and
+    a high level of flexibility. Qt provides this, by combining the
+    speed of C++ with the flexibility of the Qt Object Model.
+
+    Qt adds these features to C++:
+
+    \list
+    \li a very powerful mechanism for seamless object
+       communication called \l{signals and slots}
+    \li queryable and designable \l{Qt's Property System}{object
+       properties}
+    \li powerful \l{The Event System}{events and event filters}
+    \li contextual \l{i18n}{string translation for internationalization}
+    \li sophisticated interval driven \l timers that make it possible
+       to elegantly integrate many tasks in an event-driven GUI
+    \li hierarchical and queryable \l{Object Trees & Ownership}{object
+       trees} that organize object ownership in a natural way
+    \li guarded pointers (QPointer) that are automatically
+       set to 0 when the referenced object is destroyed, unlike normal C++
+       pointers which become dangling pointers when their objects are destroyed
+    \li a \l{metaobjects.html#qobjectcast}{dynamic cast} that works across
+       library boundaries.
+    \endlist
+
+    Many of these Qt features are implemented with standard C++
+    techniques, based on inheritance from QObject. Others, like the
+    object communication mechanism and the dynamic property system,
+    require the \l{Meta-Object System} provided
+    by Qt's own \l{moc}{Meta-Object Compiler (moc)}.
+
+    The meta-object system is a C++ extension that makes the language
+    better suited to true component GUI programming. Although
+    templates can be used to extend C++, the meta-object system
+    provides benefits using standard C++ that cannot be achieved with
+    templates; see \l{Why Doesn't Qt Use Templates for Signals and
+    Slots?}
+
+    \section1 Important Classes
+
+    These classes form the basis of the Qt Object Model.
+    
+    \annotatedlist objectmodel
+
+    \target Identity vs Value
+    \section1 Qt Objects: Identity vs Value
+
+    Some of the added features listed above for the Qt Object Model,
+    require that we think of Qt Objects as identities, not values.
+    Values are copied or assigned; identities are cloned. Cloning
+    means to create a new identity, not an exact copy of the old
+    one. For example, twins have different identities. They may look
+    identical, but they have different names, different locations, and
+    may have completely different social networks.
+
+    Then cloning an identity is a more complex operation than copying
+    or assigning a value. We can see what this means in the Qt Object
+    Model.
+
+    \b{A Qt Object...}
+
+    \list
+
+    \li might have a unique \l{QObject::objectName()}.  If we copy a Qt
+    Object, what name should we give the copy?
+
+    \li has a location in an \l{Object Trees & Ownership}
+    {object hierarchy}. If we copy a Qt Object, where should the copy
+    be located?
+
+    \li can be connected to other Qt Objects to emit signals to them or
+    to receive signals emitted by them. If we copy a Qt Object, how
+    should we transfer these connections to the copy?
+
+    \li can have \l{Qt's Property System} {new properties} added to it
+    at runtime that are not declared in the C++ class. If we copy a Qt
+    Object, should the copy include the properties that were added to
+    the original?
+    
+    \endlist
+
+    For these reasons, Qt Objects should be treated as identities, not
+    as values. Identities are cloned, not copied or assigned, and
+    cloning an identity is a more complex operation than copying or
+    assigning a value. Therefore, QObject and all subclasses of
+    QObject (direct or indirect) have their \l{No copy constructor}
+    {copy constructor and assignment operator} disabled.
+
+  */