From 66aba9ad196c24d6844e39901bf152d0951ccfb7 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Thu, 24 Feb 2011 11:48:25 +0100 Subject: qdoc: More updating command descriptions. --- tools/qdoc3/doc/qdoc-manual.qdoc | 256 ++++++++++++++++++--------------------- 1 file changed, 117 insertions(+), 139 deletions(-) diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc index 7a08916..a214b9c 100644 --- a/tools/qdoc3/doc/qdoc-manual.qdoc +++ b/tools/qdoc3/doc/qdoc-manual.qdoc @@ -127,7 +127,7 @@ \endcode From this snippet, QDoc generates the now famous HTML page \l - {http://doc.trolltech.com/4.7/qobject.html} {QObject Class Reference}. + {http://doc.trolltech.com/4.7/qobject.html#details} {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 @@ -190,7 +190,6 @@ appearance and logical structure. \list - \o \l {04-qdoc-commands-textmarkup.html#backslash-command} {\\\\} \o \l {04-qdoc-commands-textmarkup.html#a-command} {\\a} \o \l {11-qdoc-commands-specialcontent.html#abstract-command} {\\abstract} \o \l {06-qdoc-commands-includecodeinline.html#badcode-command} {\\badcode} @@ -251,6 +250,7 @@ \o \l {04-qdoc-commands-textmarkup.html#underline-command} {\\underline} \o \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\unicode} \o \l {11-qdoc-commands-specialcontent.html#warning-command} {\\warning} + \o \l {04-qdoc-commands-textmarkup.html#backslash-command} {\\\\} \endlist */ @@ -5392,18 +5392,33 @@ 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. + but they are normally placed near the top of the comment, just + below the \l {Topic Commands} {topic} command. - \section1 Categories \list - \o \l {Document Navigation} - \o \l {Reporting Status} - \o \l {Thread Support} - \o \l {Relating Things} - \o \l {Grouping Things} - \o \l {Naming Things} + \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 {16-qdoc-commands-status.html#since-command}{\\since}, + \o \l {15-qdoc-commands-navigation.html#startpage-command}{\\startpage}, + \o \l {20-qdoc-commands-namingthings.html#subtitle-command}{\\subtitle} + \o \l {17-qdoc-commands-thread.html#threadsafe-command}{\\threadsafe}, + \o \l {20-qdoc-commands-namingthings.html#title-command}{\\title} \endlist + */ /*! @@ -5414,15 +5429,11 @@ \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 - at the top and bottom of the document. They also provide browser - and search engine support. + The navigation commands are for linking the pages of a document in + a meaningful sequence. Below is a sequence of QDoc comments that + shows a typical use of the navigation commands. - \section1 General Description - - The QDoc comments below show a typical way of using the navigation - commands. + \section1 Example \code / *! @@ -5493,8 +5504,7 @@ * / \endcode - The second page of this multipage document, "Getting Started", - QDoc renders this as: + QDoc renders the "Getting Started" page in \c{creatingdialogs.html}: \quotation \raw HTML @@ -5529,18 +5539,16 @@ \endraw \endquotation - in creatingdialogs.html. - - In addition, the \l {indexpage-command} {\\indexpage} and \l - {startpage-command} {\\startpage} commands specifies links to the page's - index page and start page. These links are used by browsers and - search engines. + The \l {indexpage-command} {\\indexpage} and \l + {startpage-command} {\\startpage} commands create links to the + page's index page and start page. These links can be used by + browsers and search engines. The index page is typically an alphabetical list of the document's titles and topics, while the start page is the page considered by the author to be the starting point of a multipage document. - The links are included in the generated HTML source code but has + The links are included in the generated HTML source code but have no visual effect on the documentation: \code @@ -5552,85 +5560,61 @@ \endcode - \target previouspage-command - \section1 \\previouspage - - The \\previouspage command links the current page - to the previous one in an ordered series of documents. + \section1 Commands - The command has two arguments, each enclosed by curly - braces: The first is the link target, i.e. the title of the - previous page, the second is the link text. If the page's - title is equivalent to the link text, the second argument - can be omitted. - - The command must stand alone on its own line. + \target previouspage-command + \section2 \\previouspage - In the end, the link is rendered at the top and bottom of - the current page. For an example, see the \l {General - Description} section. + The \\previouspage command links the current page to the previous + page in a sequence.a The command has two arguments, each enclosed + by curly braces: The first is the link target, i.e. the title of + the previous page, the second is the link text. If the page's + title is equivalent to the link text, the second argument can be + omitted. + The command must stand alone on its own line. \target nextpage-command - \section1 \\nextpage - - The \\nextpage command links the current - page to the next page in an ordered series of documents. - - The command follows the same syntax and argument convention - as the \l {previouspage-command} {\\previouspage} command. - - For an example, see the \l {General Description} section. + \section2 \\nextpage + The \\nextpage command links the current page to the next page in + a sequence. The command follows the same syntax and argument + convention as the \l {previouspage-command} {\\previouspage} + command. \target startpage-command - \section1 \\startpage - - The \\startpage command specifies the first document - in a collection of documents. - - The command must stand alone on its own line, and its - unique argument is the title of the first document. + \section2 \\startpage - QDoc will generate a link to the specified document which - is included in the HTML file but has no visual effect on - the documentation. The generated link type tells browsers - and search engines which document is considered by the - author to be the starting point of the collection. - - For an example, see the \l {General Description} section. + The \\startpage command specifies the first page of a sequence of + pages. The command must stand alone on its own line, and its + unique argument is the title of the first document. + QDoc will generate a link to the start page and include it in the + generated HTML file, but this has no visual effect on the + documentation. The generated link type tells browsers and search + engines which document is considered by the author to be the + starting point of the collection. \target contentspage-command - \section1 \\contentspage - - The \\contentspage command links the current - page to a contents page. - - The command follows the same syntax and argument convention - as the \l {previouspage-command} {\\previouspage} command. - - For an example, see the \l {General Description} section. + \section2 \\contentspage + The \\contentspage command links the current page to a table of + contents page. The command follows the same syntax and argument + convention as the \l {previouspage-command} {\\previouspage} + command. \target indexpage-command - \section1 \\indexpage - - The \\indexpage command specifies a document providing - an index for the current document. - - The command must stand alone on its own line, and its - unique argument is the title of the index document. - - QDoc will generate a link to the specified document which - is included in the HTML file but has no visual effect on - the documentation. The generated link type tells browsers - and search engines which document is considered by the - author to be the index page for the current document. - - For an example, see the \l {General Description} section. + \section2 \\indexpage + The \\indexpage command specifies an index page for the current + document. The command must stand alone on its own line, and its + unique argument is the title of the index document. + QDoc will generate a link to the index page and include it in the + generated HTML file, but this has no visual effect on the + documentation. The generated link type tells browsers and search + engines which document is considered by the author to be the + index page of the collection. */ /*! @@ -5942,14 +5926,10 @@ \title Thread Support - The thread support commands specify the level of support for - multithreaded programming of a class or function. - - \section1 General Description - - There are three levels of support for multithreaded programming of - a class or function: \c threadsafe, \c reentrant and \c - nonreentrant. + The thread support commands are for specifying the level of + support for multithreaded programming in a class or function. + There are three levels of support: \c threadsafe, \c reentrant and + \c nonreentrant. The default is \c nonreentrant which means that the associated class or function cannot be called by multiple threads. \c @@ -5962,15 +5942,14 @@ can be called simultaneously by multiple threads even when each invocation references shared data. - When a class is declared \c reentrant or \c threadsafe, using the - \l {reentrant-command} {\\reentrant} and \l {threadsafe-command} {\\threadsafe} - commands respectively, functions in the referenced class can be - declared \c nonreentrant, using the \l - {nonreentrant-command} {\\nonreentrant} command, excluding the functions - from the general view. + When a class is marked \l {reentrant-command} {\\reentrant} or \l + {threadsafe-command} {\\threadsafe}, functions in that class can + be marked \c nonreentrant using the \l {nonreentrant-command} + {\\nonreentrant} command. - For example: + \section1 Example + \target reentrant-example \code / *! \class QLocale @@ -6071,56 +6050,55 @@ For more information see the general documentation on \l {threads.html#reentrant} {reentrancy and thread-safety}. + \section1 Commands + \target threadsafe-command - \section1 \\threadsafe + \section2 \\threadsafe - The \\threadsafe command indicates that the - associated class or function can be called simultaneously by - multiple threads even when each invocation references - shared data. + The \\threadsafe command includes a line in the documentation to + indicate that the associated class or function is \e threadsafe + and can be called simultaneously by multiple threads, even when + separate invocations reference shared data. - The command must stand on its own line. + The command must stand on its own line. - The generated documentation resulting from using the - \\threadsafe command is similar to the result of using the - \l {reentrant-command} {\\reentrant} command. For an example, see - the \l {General Description} section. - - See also \l{reentrant-command} {\\reentrant} and - \l{nonreentrant-command} {\\nonreentrant}. + The documentation generated from this command will be similar to + the what is generated for the \l {reentrant-command} {\\reentrant} + command. See the example above in the \l {reentrant-example} + {introduction}. + See also \l{reentrant-command} {\\reentrant} and + \l{nonreentrant-command} {\\nonreentrant}. \target reentrant-command - \section1 \\reentrant - - The \\reentrant command indicates that the associated - class or function can be called simultaneously - by multiple threads, provided that each invocation of the - functions reference unique data. + \section2 \\reentrant - The command must stand on its own line. - - For an example, see the \l {General Description} section. + The \\reentrant command indicates that the associated class or + function can be called simultaneously by multiple threads, + provided that each invocation references its own data. See the \l + {reentrant-example} {example} above. - See also \l{nonreentrant-command} {\\nonreentrant} and - \l{threadsafe-command} {\\threadsafe}. + The command must stand on its own line. + See also \l{nonreentrant-command} {\\nonreentrant} and + \l{threadsafe-command} {\\threadsafe}. \target nonreentrant-command - \section1 \\nonreentrant - - The \\nonreentrant command indicates that the - associated class or function cannot be called by - multiple threads. - - The command must stand on its own line. + \section2 \\nonreentrant - For an example, see the \l {General Description} section. + The \\nonreentrant command indicates that the associated class or + function cannot be called by multiple threads. Nonreentrant is the + default case. - See also \l{reentrant-command} {\\reentrant} and - \l{threadsafe-command} {\\threadsafe}. + The command must stand on its own line. + When a class is marked \l {reentrant-command} {\\reentrant} or \l + {threadsafe-command} {\\threadsafe}, functions in that class can + be marked \c nonreentrant using this command in the \l{fn-command} + {\\fn} comment of the functions to be excluded. + See also \l{reentrant-command} {\\reentrant} and + \l{threadsafe-command} {\\threadsafe}. */ /*! -- cgit v0.12 From d3a878209faa4e18102f41aeb3e700d88c46572b Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Thu, 24 Feb 2011 12:38:49 +0100 Subject: qdoc: More updating command descriptions. --- tools/qdoc3/doc/qdoc-manual.qdoc | 218 +++++++++++++++++++-------------------- 1 file changed, 105 insertions(+), 113 deletions(-) diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc index 6b3014c..7fcd92f 100644 --- a/tools/qdoc3/doc/qdoc-manual.qdoc +++ b/tools/qdoc3/doc/qdoc-manual.qdoc @@ -6109,147 +6109,139 @@ \title Relating Things - The relation commands discribe how the documented object relates - to its context: Whether it is an overloaded function, a - reimplemented function or a global function related to a specified - class or header file. + The relating commands are for specifying how one documented + element relates to another documented element. e.g., This function + overloads of another function, or this function is a + reimplementation of another function, or this typedef is \e + related to some class or header file. - \target overload-command - \section1 \\overload - - The \\overload command indicates that the - function is a secondary overload of its name. + \section1 Commands - The command must stand on its own line. + \target overload-command + \section2 \\overload - For any overloaded function (except constructors), QDoc - expects one primary version of the function and all the - the overloads marked with the \bold{\\overload command}. - The primary version should be fully documented. Each - overload can have whatever extra documentation you want - to add for just that overload. + The \\overload command is for indicating that a function is a + secondary overload of its name. - From Qt 4.5, you can include the function name plus '()' - as a parameter to the \bold{\\overload} command, which - will include a standard \e{This function overloads...} - line of text with a link to the documentation for the - primary version of the function. + The command must stand on its own line. - For example: + For a function name that is overloaded (except constructors), QDoc + expects one primary version of the function, and all the others + marked with the \bold {\\overload command}. The primary version + should be fully documented. Each overload can have whatever extra + documentation you want to add for just that overloaded version. - \code - / *! - \overload addAction() + From Qt 4.5, you can include the function name plus '()' as a + parameter to the \bold{\\overload} command, which will include a + standard \e{This function overloads...} line of text with a link + to the documentation for the primary version of the function. - This convenience function creates a new action with an - \a icon and some \a text. The function adds the newly - created action to the menu's list of actions, and - returns it. + \code + / *! + \overload addAction() - \sa QWidget::addAction() - * / - QAction *QMenu::addAction(const QIcon &icon, const QString &text) - { - QAction *ret = new QAction(icon, text, this); - addAction(ret); - return ret; - } - \endcode + This convenience function creates a new action with an + \a icon and some \a text. The function adds the newly + created action to the menu's list of actions, and + returns it. - QDoc renders this as: + \sa QWidget::addAction() + * / + QAction *QMenu::addAction(const QIcon &icon, const QString &text) + { + QAction *ret = new QAction(icon, text, this); + addAction(ret); + return ret; + } + \endcode - \quotation - \raw HTML -

QAction - * QMenu::addAction ( const QIcon & icon, - const QString & text ) -

- \endraw + QDoc renders this as: - This function overloads \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction} {addAction()} + \quotation + \raw HTML +

