Merge branch '4.7' of scm.dev.nokia.troll.no:qt/qt-doc-team into 4.7

1 files changed, 306 insertions, 316 deletions

diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc
index a613177..4a395e0 100644
--- a/tools/qdoc3/doc/qdoc-manual.qdoc
+++ b/tools/qdoc3/doc/qdoc-manual.qdoc
@@ -38,7 +38,7 @@
           \o \l {Topic Commands}
           \o \l {Context Commands}
             \list
-              \o \l {Navigating}
+              \o \l {Document Navigation}
               \o \l {Reporting Status}
               \o \l {Thread Support}
               \o \l {Relating Things}
@@ -81,26 +81,75 @@
 
     \title Introduction to QDoc
 
-    QDoc is a tool used by Qt Developers to extract \e {qdoc comments}
-    from a set of source files and format them for output as HTML
-    pages or as DITA XML files.. This manual explains how to use the
-    QDoc commands and how to create a QDoc configuration file.
+    QDoc is a tool used by Qt Developers to generate documentation of
+    software projects by extracting the documentation from the project
+    source files and then formatting it as HTML pages or DITA XML
+    documents, etc. The documentation is embedded in the source files
+    in \e {qdoc comments}. A qdoc comment begins with an exclamation
+    mark \bold{(!)} e.g.:
+
+    \code 
+        / *! 
+            \class QObject
+            \brief The QObject class is the base class of all Qt objects.
+
+            \ingroup objectmodel
+
+            \reentrant
+
+            QObject is the heart of the Qt \l{Object Model}. The
+            central feature in this model is a very powerful mechanism
+            for seamless object communication called \l{signals and
+            slots}. You can connect a signal to a slot with connect()
+            and destroy the connection with disconnect(). To avoid
+            never ending notification loops you can temporarily block
+            signals with blockSignals(). The protected functions
+            connectNotify() and disconnectNotify() make it possible to
+            track connections.
+
+            QObjects organize themselves in \l {Object Trees &
+            Ownership} {object trees}. When you create a QObject with
+            another object as parent, the object will automatically
+            add itself to the parent's children() list. The parent
+            takes ownership of the object; i.e., it will automatically
+            delete its children in its destructor. You can look for an
+            object by name and optionally type using findChild() or
+            findChildren().
+
+            Every object has an objectName() and its class name can be
+            found via the corresponding metaObject() (see
+            QMetaObject::className()).  You can determine whether the
+            object's class inherits another class in the QObject
+            inheritance hierarchy by using the inherits() function.
+
+	    ....
+	* /
+    \endcode
+
+    From this snippet, QDoc generates the now famous HTML page \l
+    {http://doc.trolltech.com/4.7/qobject.html} {QObject Class Reference}.
+    
+    This manual explains how to use the QDoc commands to write useful
+    qdoc comments in your source files. It also explains how to create
+    a \l {The QDoc Configuration File} {QDoc configuration file},
+    which you must pass to QDoc on the command line when you run it.
 
     \section1 Running QDoc
 
-    QDoc is currently called \c {qdoc3}. To run qdoc3, use the command
-    line:
+    The current name of the QDoc program is \c {qdoc3}. To run qdoc3
+    from the command line, give it the name of a configuration file:
 
     \quotation
-        \bold {/currentdirectory$ qdoc3 config.qdocconf}
+        \c {/current/dir$ ../../bin/qdoc3 ./config.qdocconf}
     \endquotation
 
-    ...where config.qdocconf is your \l{The QDoc Configuration File}
-    {QDoc configuration file}. The main purpose of the configuration
-    file is to tell qdoc3 where to find the source files from which to
-    extract qdoc comments, what kind of output to generate (HTML, DITA
-    XML,...}, and where to put the output. The configuration file also
-    contains other information for qdoc3.
+    \c{config.qdocconf} is your \l{The QDoc Configuration File} {QDoc
+    configuration file}. The configuration file is where tell QDoc
+    where to find the source files from which it will extract the QDoc
+    comments it will use to generate the documentation. It is also
+    where you tell QDoc what kind of output to generate (HTML, DITA
+    XML,...), and where to put the generated output. The configuration
+    file also contains other information for QDoc.
 
     \section1 Command Types
 
@@ -112,20 +161,20 @@
     \o \l {Markup Commands}
     \endlist
 
-    Topic commands identify the entity you are documenting, e.g. a C++
+    Topic commands identify the elememt you are documenting, e.g. a C++
     class, function, or type, an example, or an extra page of text
-    that doesn't map to any C++ entity.
+    that doesn't map to an underlying C++ elememnt.
 
-    Context commands tell QDoc how the entity being documented relates
-    to other documented entities, e.g. next and previous page links or
-    inclusion in page groups or library modules. They can also provide
-    information about the documented entity that QDoc can't get from
-    the source files, e.g. whether the entitity is thread-safe, an
-    overloaded or reimplemented function, or that it has been
-    deprecated.
+    Context commands tell QDoc how the element being documented
+    relates to other documented elememnts, e.g. next and previous page
+    links or inclusion in page groups or library modules. Context
+    commands can also provide information about the documented element
+    that QDoc can't get from the source files, e.g. whether the
+    element is thread-safe, an overloaded or reimplemented function,
+    or that it has been deprecated.
 
     Markup commands tell QDoc how text and image elements in the
-    document should be rendered or about the document's outline
+    document should be rendered, or about the document's outline
     structure.  
 */
 
@@ -4398,7 +4447,7 @@
     \endcode
 
     Note the inclusion of the namespace qualifier. QDoc will render
-    this enum type in \c {qt.html} something like this:
+    this enum type in \c {qt.html} like this:
 
            \quotation
            \raw HTML
@@ -4569,7 +4618,7 @@
     \endcode
 
     QDoc generates a group page in \c{io.html} that will look
-    something like this:
+    like this:
 
     \quotation
          \raw HTML
@@ -4663,7 +4712,7 @@
            \endcode
 
     QDoc generates a header file page \c{qtalgorithms.html} that looks
-    something like this:
+    like this:
 
            \quotation
                \raw HTML
@@ -4831,7 +4880,7 @@
     * /
     \endcode
 
-    QDoc renders this in \c {qtnetwork.html} something like this:
+    QDoc renders this in \c {qtnetwork.html} like this:
 
            \quotation
                \raw HTML
@@ -4913,7 +4962,7 @@
     * /
     \endcode
 
-    QDoc renders this in \c{qt.html} something like this:
+    QDoc renders this in \c{qt.html} like this:
 
            \quotation
                \raw HTML
@@ -5035,385 +5084,326 @@
     \target property-command
     \section1 \\property 
 
-    The \\property command allows you to document a Qt property.
-
-           The command follows \l {topic argument} {the general
-           topic command convention} for the argument.
-
-           A property is defined using the Q_PROPERTY() macro. The
-           macro takes as arguments the property's name and its set,
-           reset and get functions. For example:
+    The \\property command is for documenting a Qt property. The
+    argument is the full property name.
 
-           \code
-           Q_PROPERTY(QString state READ state WRITE setState)
-           \endcode
+    A property is defined using the Q_PROPERTY() macro. The macro
+    takes as arguments the property's name and its set, reset and get
+    functions. For example:
 
-           The set, reset and get functions don't need to be
-           documented, documenting the property is sufficient. QDoc
-           will generate a list of the access function that will
-           appear in the property documentation which in turn will be
-           located in the documentation of the class that defines the
-           property.
-
-           The \\property command is typically accompanied with a \l
-           {brief-command} {\\brief} command.  In the case of a
-           property, the \l {brief-command} {\\brief} command's
-           argument is a sentence fragment that will be included in a
-           one-sentence description of the property generated by
-           QDoc. The command follows the same rules for the \l
-           {brief-property} {description} as the \l {variable-command}
-           {\\variable} command.
-
-           For example:
-
-           \code
-           / *!
-               \property QPushButton::flat
-               \brief whether the border is disabled
+    \code
+    Q_PROPERTY(QString state READ state WRITE setState)
+    \endcode
 
-               This property's default is false.
-           * /
-           \endcode
+    The set, reset and get functions don't need to be documented,
+    documenting the property is sufficient. QDoc will generate a list
+    of the access function that will appear in the property
+    documentation which in turn will be located in the documentation
+    of the class that defines the property.
 
-           QDoc renders this as:
+    The \\property command comment typically includes a \l
+    {brief-command} {\\brief} command. Forproperties the \l
+    {brief-command} {\\brief} command's argument is a sentence
+    fragment that will be included in a one line description of the
+    property. The command follows the same rules for the \l
+    {brief-property} {description} as the \l {variable-command}
+    {\\variable} command. For example:
 
-           \quotation
-               \raw HTML
-               <h3>flat : bool</h3>
-               \endraw
+    \code
+    / *!
+        \property QPushButton::flat
+        \brief whether the border is disabled
 
-               This property holds whether the border is disabled.
+        This property's default is false.
+    * /
+    \endcode
 
-               This property's default is false.
+    QDoc includes this in \c {qpushbutton.html} like this:
 
-               Access functions:
+    \quotation
+        \raw HTML
+        <h3>flat : bool</h3>
+        \endraw
 
-               \list
-               \o \bold { bool isFlat () const}
-               \o \bold { void setFlat ( bool )}
-               \endlist
+        This property holds whether the border is disabled.
 
-           \endquotation
+        This property's default is false.
 
-           in qpushbutton.html. And
+        Access functions:
 
-           \code
-           / *!
-               \property QWidget::width
-               \brief the width of the widget excluding any window frame
+        \list
+        \o \bold { bool isFlat () const}
+        \o \bold { void setFlat ( bool )}
+        \endlist
 
-               See the \l {Window Geometry} documentation for an
-               overview of window geometry.
+    \endquotation
 
-               \sa geometry, height, size
-           * /
-           \endcode
+    \code
+    / *!
+        \property QWidget::width
+        \brief the width of the widget excluding any window frame
 
-           QDoc renders this as:
+        See the \l {Window Geometry} documentation for an
+        overview of window geometry.
 
-           \quotation
-               \raw HTML
-               <h3>width : const int</h3>
-               \endraw
+        \sa geometry, height, size
+    * /
+    \endcode
 
-               This property holds the width of the widget excluding
-               any window frame.
+    QDoc includes this in \c {qwidget.html} like this:
 
-               See the \l {Window Geometry} documentation for an
-               overview of window geometry.
+    \quotation
+        \raw HTML
+        <h3>width : const int</h3>
+        \endraw
 
-               Access functions:
+        This property holds the width of the widget excluding
+        any window frame.
 
-               \list
-               \o \bold { int width () const}
-               \endlist
+        See the \l {Window Geometry} documentation for an
+        overview of window geometry.
 
-               See also \l{QWidget::geometry} {geometry},
-               \l{QWidget::height} {height}, and \l{QWidget::size} {size}.
-           \endquotation
+        Access functions:
 
-           in qwidget.html.
+        \list
+        \o \bold { int width () const}
+        \endlist
 
+        See also \l{QWidget::geometry} {geometry},
+        \l{QWidget::height} {height}, and \l{QWidget::size} {size}.
+    \endquotation
 
     \target service-command
     \section1 \\service 
 
-    The \\service command tells QDoc that a class is a
-    service class and specifies its alias, i.e. the associated
-    service's name.
-
-            The command takes two arguments, the service class's name
-            and the associated alias. For example:
-
-            \code
-                / *!
-                    \service TimeService Time
-                    ...
-                * /
-                class TimeService : public QCopObjectService
-                {
-                    ...
-                }
-            \endcode
-
-            See also \l {class-command} {\\class} and \l
-            {generatelist-command} {\\generatelist}.
-
+    The \\service command tells QDoc that a class is a service class
+    and names the service. The command takes two arguments, the name
+    of the class and the name of the service. Currently, this command 
+    is not used in the Qt documentation.
+
+     \code
+         / *!
+             \service TimeService Time
+             ...
+         * /
+         class TimeService : public QCopObjectService
+         {
+             ...
+         }
+     \endcode
+
+     See also \l {class-command} {\\class} and \l
+     {generatelist-command} {\\generatelist}.
 
     \target typedef-command
     \section1 \\typedef 
 
-    The \\typedef command allows you to document a C++ type definition.
+    The \\typedef command is for documenting a C++ typedef. The
+    argument is the name of the typedef. The documentation for 
+    the typedef will be included in the refernece documentation 
+    for the class, namespace, or header file in which the typedef 
+    is declared. To relat the \\typedef to a class, namespace, or 
+    header file, the \\typedef comment must contain a
+     \l {relates-command} {\\relates} command. For example:
 
-           The command follows \l {topic argument} {the general
-           topic command convention} for the argument.
-
-           The documentation will be located in the associated class,
-           header file or namespace documentation. When documenting a
-           global type definition, the \\typedef command must be
-           accompanied with a \l {relates-command} {\\relates} command. For
-           example:
-
-           \code
-           / *!
-               \typedef QObjectList
-               \relates QObject
-
-               Synonym for QList<QObject>.
-           * /
-           \endcode
-
-           QDoc renders this as:
-
-           \quotation
-               \raw HTML
-               <h3>typedef QObjectList</h3>
-               \endraw
+    \code
+    / *!
+        \typedef QObjectList
+        \relates QObject
 
-               Synonym for QList<QObject>.
-           \endquotation
+        Synonym for QList<QObject>.
+    * /
+    \endcode
 
-           in qobject.html. Another, although more rare, example is
+    QDoc includes this in \c {qobject.html} as:
 
-           \code
-           / *!
-               \typedef QMsgHandler
-               \relates QtGlobal
+    \quotation
+        \raw HTML
+        <h3>typedef QObjectList</h3>
+        \endraw
 
-               This is a typedef for a pointer to a function with the
-               following signature:
+        Synonym for QList<QObject>.
+    \endquotation
 
-               \code
-                   void myMsgHandler(QtMsgType, const char *);
-               \ endcode
+    Another, although more rare, example:
 
-               \sa QtMsgType, qInstallMsgHandler()
-           * /
-           \endcode
+    \code
+    / *!
+        \typedef QMsgHandler
+        \relates QtGlobal
 
-           QDoc renders this as:
+        This is a typedef for a pointer to a function with the
+        following signature:
 
-           \quotation
-               \raw HTML
-               <h3>typedef QtMsgHandler</h3>
-               \endraw
+        \code
+            void myMsgHandler(QtMsgType, const char *);
+        \ endcode
 
-               This is a typedef for a pointer to a function with the
-               following signature:
+        \sa QtMsgType, qInstallMsgHandler()
+    * /
+    \endcode
 
-               \raw HTML
-               <tt>
-               <pre>    void myMsgHandler(QtMsgType, const char *);</pre>
-               </tt>
-               \endraw
+    QDoc includes this in \c {qtglobal.html} as:
 
-               See also QtMsgType and qInstallMsgHandler().
+    \quotation
+        \raw HTML
+        <h3>typedef QtMsgHandler</h3>
+        \endraw
 
-           \endquotation
+        This is a typedef for a pointer to a function with the
+        following signature:
 
-           in qtglobal.html. Other type definitions are located in the
-           documentation of the class that defines it, for example:
+        \raw HTML
+        <tt>
+        <pre>    void myMsgHandler(QtMsgType, const char *);</pre>
+        </tt>
+        \endraw
 
-           \code
-           / *!
-               \typedef QLinkedList::Iterator
+        See also QtMsgType and qInstallMsgHandler().
+    \endquotation
 
-               Qt-style synonym for QList::iterator.
-           * /
-           \endcode
+    Other typedefs are located on the reference page for the class
+    that defines them. For example:
 
-           QDoc renders this as:
+    \code
+    / *!
+        \typedef QLinkedList::Iterator
 
-           \quotation
-               \raw HTML
-               <h3>typedef QLinkedList::Iterator</h3>
-               \endraw
+        Qt-style synonym for QList::iterator.
+    * /
+    \endcode
 
-               Qt-style synonym for QList::iterator.
-           \endquotation
+    QDoc includes this one on the reference page for class QLinkedList as:
 
-           in qlinkedlist.html.
+    \quotation
+        \raw HTML
+        <h3>typedef QLinkedList::Iterator</h3>
+        \endraw
 
+        Qt-style synonym for QList::iterator.
+    \endquotation
 
     \target variable-command
     \section1 \\variable 
 
-    The \\variable command allows you to document a
-    member variable or a constant.
-
-           The command follows \l {topic argument} {the general
-           topic command convention} for the argument.
+    The \\variable command is for documenting a class member variable
+    or a constant. The argument is the variable or constant name. The
+    \\variable command comment includes a \l {brief-command} {\\brief}
+    command. QDoc generates the documentation based on the text from
+    \\brief command. 
 
-           The \\variable command is typically followed by a 
-	   \l {brief-command} {\\brief} command; QDoc will generate the
-           documentation for the variable based on the brief command
-           description. The command follows the same rules for the 
-	   \l {brief-property} {description} as the \l {property-command}
-           {\\property} command.
+    The documentation will be located in the in the associated class,
+    header file or namespace documentation.
 
-           The documentation will be located in the in the associated
-           class, header file or namespace documentation.
+    In case of a member variable:
 
-           In case of a member variable:
-
-           \code
-           / *!
-               \variable QStyleOption::palette
-               \brief the palette that should be used when painting
-                      the control
-           * /
-           \endcode
-
-           QDoc renders this as:
-
-           \quotation
-               \raw HTML
-               <h3>
-               <a href="http://qt.nokia.com/doc/4.0/qpalette.html">
-               QPalette
-               </a>
-               QStyleOption::palette
-               </h3>
-               \endraw
-
-               This variable holds the palette that should be used
-               when painting the control.
-           \endquotation
-
-           in qstyleoption.html.
-
-           But you can also use the \\variable command to document
-           constants like for example the \c Type and \c UserType
-           constants in the QTreeWidgetItem class:
+    \code
+    / *!
+        \variable QStyleOption::palette
+        \brief the palette that should be used when painting
+               the control
+    * /
+    \endcode
 
-           \code
-           enum { Type = 0, UserType = 1000 };
-           \endcode
+    QDoc includes this in qstyleoption.html as:
 
-           Then
+    \quotation
+        \raw HTML
+        <h3>
+            <a href="http://qt.nokia.com/doc/4.0/qpalette.html">
+                QPalette
+            </a>
+            QStyleOption::palette
+        </h3>
+        \endraw
 
-           \code
-           / *!
-               \variable QTreeWidgetItem::Type
+        This variable holds the palette that should be used
+        when painting the control.
+    \endquotation
 
-               The default type for tree widget items.
+    You can also document constants with the \\variable command.  For
+    example, suppose you have the \c Type and \c UserType constants in
+    the QTreeWidgetItem class:
 
-               \sa UserType, type()
-           * /
-           \endcode
+    \code
+    enum { Type = 0, UserType = 1000 };
+    \endcode
 
-           and
+    For these, the \\vaqriable command can be used this way:
 
-           \code
-           / *!
-               \variable QTreeWidgetItem::UserType
+    \code
+    / *!
+        \variable QTreeWidgetItem::Type
 
-               The minimum value for custom types. Values below
-               UserType are reserved by Qt.
+        The default type for tree widget items.
 
-               \sa Type, type()
-           * /
-           \endcode
+        \sa UserType, type()
+    * /
+    \endcode
+    \code
+    / *!
+        \variable QTreeWidgetItem::UserType
 
-           QDoc renders this as:
+        The minimum value for custom types. Values below
+        UserType are reserved by Qt.
 
-           \quotation
-               \raw HTML
-               <h3>
-               const int QTreeWidgetItem::Type
-               </h3>
-               \endraw
+        \sa Type, type()
+    * /
+    \endcode
 
-               The default type for tree widget items.
+    QDoc includes these in qtreewidget.html as:
 
-               See also \l {QTreeWidgetItem::UserType} {UserType} and
-               \l {QTreeWidgetItem::type()} {type()}.
+    \quotation
+        \raw HTML
+        <h3>
+        const int QTreeWidgetItem::Type
+        </h3>
+        \endraw
 
-               \raw HTML
-               <h3>
-               const int QTreeWidgetItem::UserType
-               </h3>
-               \endraw
+        The default type for tree widget items.
 
-               The minimum value for custom types. Values below
-               UserType are reserved by Qt.
+        See also \l {QTreeWidgetItem::UserType} {UserType} and \l
+        {QTreeWidgetItem::type()} {type()}.
 
-               See also \l {QTreeWidgetItem::Type} {Type} and
-               \l{QTreeWidgetItem::type()} {type()}.
+        \raw HTML
+        <h3>
+        const int QTreeWidgetItem::UserType
+        </h3>
+        \endraw
 
-           \endquotation
+        The minimum value for custom types. Values below
+        UserType are reserved by Qt.
 
-           in qtreewidget.html.
+        See also \l {QTreeWidgetItem::Type} {Type} and
+        \l{QTreeWidgetItem::type()} {type()}.
 
+    \endquotation
 */
 
 /*!
     \page 14-qdoc-commands-contextcommands.html
     \previouspage Topic Commands
     \contentspage Table of Contents
-    \nextpage Navigating
+    \nextpage Document Navigation
 
     \title Context Commands
 
-    The context commands provide QDoc with information, that it
-    wouldn't figure out otherwise, about the documented object. For
-    example whether a class is thread-safe or not.
-
-    These commands can appear anywhere within a QDoc comment.
+    The context commands provide information about the element being
+    documented that QDoc can't deduce on its own. e.g. Is a class
+    thread-safe? Is a function reentrant? Which module is the class a
+    member of? Context commands can appear anywhere in a QDoc comment,
+    but we put them at the top of the comment, right below the \l
+    {Topic Commands} {topic} command.
 
     \section1 Categories
     \list
-    \o \l {Navigating}
+    \o \l {Document Navigation}
     \o \l {Reporting Status}
     \o \l {Thread Support}
     \o \l {Relating Things}
     \o \l {Grouping Things}
     \o \l {Naming Things}
     \endlist
-
-    \section1 Command List
-
-    \list
-    \o \l {16-qdoc-commands-status.html#compat-command} {\\compat}
-    \o \l {15-qdoc-commands-navigation.html#contentspage-command} {\\contentspage}
-    \o \l {15-qdoc-commands-navigation.html#indexpage-command} {\\indexpage}
-    \o \l {19-qdoc-commands-grouping.html#ingroup-command} {\\ingroup}
-    \o \l {19-qdoc-commands-grouping.html#inmodule-command} {\\inmodule}
-    \o \l {16-qdoc-commands-status.html#internal-command} {\\internal}
-    \o \l {19-qdoc-commands-grouping.html#mainclass-command} {\\mainclass}
-    \o \l {15-qdoc-commands-navigation.html#nextpage-command} {\\nextpage}
-    \o \l {17-qdoc-commands-thread.html#nonreentrant-command} {\\nonreentrant}
-    \o \l {16-qdoc-commands-status.html#obsolete-command} {\\obsolete}
-    \o \l {18-qdoc-commands-relating.html#overload-command} {\\overload}
-    \o \l {16-qdoc-commands-status.html#preliminary-command} {\\preliminary}
-    \o \l {15-qdoc-commands-navigation.html#previouspage-command} {\\previouspage}
-    \o \l {17-qdoc-commands-thread.html#reentrant-command} {\\reentrant}
-    \o \l {18-qdoc-commands-relating.html#reimp-command} {\\reimp}
-    \o \l {18-qdoc-commands-relating.html#relates-command} {\\relates}
-    \o \l {15-qdoc-commands-navigation.html#startpage-command} {\\startpage}
-    \o \l {17-qdoc-commands-thread.html#threadsafe-command} {\\threadsafe}
-    \o \l {20-qdoc-commands-namingthings.html#title-command} {\\title}
-    \endlist
 */
 
 /*!
@@ -5422,7 +5412,7 @@
     \contentspage Table of Contents
     \nextpage Reporting Status
 
-    \title Navigating
+    \title Document Navigation
 
     The navigation commands allow you to link the pages of a multipage
     document together. They provide the components of a navigation bar
@@ -5431,8 +5421,8 @@
 
     \section1 General Description
 
-    The QDoc comments below shows a typical example using the
-    navigation commands.
+    The QDoc comments below show a typical way of using the navigation
+    commands.
 
     \code
     / *!
@@ -5645,7 +5635,7 @@
 
 /*!
     \page 16-qdoc-commands-status.html
-    \previouspage Navigating
+    \previouspage Document Navigation
     \contentspage Table of Contents
     \nextpage Thread Support