From 1743bce4ff6fc4cb6788964ce0cc653aa0988b7e Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Mon, 21 Feb 2011 12:09:33 +0100 Subject: qdoc: More updating command descriptions. --- tools/qdoc3/doc/qdoc-manual.qdoc | 356 ++++++++++++++++----------------------- 1 file changed, 145 insertions(+), 211 deletions(-) diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc index 4506b85..03ca0a9 100644 --- a/tools/qdoc3/doc/qdoc-manual.qdoc +++ b/tools/qdoc3/doc/qdoc-manual.qdoc @@ -3284,11 +3284,11 @@ The \\legalese and \\endlegalese commands delimit a licence agreement. - In the generated HTML, the delimited text is surrounded by a - \bold {
} and \bold {
} tags. + In the generated HTML, the delimited text is surrounded by a \bold + {
} and \bold {
} tags. - For example, here is a license agreement enclosed in \\legalese and - \\endlegalese: + For example, here is a license agreement enclosed in \\legalese + and \\endlegalese: \code / *! @@ -3335,26 +3335,23 @@ \endcode - If the \\endlegalese command is omitted, QDoc will still - process the \\legalese command but considers the rest of the - documentation page as the license agreement. + If the \\endlegalese command is omitted, QDoc will process the + \\legalese command but considers the rest of the documentation + page as the license agreement. - Ideally, the license text is located with the licensed code. - - Elsewhere, the documentation identified as \e{\\legalese} - command can be accumulated using \l {generatelist-command} - {\\generatelist} with \c {legalese-command} as the argument. This is - useful for generating an overview of the license agreements - associated with the source code. + Ideally, the license text is located with the licensed code. + Elsewhere, the documentation identified as \e{\\legalese} command + can be accumulated using \l {generatelist-command} {\\generatelist} + with \c {legalese-command} as the argument. This is useful for + generating an overview of the license agreements associated with + the source code. \target warning-command \section1 \\warning - The \\warning command renders a "Warning:" prefix to - the command's argument. - - For example: + The \\warning command prepends "Warning:" to the command's + argument, in bold font. For example: \code / *! @@ -3367,7 +3364,7 @@ * / \endcode - QDoc renders this as: + QDoc renders this as: \quotation Qt::HANDLE is a platform-specific handle type @@ -3388,9 +3385,9 @@ \title Miscellaneous - These commands provide miscellaneous functions - connected to the visual appearance of the documentation, and to the - process of generating the documentation. + These commands provide miscellaneous functions connected to the + visual appearance of the documentation, and to the process of + generating the documentation. \target expire-command \section1 \\expire @@ -3398,10 +3395,10 @@ The \\expire command allows you to define an expiration date for your documentation. - When using the \\expire command, QDoc will emit a warning - when the current date is larger than the specified - date. The command accepts one argument; the argument's - format is yyyy-mm-dd. For example: + When using the \\expire command, QDoc will emit a warning when the + current date is larger than the specified date. The command + accepts one argument; the argument's format is yyyy-mm-dd. For + example: \code / *! @@ -3420,7 +3417,7 @@ * / \endcode - If you run QDoc on 4 July 2005, it will emit the warning + If you run QDoc on 4 July 2005, it will emit the warning \quotation porting.qdoc:6: Documentation expired 185 days ago @@ -3430,10 +3427,9 @@ \target generatelist-command \section1 \\generatelist - The \\generatelist command expands to a list of - various documentation or links to documentation. - - For example in the Qt Reference Documentation: + The \\generatelist command expands to a list of various + documentation or links to documentation. Below is an example from + the Qt Reference Documentation: \code / *! @@ -3449,225 +3445,163 @@ * / \endcode - is used to generate \l {All Classes}. - - The command accepts the following arguments: - - \target table example - - \section2 \c annotatedclasses - - The \c annotatedclasses argument provides a table - containing the names of all the classes, and a - description of each class. Each class name is a link to - the class's reference documentation. - - For example: - - \table - \row - \o QDial - \o Rounded range control (like a speedometer or potentiometer) - \row - \o QDialog - \o The base class of dialog windows - \row - \o QDir - \o Access to directory structures and their contents - \endtable - - \quotation - \raw HTML - - - - - - - - - - - - - - - - -
- - QDial - Rounded range control (like a speedometer - or potentiometer)
- - QDialog - The base class of dialog windows
- - QDir - Access to directory structures and their - contents
- \endraw - \endquotation - - A class is identified within the documentation by the - the \l {class-command} {\\class} command, and the descriptions - are based on the argument of the \l {brief-command} {\\brief} - commands in the class documentation. - - \target list example - - \section2 \c classes - - The \c classes argument provides a complete alphabetical - list of the classes. Each class name is a link to the - class's reference documentation. - - For example: - - \quotation - \raw HTML -