QAction + * QMenu::addAction ( const QIcon & icon, + const QString & text ) +

+ \endraw - This convenience function creates a new action with an - \e icon and some \e text. The function adds the newly - created action to the menu's list of actions, and - returns it. + This function overloads \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction} {addAction()} - See also - \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction} - {QWidget::addAction}(). - \endquotation + This convenience function creates a new action with an + \e icon and some \e text. The function adds the newly + created action to the menu's list of actions, and + returns it. - If you don't include the function name with the - \bold{\\overlaod} command, then instead of the "This - function overloads..." line with the link to the - documentation for the primary version, you get the old - standard line: + See also + \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction} + {QWidget::addAction}(). + \endquotation - \quotation - This is an overloaded member function, provided for - convenience. - \endquotation. + If you don't include the function name with the \bold{\\overlaod} + command, then instead of the "This function overloads..." line + with the link to the documentation for the primary version, you + get the old standard line: + \quotation + This is an overloaded member function, provided for + convenience. + \endquotation. \target reimp-command - \section1 \\reimp + \section2 \\reimp - The \\reimp command indicates that the - referenced function is a reimplementation of a virtual function, - where the reimplementation has no effect on the interface. - - The command must stand on its own line. + The \\reimp command is for indicating that a function is a + reimplementation of a virtual function. - QDoc will omit the reimplemented function from the class - reference. For example: + The command must stand on its own line. - \code - / *! - \reimp - * / - void QToolButton::nextCheckState() - { - Q_D(QToolButton); - if (!d->defaultAction) - QAbstractButton::nextCheckState(); - else - d->defaultAction->trigger(); - } - \endcode + QDoc will omit the reimplemented function from the class + reference. For example: - will not be rendered at all; only a link to the inherited - QAbstractButton::nextCheckState() will appear in the - documentation. + \code + / *! + \reimp + * / + void QToolButton::nextCheckState() + { + Q_D(QToolButton); + if (!d->defaultAction) + QAbstractButton::nextCheckState(); + else + d->defaultAction->trigger(); + } + \endcode + This function will not be included in the documentation. Instead, + a link to the base function QAbstractButton::nextCheckState() will + appear in the documentation. \target relates-command - \section1 \\relates + \section2 \\relates - The \\relates command attaches the documentation of - a global function to that of a related class or header file. + The \\relates command is for including the documentation of a + global element to some class or header file. The argument is a + class name or header file. - The command's argument is a class name, an the command (and - its argument) must stand on its own line. - - \code - / *! - \relates QChar - - Reads a char from the stream \a in into char \a chr. - - \sa {Format of the QDataStream operators} - * / - QDataStream &operator>>(QDataStream &in, QChar &chr) - { - quint16 u; - in >> u; - chr.unicode() = ushort(u); - return in; - } - \endcode - - will be rendered with the QChar documentation. + \code + / *! + \relates QChar + Reads a char from the stream \a in into char \a chr. + \sa {Format of the QDataStream operators} + * / + QDataStream &operator>>(QDataStream &in, QChar &chr) + { + quint16 u; + in >> u; + chr.unicode() = ushort(u); + return in; + } + \endcode + + The documentation for this function will be included on the reference page + for class QChra. */ /*! @@ -7335,7 +7327,7 @@ Example: - This option has been replaced by the \l{syntaxhighlighing} option. + This option has been replaced by the \l{syntaxhighlighting} option. For compatibility, the \c -slow command-line option has been retained. This has the effect of enabling syntax highlighting. -- cgit v0.12 From a7bca792fd7c1ae7edf45a7aae67c7a3423d35e8 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Thu, 24 Feb 2011 12:55:14 +0100 Subject: qdoc: More updating command descriptions. --- tools/qdoc3/doc/qdoc-manual.qdoc | 256 +++++++++++++++++++-------------------- 1 file changed, 123 insertions(+), 133 deletions(-) diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc index 7fcd92f..0ada405 100644 --- a/tools/qdoc3/doc/qdoc-manual.qdoc +++ b/tools/qdoc3/doc/qdoc-manual.qdoc @@ -6257,108 +6257,105 @@ classes in the documentation, while the modules are elements of Qt's structure. + \section1 Commands + \target mainclass-command - \section1 \\mainclass + \section2 \\mainclass The \\mainclass command relates the documented class to a group called mainclasses. - The command must stand on its own line. - - For example: + The command must stand on its own line. - \code - / *! - \class QWidget qwidget.h - \brief The QWidget class is the base class of - all user interface objects. + \code + / *! + \class QWidget qwidget.h + \brief The QWidget class is the base class of + all user interface objects. - \mainclass + \mainclass - ... - * / - \endcode + ... + * / + \endcode - will ensure that the QWidget class is included in the \c - mainclasses group, which means, for example, that the class - will appear on the list created by calling the \l - {generatelist-command} {\\generatelist} command with the \c - mainclasses argument: + This will include the QWidget class in the \e mainclasses + group, which means, for example, that the class will appear on the + list created by calling the \l {generatelist-command} + {\\generatelist} command with the \c mainclasses argument: - \l http://qt.nokia.com/doc/4.0/mainclasses.html + \l http://qt.nokia.com/doc/4.0/mainclasses.html - See also \l {generatelist-command} {\\generatelist}. + \note The Qt documentation no longer includes the \e mainclasses + page. + See also \l {generatelist-command} {\\generatelist}. \target ingroup-command - \section1 \\ingroup + \section2 \\ingroup The \\ingroup command indicates that the given overview or documented class belongs to a certain group of related docmentation. - A class or overview may belong to many groups. + A class or overview may belong to many groups. - The \\ingroup command's argument is a group name, but note - that the command considers the rest of the line as part of - its argument. Make sure that the group name is followed by - a linebreak. For example: + The \\ingroup command's argument is a group name, but note + that the command considers the rest of the line as part of + its argument. Make sure that the group name is followed by + a linebreak. For example: - \code - / *! - \class QDir - \brief The QDir class provides access to directory - structures and their contents. + \code + / *! + \class QDir + \brief The QDir class provides access to directory + structures and their contents. - \ingroup io - ... - * / - \endcode + \ingroup io + ... + * / + \endcode - will ensure that the QDir class is included in the \c io - group, which means, for example, that QDir will appear on - the list created by calling the \l {group-command} {\\group} command - with the \c io argument. + This will include the QDir class in the \c io group, which means, + for example, that QDir will appear on the list created by calling + the \l {group-command} {\\group} command with the \c io argument. - Note that to list overviews that are related to a given - group, you must generate the list exlicitly by using the \l - {generatelist-command} {\\generatelist} command with the \c related - argument. + To list overviews that are related to a certain group, you must + generate the list explicitly using the \l {generatelist-command} + {\\generatelist} command with the \c related argument. - See also \l {group-command} {\\group}. + See also \l {group-command} {\\group}. \target inmodule-command - \section1 \\inmodule + \section2 \\inmodule - The \\inmodule command relates the documented class - to the module specified by the command's argument. + The \\inmodule command relates a class to the module specified by + the command's argument. - 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 needs to - be related to a module explicitly. + 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 must be related to a module + explicitly. - The command's argument is a module name, but note that the - command considers the rest of the line as part of its - argument. Make sure that the module name is followed by a - linebreak. For example: + The command's argument is a module name, but note that the command + considers the rest of the line as part of its argument. Make sure + that the module name is followed by a linebreak. For example: - \code - /*! - \class QDesignerTaskMenuExtension - \inmodule QtDesigner - * / - \endcode - - will ensure that the QDesignerTaskMenuExtension class is - included in the \c QtDesigner module, which means, for - example, that the class will appear on the list created by - calling the \l {generatelist-command} {\\generatelist} command with - the \c {{classesbymodule QtDesigner}} argument. + \code + /*! + \class QDesignerTaskMenuExtension + \inmodule QtDesigner + * / + \endcode - See also \l {module-command} {\\module} and \l - {generatelist-command} {\\generatelist}. + This ensures that the QDesignerTaskMenuExtension class is included + in the \c QtDesigner module, which means, for example, that the + class will appear on the list created by calling the \l + {generatelist-command} {\\generatelist} command with the \c + {{classesbymodule QtDesigner}} argument. + See also \l {module-command} {\\module} and \l + {generatelist-command} {\\generatelist}. */ /*! @@ -6369,90 +6366,83 @@ \title Naming Things - In general a title command considers everything that follows it - until the first line break as its argument. If the title needs to - be spanned over several lines, make sure to end each line (except - the last one) with a backslash. - - \target title-command - \section1 \\title - - The \\title command sets the title for a - documentation page, or allows you to override it. + In general, a title command considers everything that follows it + until the first line break as its argument. If the title is so + long it must span multiple lines, end each line (except the last + one) with a backslash. - For example: + \section1 Commands - \code - / *! - \page signalandslots.html + \target title-command + \section2 \\title - \title Signals & Slots + The \\title command sets the title for a documentation page, or + allows you to override it. - Signals and slots are used for communication between - objects. The signals and slots mechanism is a central - feature of Qt and probably the part that differs most - from the features provided by other frameworks. + \code + / *! + \page signalandslots.html - ... - * / - \endcode + \title Signals & Slots - QDoc renders this as: + Signals and slots are used for communication between + objects. The signals and slots mechanism is a central + feature of Qt and probably the part that differs most + from the features provided by other frameworks. - \quotation - \raw HTML -

