From cb7aaec6e914b8fd30520aa02645aae9e2dd1e91 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Wed, 23 Feb 2011 12:19:57 +0100 Subject: qdoc: More updating command descriptions. --- tools/qdoc3/doc/qdoc-manual.qdoc | 478 ++++++++++++++++++--------------------- 1 file 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 -

flat : bool

- \endraw + QDoc includes this in \c {qpushbutton.html} like this: - This property holds whether the border is disabled. + \quotation + \raw HTML +

flat : bool

+ \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 -

width : const int

- \endraw + \quotation + \raw HTML +

width : const int

+ \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. - * / - \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 -

typedef QObjectList

- \endraw + \code + / *! + \typedef QObjectList + \relates QObject - Synonym for QList. - \endquotation + Synonym for QList. + * / + \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 +

typedef QObjectList

+ \endraw - This is a typedef for a pointer to a function with the - following signature: + Synonym for QList. + \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 -

typedef QtMsgHandler

- \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 - -
    void myMsgHandler(QtMsgType, const char *);
-
- \endraw + QDoc includes this in \c {qtglobal.html} as: - See also QtMsgType and qInstallMsgHandler(). + \quotation + \raw HTML +

typedef QtMsgHandler

+ \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 + +
    void myMsgHandler(QtMsgType, const char *);
+
+ \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 -

typedef QLinkedList::Iterator

- \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 +

typedef QLinkedList::Iterator

+ \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 -

- - QPalette - - QStyleOption::palette -

- \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 +

+ + QPalette + + QStyleOption::palette +

+ \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 -

- const int QTreeWidgetItem::Type -

- \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 +

+ const int QTreeWidgetItem::Type +

+ \endraw - \raw HTML -

- const int QTreeWidgetItem::UserType -

- \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 +

+ const int QTreeWidgetItem::UserType +

+ \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 */ /*! -- cgit v0.12