qdoc: More updating command descriptions.

1 files changed, 221 insertions, 257 deletions

diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc
index 5945aea..ddce165 100644
--- a/tools/qdoc3/doc/qdoc-manual.qdoc
+++ b/tools/qdoc3/doc/qdoc-manual.qdoc
@@ -4398,7 +4398,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 +4569,7 @@
     \endcode
 
     QDoc generates a group page in \c{io.html} that will look
-    something like this:
+    like this:
 
     \quotation
          \raw HTML
@@ -4663,7 +4663,7 @@
            \endcode
 
     QDoc generates a header file page \c{qtalgorithms.html} that looks
-    something like this:
+    like this:
 
            \quotation
                \raw HTML
@@ -4831,7 +4831,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 +4913,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,336 +5035,300 @@
     \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.
+    The \\property command is for documenting a Qt property. The
+    argument is the full property name.
 
-           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:
-
-           \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.
+    \code
+    Q_PROPERTY(QString state READ state WRITE setState)
+    \endcode
 
-           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.
 
-           \code
-           / *!
-               \property QPushButton::flat
-               \brief whether the border is disabled
+    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:
 
-               This property's default is false.
-           * /
-           \endcode
+    \code
+    / *!
+        \property QPushButton::flat
+        \brief whether the border is disabled
 
-           QDoc renders this as:
+        This property's default is false.
+    * /
+    \endcode
 
-           \quotation
-               \raw HTML
-               <h3>flat : bool</h3>
-               \endraw
+    QDoc includes this in \c {qpushbutton.html} like this:
 
-               This property holds whether the border is disabled.
+    \quotation
+        \raw HTML
+        <h3>flat : bool</h3>
+        \endraw
 
-               This property's default is false.
+        This property holds whether the border is disabled.
 
-               Access functions:
+        This property's default is false.
 
-               \list
-               \o \bold { bool isFlat () const}
-               \o \bold { void setFlat ( bool )}
-               \endlist
+        Access functions:
 
-           \endquotation
+        \list
+        \o \bold { bool isFlat () const}
+        \o \bold { void setFlat ( bool )}
+        \endlist
 
-           in qpushbutton.html. And
+    \endquotation
 
-           \code
-           / *!
-               \property QWidget::width
-               \brief the width of the widget excluding any window frame
+    \code
+    / *!
+        \property QWidget::width
+        \brief the width of the widget excluding any window frame
 
-               See the \l {Window Geometry} documentation for an
-               overview of window geometry.
+        See the \l {Window Geometry} documentation for an
+        overview of window geometry.
 
-               \sa geometry, height, size
-           * /
-           \endcode
+        \sa geometry, height, size
+    * /
+    \endcode
 
-           QDoc renders this as:
+    QDoc includes this in \c {qwidget.html} like this:
 
-           \quotation
-               \raw HTML
-               <h3>width : const int</h3>
-               \endraw
+    \quotation
+        \raw HTML
+        <h3>width : const int</h3>
+        \endraw
 
-               This property holds the width of the widget excluding
-               any window frame.
+        This property holds the width of the widget excluding
+        any window frame.
 
-               See the \l {Window Geometry} documentation for an
-               overview of window geometry.
+        See the \l {Window Geometry} documentation for an
+        overview of window geometry.
 
-               Access functions:
+        Access functions:
 
-               \list
-               \o \bold { int width () const}
-               \endlist
-
-               See also \l{QWidget::geometry} {geometry},
-               \l{QWidget::height} {height}, and \l{QWidget::size} {size}.
-           \endquotation
-
-           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 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:
+    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:
 
-           \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 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.
-
-           In case of a member variable:
-
-           \code
-           / *!
-               \variable QStyleOption::palette
-               \brief the palette that should be used when painting
-                      the control
-           * /
-           \endcode
+    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. 
 
-           QDoc renders this as:
+    The documentation will be located in the in the associated class,
+    header file or namespace documentation.
 
-           \quotation
-               \raw HTML
-               <h3>
-               <a href="http://qt.nokia.com/doc/4.0/qpalette.html">
-               QPalette
-               </a>
-               QStyleOption::palette
-               </h3>
-               \endraw
+    In case of a member variable:
 
-               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
 */
 
 /*!