Signal and Slots

- \endraw + ... + * / + \endcode - Signals and slots are used for communication between - objects. The signals and slots mechanism is a central - feature of Qt and probably the part that differs most - from the features provided by other frameworks. + QDoc renders this as: - ... - \endquotation - See also \l {subtitle-command} {\\subtitle}. + \quotation + \raw HTML +

Signal and Slots

+ \endraw + Signals and slots are used for communication between + objects. The signals and slots mechanism is a central + feature of Qt and probably the part that differs most + from the features provided by other frameworks. + ... + \endquotation + See also \l {subtitle-command} {\\subtitle}. \target subtitle-command - \section1 \\subtitle + \section2 \\subtitle - The \\subtitle command sets a subtitle for a - documentation page. - - For example: - - \code - / *! - \page qtopiacore-overview.html + The \\subtitle command sets a subtitle for a documentation page. - \title Qtopia Core - \subtitle Qt for Embedded Linux - - Qt/Embedded, the embedded Linux port of Qt, is a - complete and self-contained C++ GUI and platform - development tool for Linux-based embedded development. + \code + / *! + \page qtopiacore-overview.html - ... - * / - \endcode + \title Qtopia Core + \subtitle Qt for Embedded Linux - QDoc renders this as: + Qt/Embedded, the embedded Linux port of Qt, is a + complete and self-contained C++ GUI and platform + development tool for Linux-based embedded development. + ... + * / + \endcode - \quotation - \raw HTML -