- - - - + This generates the \l {All Classes} page. The command accepts the + following arguments: - - + \target table example + \section2 \c annotatedclasses - - - - - - - + The \c annotatedclasses argument provides a table containing the + names of all the classes, and a description of each class. Each + class name is a link to the class's reference documentation. For + example: - - + \table + \row + \o QDial + \o Rounded range control (like a speedometer or potentiometer) + \row + \o QDialog + \o The base class of dialog windows + \row + \o QDir + \o Access to directory structures and their contents + \endtable - - - + A C++ class is documented with the \l {class-command} {\\class} + command. The annotation for the class is taken from the argument + of the class comment's \l {brief-command} {\\brief} command. - - - + \target list example + \section2 \c classes - - + The \c classes argument provides a complete alphabetical list of + the classes. Each class name is a link to the class's reference + documentation. - - - -
A QAbstractButtonQAbstractExtensionManagerQAbstractItemModel
QAbstractEventDispatcherQAbstractFormBuilderQAbstractItemView
QAbstractExtensionFactoryQAbstractItemDelegateQAbstractListModel

- \endraw - \endquotation + For example: - A class is identified within the documentation by the - the \l {class-command} {\\class} command. + \quotation + \raw HTML +

+ + + + - \section2 \c classesbymodule + + - This particular argument requests an additional argument, - i.e. a specification of the module. + + + - For example: + + + - \code - / *! - \page qtgui.html - \contentspage Qt Classes by Module - \previouspage QtCore Classes - \nextpage QtNetwork Classes + + - \title QtGui Classes + + + - \keyword QtGui + + + - \generatelist {classesbymodule QtGui} - * / - \endcode + + - Together, these arguments provide a table containing the - classes considered members of the specified module, - accompanied with a brief description. Each class name is - a link to the class's reference documentation. + + + +
A QAbstractButtonQAbstractExtensionManagerQAbstractItemModel
QAbstractEventDispatcherQAbstractFormBuilderQAbstractItemView
QAbstractExtensionFactoryQAbstractItemDelegateQAbstractListModel

+ \endraw + \endquotation - The generated table is rendered similarily to the one - generated when using the \l {table example} {\c - annotatedclasses} argument. + A C++ class is documented with the \l {class-command} {\\class} + command. - For the basic classes in Qt, a class's module is - determined by its location, i.e. its directory. However, - for extensions, like ActiveQt and Qt Designer, a class - is related to a module with the \l - {inmodule-command} {\\inmodule} command. + \section2 \c classesbymodule - \section2 \c classesbyedition + When this argument is used, a second argument is required, which + specifies the module whose classes are to be listed. QDoc + generates a table containing those classes. Each class is listed + with the text of its \l{brief-command} {\\brief} command. - This particular argument requests an additional argument, - i.e. a specification of the edition. + This command is used to generate the \l {phonon-module.html} + {Phonon Module} page this way. - For example: + \code + / *! + \page phonon-module.html + \module Phonon + \title Phonon Module + \ingroup modules - \code - / *! - \page console-edition-classes.html - \title Qt Console Edition Classes + \brief The Phonon module contains namespaces and classes for multimedia functionality. - \generatelist{classesbyedition Console} - * / - \endcode + \generatelist{classesbymodule Phonon} - Together, these arguments provide a table containing the - classes considered members of the specified edition, - accompanied with a brief description. Each class name is - a link to the class's reference documentation. + ... - The edition a given class can be found in is determined by - the module it belongs to. + * / + \endcode - \section2 \c compatclasses + Each class that is a member of the specified module must be + marked with the \l {inmodule-command} {\\inmodule} command in + its \\class comment. - The \c compatclasses argument provides a complete and - alphabetical list of the support classes. A support - class is identified within the documentation by the \l - {compat-command} {\\compat} command. Each class name is - a link to the class's reference documentation. The list - is rendered similarily to the list generated by the \l - {list example} {\c classes} argument. + \section2 \c compatclasses - \warning The \c classesbymodule argument will at some - point replace the this argument. + The \c compatclasses argument generates a list in alphabetical + order of the support classes. It is normally used only to + generate the \l {compatclasses.html} {Qt3 Support Classes} page + this way: - \section2 \c functionindex + \code + / *! + \page compatclasses.html + \title Qt3 Support Classes + \ingroup classlists - The \c functionindex argument provides a complete - alphabetical list of all the documented member - functions. + \brief These classes ease the porting of code from Qt 3 to Qt 4. - For example: + These are the classes that Qt provides for compatibility with Qt + 3. Most of these are provided by the Qt3Support module. - \quotation - \raw HTML -

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 

+ \generatelist compatclasses + * / + \endcode -

DTDHandler: QXmlReader

+ A support class is identified in the \\class comment with the \l + {compat-command} {\\compat} command. -

QAXCLASS: global

+ \section2 \c functionindex -

QAXFACTORY_BEGIN: global

+ The \c functionindex argument provides a complete alphabetical + list of all the documented member functions. It is normally used + only to generate the \l {functions.html} {Qt function index} + page this way: -

QAXFACTORY_DEFAULT: global

+ \code + / *! + \page functions.html + \title All Functions + \ingroup funclists -

QAXFACTORY_END: global

+ \brief All documented Qt functions listed alphabetically with a + link to where each one is declared. - \endraw + This is the list of all documented member functions and global + functions in the Qt API. Each function has a link to the class or + header file where it is declared and documented. - ... - \endquotation + \generatelist functionindex + * / + \endcode \section2 \c legalese -- cgit v0.12