Qtopia Core

-

Qt for Embedded Linux

- \endraw + QDoc renders this as: - Qt/Embedded, the embedded Linux port of Qt, is a - complete and self-contained C++ GUI and platform - development tool for Linux-based embedded development. + \quotation + \raw HTML +

Qtopia Core

+

Qt for Embedded Linux

+ \endraw - ... - \endquotation + Qt/Embedded, the embedded Linux port of Qt, is a + complete and self-contained C++ GUI and platform + development tool for Linux-based embedded development. + ... + \endquotation - See also \l {title-command} {\\title}. + See also \l {title-command} {\\title}. */ -- cgit v0.12 From 85c81120dcd3f17b9846d9a5e5fedd11b59c6270 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Thu, 24 Feb 2011 13:33:52 +0100 Subject: qdoc: More updating command descriptions. --- tools/qdoc3/doc/qdoc-manual.qdoc | 396 ++++++++++++++++++--------------------- 1 file changed, 186 insertions(+), 210 deletions(-) diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc index 0ada405..49163ab 100644 --- a/tools/qdoc3/doc/qdoc-manual.qdoc +++ b/tools/qdoc3/doc/qdoc-manual.qdoc @@ -5634,202 +5634,186 @@ \target preliminary-command \section1 \\preliminary - The \\preliminary command indicates that the - referenced function is under development. + The \\preliminary command is for indicating that a referenced + function is still under development. - The command must stand on its own line. + The command must stand on its own line. - The \\preliminary command expands to a notification in the - function documentation, and marks the function as - preliminary when it appears in lists. For example: + The \\preliminary command expands to a notification in the + function documentation, and marks the function as preliminary when + it appears in lists. For example: - \code - / *! - \preliminary - - Returns information about the joining properties of the - character (needed for certain languages such as - Arabic). - * / - QChar::Joining QChar::joining() const - { - return ::joining(*this); - } - \endcode + \code + / *! + \preliminary - QDoc renders this as: + Returns information about the joining properties of the + character (needed for certain languages such as + Arabic). + * / + QChar::Joining QChar::joining() const + { + return ::joining(*this); + } + \endcode - \quotation - \raw HTML -

- Joining - QChar::joining () const

- \endraw + QDoc renders this as: - \bold {This function is under development and - is subject to change.} + \quotation + \raw HTML +

+ Joining + QChar::joining () const

+ \endraw - Returns information about the joining properties of the - character (needed for certain languages such as - Arabic). - \endquotation + \bold {This function is under development and + subject to change.} - And the function's entry in QChar's list of functions will - be rendered as + Returns information about the joining properties of the + character (needed for certain languages such as + Arabic). + \endquotation - \quotation - \list - \o ... - \o Joining - \l {http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum} - {joining}() - const \c (preliminary) - \o ... - \endlist - \endquotation + And the function's entry in QChar's list of functions will be + rendered as: + \quotation + \list + \o ... + \o Joining + \l {http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum} + {joining}() + const \c (preliminary) + \o ... + \endlist + \endquotation \target obsolete-command \section1 \\obsolete - The \\obsolete command indicates that the referenced - function no longer should be used in new code; - there is no guarantee for how long it will remain in - the library. - - The command must stand on its own line. + The \\obsolete command is for indicating that a function is being + deprecated, and it should no longer be used in new code. There is + no guarantee for how long it will remain in the library. - When generating the reference documentation for a class, - QDoc will create and link to a separate page documenting - its obsolete functions. Usually an equivalent function is - provided as an alternative. - - For example: - - \code - / *! - \fn MyClass::MyObsoleteFunction - \obsolete - - Use MyNewFunction() instead. - * / - \endcode - - QDoc renders this as: + The command must stand on its own line. - \quotation - \raw HTML -

Obsolete Members for MyClass

- \endraw + When generating the reference documentation for a class, QDoc will + create and link to a separate page documenting its obsolete + functions. Usually an equivalent function is provided as an + alternative. - \bold {The following class members are obsolete.} They - are provided to keep old source code working. We - strongly advise against using them in new code. + \code + / *! + \fn MyClass::MyObsoleteFunction + \obsolete - ... + Use MyNewFunction() instead. + * / + \endcode - \list - \o void MyObsoleteFunction() \c (obsolete) - \o ... - \endlist + QDoc renders this in \c{myclass-obsolete.html} as: - \raw HTML -
-

Member Function Documentation

-

void MyObsoleteFunction ()

-

Use MyNewFunction() instead.

- \endraw + \quotation + \raw HTML +

Obsolete Members for MyClass

+ \endraw - ... - \endquotation + \bold {The following class members are obsolete.} They are + provided to keep old source code working. We strongly advise + against using them in new code. - in myclass-obsolete.html + ... + \list + \o void MyObsoleteFunction() \c (obsolete) + \o ... + \endlist + \raw HTML +
+

Member Function Documentation

+

void MyObsoleteFunction ()

+

Use MyNewFunction() instead.

+ \endraw + ... + \endquotation \target compat-command \section1 \\compat - The \\compat command indicates that the referenced class - or function is part of the support library provided to keep - old source code working. - - The command must stand on its own line. - - Usually an equivalent function or class is provided as an - alternative. + The \\compat command is for indicating that a class or function is + part of the support library provided to keep old source code + working. - If the command is used within the documentation of a class, - the command expands to a warning that the referenced class - is part of the support library. The warning is located on - top of the associated documentation. For example: - - \code - / *! - \class MyQt3SupportClass - \compat - * / - \endcode - - QDoc renders this as: - - \quotation - \bold {This class is part of the Qt 3 support - library.} It is provided to keep old source code - working. We strongly advise against using it in new - code. See the \l - {http://qt.nokia.com/doc/4.0/porting4.html} {Porting - Guide} for more information. - \endquotation + The command must stand on its own line. - on the top of the MyQt3SupportClass class reference. + Usually an equivalent function or class is provided as an + alternative. - If the command is used when documenting a function, QDoc - will create and link to a separate page documenting Qt 3 - support members when generating the reference documentation - for the associated class. For example: + If the command is used in the documentation of a class, the + command expands to a warning that the referenced class is part of + the support library. The warning is located at the top of the + documentation page. - \code - / *! - \fn MyClass::MyQt3SupportMemberFunction - \compat + \code + / *! + \class MyQt3SupportClass + \compat + * / + \endcode - Use MyNewFunction() instead. - * / - \endcode + QDoc renders this at the top of the MyQt3SupportClass class + reference page. - QDoc renders this as: + \quotation + \bold {This class is part of the Qt 3 support + library.} It is provided to keep old source code + working. We strongly advise against using it in new + code. See the \l + {http://qt.nokia.com/doc/4.0/porting4.html} {Porting + Guide} for more information. + \endquotation - \quotation - \raw HTML -

Qt 3 Support Members for MyClass

- \endraw + If the command is used when documenting a function, QDoc will + create and link to a separate page documenting Qt 3 support + members when generating the reference documentation for the + associated class. - \bold {The following class members are part of the Qt - 3 support layer.} They are provided to help you port - old code to Qt 4. We advise against using them in new - code. + \code + / *! + \fn MyClass::MyQt3SupportMemberFunction + \compat - ... + Use MyNewFunction() instead. + * / + \endcode - \list - \o void MyQt3SupportMemberFunction() - \o ... - \endlist + QDoc renders this in \c{myclass-qt3.html} as: - \raw HTML -
-

Member Function Documentation

-

void MyQt3SupportMemberFunction ()

-

Use MyNewFunction() instead.

- \endraw + \quotation + \raw HTML +

Qt 3 Support Members for MyClass

+ \endraw - ... - \endquotation + \bold {The following class members are part of the Qt 3 + support layer.} They are provided to help you port old code to + Qt 4. We advise against using them in new code. - in myclass-qt3.html + ... + \list + \o void MyQt3SupportMemberFunction() + \o ... + \endlist + \raw HTML +
+

Member Function Documentation

+

void MyQt3SupportMemberFunction ()

+

Use MyNewFunction() instead.

+ \endraw + ... + \endquotation \target internal-command \section1 \\internal @@ -5837,32 +5821,30 @@ The \\internal command indicates that the referenced function is not part of the public interface. - The command must stand on its own line. - - QDoc ignores the documentation as well as the documented - item, when generating the associated class reference - documenation. For example: + The command must stand on its own line. - \code - / *! - \internal + QDoc ignores the documentation as well as the documented item, + when generating the associated class reference documenation. - Tries to find the decimal separator. If it can't find - it and the thousand delimiter is != '.' it will try to - find a '.'; - * / - int QDoubleSpinBoxPrivate::findDelimiter - (const QString &str, int index) const - { - int dotindex = str.indexOf(delimiter, index); - if (dotindex == -1 && thousand != dot && delimiter != dot) - dotindex = str.indexOf(dot, index); - return dotindex; - } - \endcode + \code + / *! + \internal - in qspinbox.cpp, will not be rendered at all. + Tries to find the decimal separator. If it can't find + it and the thousand delimiter is != '.' it will try to + find a '.'; + * / + int QDoubleSpinBoxPrivate::findDelimiter + (const QString &str, int index) const + { + int dotindex = str.indexOf(delimiter, index); + if (dotindex == -1 && thousand != dot && delimiter != dot) + dotindex = str.indexOf(dot, index); + return dotindex; + } + \endcode + This function will not be included in the documentation. \target since-command \section1 \\since @@ -5870,52 +5852,46 @@ The \\since command tells in which minor release the associated functionality was added. - For example: - - \code - / *! - \since 4.1 - - Returns an icon for \a standardIcon. - - ... + \code + / *! + \since 4.1 - \sa standardIconImplementation(), standardPixmap() - * / - QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const - { - } - \endcode + Returns an icon for \a standardIcon. - QDoc renders this as: + ... - \quotation - \raw HTML -

QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const

- \endraw + \sa standardIconImplementation(), standardPixmap() + * / + QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const + { + } + \endcode - This function was introduced in Qt version 4.1 + QDoc renders this as: - Returns an icon for \a standardIcon. + \quotation + \raw HTML +

QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const

+ \endraw - ... + This function was introduced in Qt version 4.1 - See also \l - {QStyle::standardIconImplementation()} {standardIconImplementation()} - and \l {QStyle::standardPixmap()} {standardPixmap()}. - \endquotation + Returns an icon for \a standardIcon. - QDoc generates the "Qt" reference from the \l - {25-qdoc-configuration-derivedprojects.html#project} {\c - project} configuration variable. For that reason this - reference will change according to the current - documentation project. + ... - See also \l - {25-qdoc-configuration-derivedprojects.html#project} {\c - project}. + See also \l {QStyle::standardIconImplementation()} + {standardIconImplementation()} and \l + {QStyle::standardPixmap()} {standardPixmap()}. + \endquotation + QDoc generates the "Qt" reference from the \l + {25-qdoc-configuration-derivedprojects.html#project} {\c project} + configuration variable. For that reason this reference will change + according to the current documentation project. + See also \l {25-qdoc-configuration-derivedprojects.html#project} + {\c project}. */ /*! -- cgit v0.12 From f65e8376f14a189675c225cfb562df985babe544 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Thu, 24 Feb 2011 13:55:06 +0100 Subject: qdoc: More updating command descriptions. --- tools/qdoc3/doc/qdoc-manual.qdoc | 284 ++++++++++++++++----------------------- 1 file changed, 115 insertions(+), 169 deletions(-) diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc index 49163ab..faabe2c 100644 --- a/tools/qdoc3/doc/qdoc-manual.qdoc +++ b/tools/qdoc3/doc/qdoc-manual.qdoc @@ -274,7 +274,7 @@ is misspelled, so when you document a function you should mention each formal parameter by name in the function description, preceded by the \\a command. The parameter name is then rendered - in italics. For example: + in italics. \code / *! @@ -616,8 +616,6 @@ The \\bold command renders its argument in bold font. - For example: - \code / *! This is regular text; \bold {this text is @@ -737,8 +735,6 @@ The \\sub command renders its argument lower than the baseline of the regular text, using a smaller font. - For example: - \code / *! Definition (Range): Consider the sequence @@ -770,8 +766,6 @@ The \\sup command renders its argument higher than the baseline of the regular text, using a smaller font. - For example: - \code / *! The series @@ -800,8 +794,6 @@ The \\underline command renders its argument underlined. - For example: - \code / *! The \underline {F}ile menu gives the users the possibility @@ -829,7 +821,7 @@ QDoc commands always start with a backslash alone. To display an actual backslash in the text you need to type two of the kind. If you want to display two backslashes, you need to type four, and so - forth. For example: + forth. \code / *! @@ -926,7 +918,7 @@ example from \c part to \c section1, is not allowed. You can \e begin with either of the three: \c part, \c chapter or - \c section1. For example: + \c section1. \code @@ -1138,8 +1130,6 @@ {quotefromfile-command} {\\quotefromfile} or \l {quotefile-command} {\\quotefile} command. - For example: - \code / *! \code @@ -1195,7 +1185,7 @@ Like the \l {code-command} {\\code} command, this command begins its code snippet on a new line rendered in the code font and with - the standard indentation. For example: + the standard indentation. \code / *! @@ -1255,7 +1245,7 @@ Like the \l {code-command} {\\code} and \l {badcode-command} {\\badcode} commands, the \\newcode command renders its code on a new line in the documentation using a typewriter font and the - standard indentation. For example: + standard indentation. \code / *! @@ -1331,7 +1321,7 @@ The file's contents is rendered in a separate paragraph, using a typewriter font and the standard indentation. The code is shown - verbatim. For example: + verbatim. \code / *! @@ -1377,7 +1367,7 @@ {\\printuntil}, \l {skipline-command} {\\skipline}, \l {skipto-command} {\\skipto}, \l {skipuntil-command} {\\skipuntil}. This enables you to quote specific portions of a - file. For example: + file. \code / *! @@ -1453,7 +1443,7 @@ The line from the source file is rendered as a separate paragraph, using a typewriter font and the standard indentation. The code is - shown verbatim. For example: + shown verbatim. \code / *! @@ -1521,7 +1511,7 @@ \target substring If the substring argument is surrounded by slashes it is - interpreted as a \l {regular expression}. For example: + interpreted as a \l {regular expression}. \code / *! @@ -1582,7 +1572,7 @@ The lines from the source file are rendered in a separate paragraph, using a typewriter font and the standard - indentation. The code is shown verbatim. For example: + indentation. The code is shown verbatim. \code / *! @@ -1631,7 +1621,7 @@ The lines from the source file are rendered in a separate paragraph, using a typewriter font and the standard - indentation. The code is shown verbatim. For example: + indentation. The code is shown verbatim. \code / *! @@ -1685,7 +1675,7 @@ command also follows the same conventions for \l {substring} {argument} as the \l {printline-command} {\\printline} command, and it is used in conjunction with the \l {quotefromfile-command} - {\\quotefromfile} command. For example: + {\\quotefromfile} command. \code / *! @@ -1744,7 +1734,7 @@ The command also follows the same conventions for \l {substring} {argument} as the \l {printline-command} {\\printline} command, and it is used in conjunction with the \l {quotefromfile-command} - {\\quotefromfile} command. For example: + {\\quotefromfile} command. \code / *! @@ -1802,7 +1792,7 @@ The command also follows the same conventions for \l {substring} {argument} as the \l {printline-command} {\\printline} command, and it is used in conjunction with the \l {quotefromfile-command} - {\\quotefromfile} command. For example: + {\\quotefromfile} command. \code / *! @@ -1850,7 +1840,7 @@ The command is used in conjunction with the \l {quotefromfile-command} {\\quotefromfile} command, and should be stated on its own line. The dots are rendered on a new line, using - a typewriter font. For example: + a typewriter font. \code / *! @@ -1875,7 +1865,7 @@ (\l {Example File} {The complete example file...}) The default indentation is 4 spaces, but this can be adjusted - using the command's optional argument. For example: + using the command's optional argument. \code / *! @@ -1967,14 +1957,12 @@ \section1 \\l (link) The \\l link command is used to create a hyperlink to many - different kinds of targets. The command's general syntax is + different kinds of targets. The command's general syntax is: \code \l {link target} {link text} \endcode - For example: - \code / *! Read the \l {http://qt.nokia.com/doc/4.0/} @@ -2118,7 +2106,7 @@ \endlist The \\sa command supports the same kind of links as the \l - {l-command} {\\l} command. For example: + {l-command} {\\l} command. \code / *! @@ -2162,8 +2150,6 @@ required around the target name, but they may be required when the target name is used in a link cammand. See below. - For example: - \code / *! \target capturing parentheses @@ -2205,7 +2191,7 @@ The \\keyword command is like the \l {target-command} {\\target} command, but stronger. A keyword can be linked from anywhere using - a simple syntax. For example: + a simple syntax. Keywords must be unique over all the documents processed during the QDoc run. The command uses the rest of the line as its @@ -2289,8 +2275,6 @@ description with a line break. Curly brackets are required if the description argument spans multiple lines. - For example: - \code / *! Qt by Trolltech is a C++ toolkit for cross-platform GUI @@ -2396,7 +2380,7 @@ \endraw The command can also be used to insert an image inline with the - text. For example: + text. \code / *! @@ -2500,7 +2484,7 @@ \l {row-command} {\\row} command and consists of cells, which starts with a \l {o-command} {\\o} command. There is also a \l {header-command} {\\header} command which is a special kind of row - with a special formatting. For example: + with a special formatting. \code / *! @@ -2629,7 +2613,7 @@ cells. A cell is created with the \l {o-command} {\\o} command. A header cell's text is centered within the table cell and - rendered using a bold font. For example: + rendered using a bold font. \code / *! @@ -2681,7 +2665,7 @@ The background cell color of each row alternates between two shades of grey, making it easier to distinguish the rows from each - other. The cells' contents is left aligned. For example: + other. The cells' contents is left aligned. \code / *! @@ -2824,7 +2808,7 @@ \endlist The \\list command takes an optional argument providing - alternative appearances for the list items. For example: + alternative appearances for the list items. \code / *! @@ -2931,7 +2915,7 @@ {list-command} {\\list}. If the command is used within a table, you can in addition specify - how many rows or columns the item should span. For example: + how many rows or columns the item should span. \code / *! @@ -3177,7 +3161,7 @@ \endcode \warning The brief statement is used as the first paragraph of the - detailed description. Do not repeat the sentence. For example: + detailed description. Do not repeat the sentence. \code / *! @@ -3400,7 +3384,7 @@ \section1 \\warning The \\warning command prepends "Warning:" to the command's - argument, in bold font. For example: + argument, in bold font. \code / *! @@ -3741,7 +3725,7 @@ the condition specified by the command's argument is true. The command reads the rest of the line and parses it as an C++ #if - statement. For example: + statement. \code / *! @@ -3795,7 +3779,7 @@ The \\else command can only be used within \l {if-command} {\\if...\\endif} commands, but is useful when there is only two - alternatives. For example: + alternatives. \code / *! @@ -3906,7 +3890,7 @@ the enclosing \c{/}\c{*!} ... \c{*}\c{/} marks. To ensure that QDoc won't attempt to read the file as a stand-alone piece of documentation, we recommend that you use the \c .qdocinc - extension. For example: + extension. \code / *! @@ -3943,7 +3927,7 @@ The command accepts two arguments: The first argument (the following word) is equivalent to the HTML meta tag's \e name variable, and the second argument (the rest of the line) is - equivalent to the tag's \e contents variable. For example: + equivalent to the tag's \e contents variable. \code / *! @@ -4042,11 +4026,11 @@ currently the only supported format is HTML. The \\raw command is useful if you want some special HTML effects - in your documentation. For example: + in your documentation. \code / *! - Qt has some predefined QColor objects. For example: + Qt has some predefined QColor objects. \raw HTML