diff options
Diffstat (limited to 'tools/qdoc3/doc/qdoc-manual.qdoc')
| -rw-r--r-- | tools/qdoc3/doc/qdoc-manual.qdoc | 10279 |
1 files changed, 5003 insertions, 5276 deletions
diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc index 7290c0e..0e4055b 100644 --- a/tools/qdoc3/doc/qdoc-manual.qdoc +++ b/tools/qdoc3/doc/qdoc-manual.qdoc @@ -27,727 +27,924 @@ /*! \page index.html - \nextpage QDoc Manual + \nextpage Introduction to QDoc - \title QDoc Manual - Table of Contents + \title Table of Contents \list - \o \l{QDoc Manual} - \o \l{QDoc Commands} - \list - \o \l{Markup Commands} - \o \l{Text Formatting Commands} - \o \l{Document Structuring Commands} - \o \l{Verbatim Code Commands} - \o \l{Quoting External Code Commands} - \list - \o \l{Example File} - \endlist - \o \l{Linking Commands} - \o \l{Graphic Commands} - \o \l{Container Commands} - \o \l{Document Contents Commands} - \o \l{Miscellaneous Commands} - \list - \o \l{signalandslots.qdocinc} - \o \l{objectmodel.qdocinc} - \o \l{layoutmanagement.qdocinc} - \endlist - \o \l{Topical Commands} - \o \l{Contextual Commands} - \o \l{Navigation Commands} - \o \l{Status Commands} - \o \l{Thread Support Commands} - \o \l{Relating Commands} - \o \l{Grouping Commands} - \o \l{Title Commands} - \endlist - \o \l{QDoc Configuration} - \list - \o \l{General Configuration Variables} - \o \l{Creating Help Project Files} - \o \l{C++ Specific Configuration Variables} - \o \l{HTML Specific Configuration Variables} - \o \l{Supporting Derived Projects} - \o \l{QDoc Compatibility} - \o \l{qt.qdocconf} - \o \l{minimum.qdocconf} - \endlist - \o \l{QDoc Commands - Alphabetical List} + \o \l {Introduction to QDoc} + \o \l {Command Index} + \o \l {Topic Commands} + \o \l {Context Commands} + \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} + \endlist + \o \l{Markup Commands} + \list + \o \l {Text Markup} + \o \l {Document Structure} + \o \l {Including Code Inline} + \o \l {Including External Code} + \o \l {Creating Links} + \o \l {Including Images} + \o \l {Tables and Lists} + \o \l {Special Content} + \o \l {Miscellaneous} + \endlist + \o \l {The QDoc Configuration File} + \list + \o \l {Generic Configuration Variables} + \o \l {Creating Help Project Files} + \o \l {C++ Specific Configuration Variables} + \o \l {HTML Specific Configuration Variables} + \o \l {Supporting Derived Projects} + \o \l {Compatibility Issues} + \o \l {qt.qdocconf} + \o \l {minimum.qdocconf} + \endlist \endlist + */ /*! \page 01-qdoc-manual.html - \contentspage QDoc Manual - Table of Contents - \previouspage QDoc Manual - Table of Contents - \nextpage QDoc Commands - - \title QDoc Manual - - QDoc is the internal tool used by Qt Development Frameworks for generating - documentation. This document is a reference for QDoc command syntax and - configuration. + \contentspage Table of Contents + \previouspage Table of Contents + \nextpage Command Index + + \title Introduction to QDoc + + QDoc is a tool used by Qt Developers to generate documentation for + software projects. It works by extracting \e {qdoc comments} from + project source files and then formatting these comments as HTML + pages or DITA XML documents, etc. QDoc finds qdoc comments in \c + {.cpp} files and in \c {.qdoc} files. QDoc does not look for qdoc + comments in \c {.h} files. A qdoc comment always begins with an + exclamation mark \bold{!} e.g.: + + \code + / *! + \class QObject + \brief The QObject class is the base class of all Qt objects. + + \ingroup objectmodel + + \reentrant + + QObject is the heart of the Qt \l{Object Model}. The + central feature in this model is a very powerful mechanism + for seamless object communication called \l{signals and + slots}. You can connect a signal to a slot with connect() + and destroy the connection with disconnect(). To avoid + never ending notification loops you can temporarily block + signals with blockSignals(). The protected functions + connectNotify() and disconnectNotify() make it possible to + track connections. + + QObjects organize themselves in \l {Object Trees & + Ownership} {object trees}. When you create a QObject with + another object as parent, the object will automatically + add itself to the parent's children() list. The parent + takes ownership of the object; i.e., it will automatically + delete its children in its destructor. You can look for an + object by name and optionally type using findChild() or + findChildren(). + + Every object has an objectName() and its class name can be + found via the corresponding metaObject() (see + QMetaObject::className()). You can determine whether the + object's class inherits another class in the QObject + inheritance hierarchy by using the inherits() function. + + .... + * / + \endcode - \section1 Overview + From the qdoc comment above, QDoc generates the now famous HTML + page \l {http://doc.trolltech.com/4.7/qobject.html#details} + {QObject Class Reference}. + + This manual explains how to use the QDoc commands in qdoc comments + to embed good documentation in your source files. It also explains + how to make a \l {The QDoc Configuration File} {QDoc configuration + file}, which you will pass to QDoc on the command line. - \list I - \o \section2 \l {QDoc Commands} + \section1 Running QDoc - \l {QDoc Commands - Alphabetical List}{A complete alphabetical - list}. + The current name of the QDoc program is \c {qdoc3}. To run qdoc3 + from the command line, give it the name of a configuration file: - There are two main categories of commands for QDoc: markup - commands and meta-commands. + \quotation + \c {$ ../../bin/qdoc3 ./config.qdocconf} + \endquotation - The markup commands indicate the generated documentation's - appearance and logical structure. The meta-commands provide - information about the document as well as the documented - item. The meta-commands can be further categorized as topical - commands and contextual commands. + QDoc recognizes the \c {.qdocconf} suffix as a \l{The QDoc + Configuration File} {QDoc configuration file}. The configuration + file is where you tell QDoc where to find the project source + files, header files, and \c {.qdoc} files. It is also where you + tell QDoc what kind of output to generate (HTML, DITA XML,...), + and where to put the generated documentation. The configuration + file also contains other information for QDoc. + + See \l{The QDoc Configuration File} for a instructions on how to + build a Qdoc configuration file. + + \section1 How QDoc Works + + QDoc begins by reading the configuarion file you specified on the + command line. It stores all the variables from the configuration + file for later use. One of the first variables it uses is \c + {outputformats}. This variable tells QDoc which output generators + it will run. The default value is \e {HTML}, so if you don't set + \c {outputformats} in your configuration file, QDoc will generate + HTML output. That's usually what you will want anyway, but you can + also specify \e {DITAXML} to get DITA XML output instead. + + Next, QDoc uses the values of the \l + {22-qdoc-configuration-generalvariables.html#headerdirs-variable} + {headerdirs} variable and/or the \l + {22-qdoc-configuration-generalvariables.html#headers-variable} + {headers} variable to find and parse all the header files for your + project. QDoc does \e not scan header files for qdoc comments. It + parses the header files to build a master tree of all the items + that should be documented (i.e. the items that QDoc should find + qdoc comments for). + + After parsing all the header files and building the master tree of + items to be documented, QDoc uses the value of the \l + {22-qdoc-configuration-generalvariables.html#sourcedirs-variable} + {sourcedirs} variable and/or the value of the \l + {22-qdoc-configuration-generalvariables.html#sources-variable} + {sources} variable to find and parse all the \c {.cpp} and \c + {.qdoc} files for your project. These are the files QDoc scans for + \e {qdoc comments}. Remember that a qdoc comment begins with + an exclamation mark, i.e. \bold {/*!} . + + For each qdoc comment it finds, it searches the master tree for + the item where the documentation belongs. The it interprets the + qdoc commands in the comment and stores the interpreted commands + and the comment text in the tree node for the item. + + Finally, QDoc traverses the master tree. For each node, if the + node has stored documentation, QDoc calls the output generator + specified by the \c {outputformats} variable to format and write + the documentation in the directory specified in the configuration + file in the \l + {22-qdoc-configuration-generalvariables.html#outputdir-variable} + {outputdir} variable. + + \section1 Command Types + + QDoc interprets three types of commands: - \list - \o \l {Markup Commands} - \list - \o \l {Text Formatting Commands}{Text Formatting} - \o \l {Document Structuring Commands}{Document Structuring} - \o \l {Verbatim Code Commands}{Verbatim Code} - \o \l {Quoting External Code Commands}{Quoting External Code} - \o \l {Linking Commands}{Linking} - \o \l {Graphic Commands}{Graphic} - \o \l {Container Commands}{Container} - \o \l {Document Contents Commands}{Document Contents} - \o \l {Miscellaneous Commands}{Miscellaneous} - \endlist - \o \l {Topical Commands} - \o \l {Contextual Commands} - \list - \o \l {Navigation Commands}{Navigation} - \o \l {Status Commands}{Status} - \o \l {Thread Support Commands}{Thread Support} - \o \l {Relating Commands}{Relating} - \o \l {Grouping Commands}{Grouping} - \o \l {Title Commands}{Title} - \endlist - \endlist + \list + \o \l {Topic Commands} + \o \l {Context Commands} + \o \l {Markup Commands} \endlist - \list II - \o \section2 \l {QDoc Configuration} - - When running QDoc to generate the documentation, you must - specify a configuration file on the command line. The - configuration file is a list of entries of entries of the form - "variable = value". - - \list - \o \l {Configuration Variables} - \o \l {Configuration File Examples} - \endlist - - Some particular configuration variables allow you to use QDoc - to support Qt-based projects; i.e to make projects, such as Qt - Solutions, contain references to the online Qt documentation. - - \list - \o \l {Supporting Derived Projects} - \endlist - - QDoc is a tool that constantly evolves to suit our needs, for - that reason there are some compatibility issues between old and - new practices. - - \list - \o \l {QDoc Compatibility} - \endlist - \endlist + Topic commands identify the elememt you are documenting, e.g. a C++ + class, function, or type, an example, or an extra page of text + that doesn't map to an underlying C++ elememnt. + + Context commands tell QDoc how the element being documented + relates to other documented elememnts, e.g. next and previous page + links or inclusion in page groups or library modules. Context + commands can also provide information about the documented element + that QDoc can't get from the source files, e.g. whether the + element is thread-safe, an overloaded or reimplemented function, + or that it has been deprecated. + + Markup commands tell QDoc how text and image elements in the + document should be rendered, or about the document's outline + structure. */ /*! - \page 02-qdoc-commands.html - \previouspage QDoc Manual - \contentspage QDoc Manual - Table of Contents - \nextpage Markup Commands - - \title QDoc Commands + \page 03-qdoc-commands-markup.html + \contentspage Table of Contents + \previouspage Naming Things + \nextpage Text Markup - There are two main categories of commands for QDoc: markup - commands and meta-commands. + \title Markup Commands The markup commands indicate the generated documentation's visual - appearance and logical structure. The meta-commands provide - information about the documentation unit as well as the documented - item. The meta-commands can be further categorized as topical - commands and contextual commands. - - \section1 Alphabetical List - - A complete \l{QDoc Commands - Alphabetical List } - {alphabetical list of the QDoc commands}. - - \section1 Categories + appearance and logical structure. \list - \o \l {Markup Commands} - \o \l {Topical Commands} - \o \l {Contextual Commands} + \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} + \o \l {04-qdoc-commands-textmarkup.html#bold-command} {\\bold} + \o \l {11-qdoc-commands-specialcontent.html#brief-command} {\\brief} + \o \l {04-qdoc-commands-textmarkup.html#c-command} {\\c} + \o \l {09-qdoc-commands-includingimages.html#caption-command} {\\caption} + \o \l {05-qdoc-commands-documentstructure.html#chapter-command} {\\chapter} + \o \l {06-qdoc-commands-includecodeinline.html#code-command} {\\code} + \o \l {07-0-qdoc-commands-includingexternalcode.html#codeline-command} {\\codeline} + \o \l {04-qdoc-commands-textmarkup.html#div-command} {\\div} \span {class="newStuff"} {(new)} + \o \l {07-0-qdoc-commands-includingexternalcode.html#dots-command} {\\dots} + \o \l {12-0-qdoc-commands-miscellaneous.html#else-command} {\\else} + \o \l {12-0-qdoc-commands-miscellaneous.html#endif-command} {\\endif} + \o \l {12-0-qdoc-commands-miscellaneous.html#expire-command} {\\expire} + \o \l {11-qdoc-commands-specialcontent.html#footnote-command} {\\footnote} + \o \l {12-0-qdoc-commands-miscellaneous.html#generatelist-command} {\\generatelist} + \o \l {10-qdoc-commands-tablesandlists.html#header-command} {\\header} + \o \l {04-qdoc-commands-textmarkup.html#i-command} {\\i} + \o \l {12-0-qdoc-commands-miscellaneous.html#if-command} {\\if} + \o \l {09-qdoc-commands-includingimages.html#image-command} {\\image} + \o \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\include} + \o \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\input} + \o \l {09-qdoc-commands-includingimages.html#inlineimage-command} {\\inlineimage} + \o \l {08-qdoc-commands-creatinglinks.html#keyword-command} {\\keyword} + \o \l {08-qdoc-commands-creatinglinks.html#l-command} {\\l} + \o \l {11-qdoc-commands-specialcontent.html#legalese-command} {\\legalese} + \o \l {10-qdoc-commands-tablesandlists.html#list-command} {\\list} + \o \l {12-0-qdoc-commands-miscellaneous.html#meta-command} {\\meta} + \o \l {06-qdoc-commands-includecodeinline.html#newcode-command} {\\newcode} + \o \l {10-qdoc-commands-tablesandlists.html#o-command} {\\o} + \o \l {06-qdoc-commands-includecodeinline.html#oldcode-command} {\\oldcode} + \o \l {12-0-qdoc-commands-miscellaneous.html#omit-command} {\\omit} + \o \l {05-qdoc-commands-documentstructure.html#part-command} {\\part} + \o \l {07-0-qdoc-commands-includingexternalcode.html#printline-command} {\\printline} + \o \l {07-0-qdoc-commands-includingexternalcode.html#printto-command} {\\printto} + \o \l {07-0-qdoc-commands-includingexternalcode.html#printuntil-command} {\\printuntil} + \o \l {11-qdoc-commands-specialcontent.html#quotation-command} {\\quotation} + \o \l {07-0-qdoc-commands-includingexternalcode.html#quotefile-command} {\\quotefile} + \o \l {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} {\\quotefromfile} + \o \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\raw} \span {class="newStuff"} {(deprecated)} + \o \l {10-qdoc-commands-tablesandlists.html#row-command} {\\row} + \o \l {08-qdoc-commands-creatinglinks.html#sa-command} {\\sa} + \o \l {05-qdoc-commands-documentstructure.html#sectionOne-command} {\\section1} + \o \l {05-qdoc-commands-documentstructure.html#sectionTwo-command} {\\section2} + \o \l {05-qdoc-commands-documentstructure.html#sectionThree-command} {\\section3} + \o \l {05-qdoc-commands-documentstructure.html#sectionFour-command} {\\section4} + \o \l {07-0-qdoc-commands-includingexternalcode.html#skipline-command} {\\skipline} + \o \l {07-0-qdoc-commands-includingexternalcode.html#skipto-command} {\\skipto} + \o \l {07-0-qdoc-commands-includingexternalcode.html#skipuntil-command} {\\skipuntil} + \o \l {07-0-qdoc-commands-includingexternalcode.html#snippet-command} {\\snippet} + \o \l {04-qdoc-commands-textmarkup.html#span-command} {\\span} \span {class="newStuff"} {(new)} + \o \l {04-qdoc-commands-textmarkup.html#sub-command} {\\sub} + \o \l {04-qdoc-commands-textmarkup.html#sup-command} {\\sup} + \o \l {10-qdoc-commands-tablesandlists.html#table-command} {\\table} + \o \l {11-qdoc-commands-specialcontent.html#tableofcontents-command} {\\tableofcontents} + \o \l {08-qdoc-commands-creatinglinks.html#target-command} {\\target} + \o \l {04-qdoc-commands-textmarkup.html#tt-command} {\\tt} + \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 */ /*! - \page 03-qdoc-commands-markup.html - \contentspage QDoc Manual - Table of Contents - \previouspage QDoc Commands - \nextpage Text Formatting Commands + \page 04-qdoc-commands-textmarkup.html + \contentspage Table of Contents + \previouspage Markup Commands + \nextpage Document Structure - \title Markup Commands + \title Text Markup - The markup commands indicate the generated documentation's visual - appearance and logical structure. + The text formatting commands indicate how text is to be rendered. - \section1 Alphabetical List - - \l {04-qdoc-commands-textformatting.html#backslash}{\\\\}, - \l {04-qdoc-commands-textformatting.html#a}{\\a}, - \l {11-qdoc-commands-documentcontents.html#abstract}{\\abstract}, - \l {06-qdoc-commands-verbatimcode.html#badcode}{\\badcode}, - \l {04-qdoc-commands-textformatting.html#bold}{\\bold}, - \l {11-qdoc-commands-documentcontents.html#brief}{\\brief}, - \l {04-qdoc-commands-textformatting.html#c}{\\c}, - \l {09-qdoc-commands-graphic.html#caption}{\\caption}, - \l {05-qdoc-commands-documentstructuring.html#chapter}{\\chapter}, - \l {06-qdoc-commands-verbatimcode.html#code}{\\code}, - \l {07-0-qdoc-commands-quoting.html#codeline}{\\codeline}, - \l {07-0-qdoc-commands-quoting.html#dots}{\\dots}, - \l {12-0-qdoc-commands-miscellaneous.html#else}{\\else}, - \l {12-0-qdoc-commands-miscellaneous.html#endif}{\\endif}, - \l {12-0-qdoc-commands-miscellaneous.html#expire}{\\expire}, - \l {11-qdoc-commands-documentcontents.html#footnote}{\\footnote}, - \l {12-0-qdoc-commands-miscellaneous.html#generatelist}{\\generatelist}, - \l {10-qdoc-commands-container.html#header}{\\header}, - \l {04-qdoc-commands-textformatting.html#i}{\\i}, - \l {12-0-qdoc-commands-miscellaneous.html#if}{\\if}, - \l {09-qdoc-commands-graphic.html#image}{\\image}, - \l {12-0-qdoc-commands-miscellaneous.html#include}{\\include}, - \l {09-qdoc-commands-graphic.html#inlineimage}{\\inlineimage}, - \l {08-qdoc-commands-linking.html#keyword}{\\keyword}, - \l {08-qdoc-commands-linking.html#l}{\\l}, - \l {11-qdoc-commands-documentcontents.html#legalese}{\\legalese}, - \l {10-qdoc-commands-container.html#list}{\\list}, - \l {12-0-qdoc-commands-miscellaneous.html#meta}{\\meta}, - \l {06-qdoc-commands-verbatimcode.html#newcode}{\\newcode}, - \l {10-qdoc-commands-container.html#o}{\\o}, - \l {06-qdoc-commands-verbatimcode.html#oldcode}{\\oldcode}, - \l {12-0-qdoc-commands-miscellaneous.html#omit}{\\omit}, - \l {05-qdoc-commands-documentstructuring.html#part}{\\part}, - \l {07-0-qdoc-commands-quoting.html#printline}{\\printline}, - \l {07-0-qdoc-commands-quoting.html#printto}{\\printto}, - \l {07-0-qdoc-commands-quoting.html#printuntil}{\\printuntil}, - \l {11-qdoc-commands-documentcontents.html#quotation}{\\quotation}, - \l {07-0-qdoc-commands-quoting.html#quotefile}{\\quotefile}, - \l {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile}, - \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\raw}, - \l {10-qdoc-commands-container.html#row}{\\row}, - \l {08-qdoc-commands-linking.html#sa}{\\sa}, - \l {05-qdoc-commands-documentstructuring.html#sectionOne}{\\section1}, - \l {05-qdoc-commands-documentstructuring.html#sectionTwo}{\\section2}, - \l {05-qdoc-commands-documentstructuring.html#sectionThree}{\\section3}, - \l {05-qdoc-commands-documentstructuring.html#sectionFour}{\\section4}, - \l {07-0-qdoc-commands-quoting.html#skipline}{\\skipline}, - \l {07-0-qdoc-commands-quoting.html#skipto}{\\skipto}, - \l {07-0-qdoc-commands-quoting.html#skipuntil}{\\skipuntil}, - \l {07-0-qdoc-commands-quoting.html#snippet}{\\snippet}, - \l {04-qdoc-commands-textformatting.html#sub}{\\sub}, - \l {04-qdoc-commands-textformatting.html#sup}{\\sup}, - \l {10-qdoc-commands-container.html#table}{\\table}, - \l {11-qdoc-commands-documentcontents.html#tableofcontents} - {\\tableofcontents}, - \l {08-qdoc-commands-linking.html#target}{\\target}, - \l {04-qdoc-commands-textformatting.html#tt}{\\tt}, - \l {04-qdoc-commands-textformatting.html#underline}{\\underline}, - \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\unicode}, - \l {11-qdoc-commands-documentcontents.html#warning}{\\warning} + \target a-command + \section1 \\a (parameter marker) - \section1 Categories - \list - \o \l {Text Formatting Commands} - \o \l {Document Structuring Commands} - \o \l {Verbatim Code Commands} - \o \l {Quoting External Code Commands} - \o \l {Linking Commands} - \o \l {Graphic Commands} - \o \l {Container Commands} - \o \l {Document Contents Commands} - \o \l {Miscellaneous Commands} - \endlist + The \\a command tells QDoc the next word is a formal parameter name. -*/ + A warning is emitted when a formal parameter is not documented or + 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. -/*! - \page 04-qdoc-commands-textformatting.html - \contentspage QDoc Manual - Table of Contents - \previouspage Markup Commands - \nextpage Document Structuring Commands + \code + / *! + Constructs a line edit containing the text + \a contents. The \a parent parameter is sent + to the QWidget constructor. + * / - \title Text Formatting Commands + QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent) + { + ... + } - The text formatting commands indicate how the regular text in the - documentation is rendered. + \endcode - \section1 Alphabetical List + QDoc renders this as: - \l {04-qdoc-commands-textformatting.html#backslash}{\\\\}, - \l {04-qdoc-commands-textformatting.html#a}{\\a}, - \l {04-qdoc-commands-textformatting.html#bold}{\\bold}, - \l {04-qdoc-commands-textformatting.html#c}{\\c}, - \l {04-qdoc-commands-textformatting.html#i}{\\i}, - \l {04-qdoc-commands-textformatting.html#sub}{\\sub}, - \l {04-qdoc-commands-textformatting.html#sup}{\\sup}, - \l {04-qdoc-commands-textformatting.html#tt}{\\tt}, - \l {04-qdoc-commands-textformatting.html#underline}{\\underline} + \quotation + \bold {QLineEdit::QLineEdit ( const QString & + contents, QWidget *parent )} - \section1 Command Descriptions + Constructs a line edit containing the text \a contents. + The \a parent parameter is sent to the QWidget constructor. + \endquotation - \table - \header - \o Command - \o Description + You can enclose the formal parameter name in curly brackets, if + you want to, but it isn't necessary. - \row + \target c-command + \section1 \\c (code font) + + The \\c command is used for rendering variable names, user-defined + class names, and C++ keywords (e.g. \c int and \c for) in the code + font. - \o \bold \\\\ \target backslash - \o \bold {The \\\\ command expands to a single backslash.} + The command renders its argument using a typewriter font. For + example: - 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: + \code + / *! + The \c AnalogClock class provides a clock widget with hour + and minute hands that is automatically updated every + few seconds. + * / + \endcode - \code - / *! - The \\\\ command is useful if you want a - backslash to appear verbatim, for example, - writing C:\\windows\\home\\. - * / - \endcode + QDoc renders this as: - will be rendered as + \quotation + The \c AnalogClock class provides a clock widget with hour + and minute hands that is automatically updated every + few seconds. + \endquotation - \quotation - The \\\\ command is useful if you want a - backslash to appear verbatim, for example, - writing C:\\windows\\home\\. - \endquotation + If the text to be rendered in the code font contains spaces, enclose the + entire text in curly brackets. - However, if you want your text to appear in a typewriter - font as well, you can use the \l {c}{\\c} command instead, - which accepts and renders the backslash as any other - character. For example: + \code + \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} + \endcode - \code - / *! - The \\c command is useful if you want a - backslash to appear verbatim, and the word - that contains it written in a typewriter font, - like this: \c {C:\windows\home\}. - * / - \endcode + QDoc renders this as: - will be rendered as + \quotation + \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} + \endquotation - \quotation - The \\c command is useful if you want a - backslash to appear verbatim, and the word - that contains it written in a typewriter font, - like this: \c {C:\windows\home\}. - \endquotation + The \\c command accepts the special character \c \ within its + argument, i.e. it renders it as a normal character. So if you want + to use nested commands, you must use the \l {tt-command} {teletype + (\\tt)} command instead. - \row - \o \bold \\a \target a - \o \bold {The \\a command indicates that the next word - is a parameter when documenting functions.} + See also \l {tt-command} {\\tt} and \l {code-command} {\\code}. + + \target div-command + \section1 \\div \span {class="newStuff"} {(new)} + + The \\div and \\enddiv commands delimit a large or small block of + text (which may include other QDoc commands) to which special + formatting attributes should be applied. - Warnings are emitted when function parameters are - undocumented or misspelled, so whenever you write - documentation for functions you should make sure you - mention all the parameters and precede each of these by the - \\a command. The parameter is then rendered in italic. For - example: + An argument must be provided in curly braces, as in the qdoc + comment shown below. The argument is not interpreted but is used + as attribute(s) of the tag that is ultimately output by qdoc. - \code - / *! - Constructs a line edit containing the text - \a contents. + For example, we might want to render an inline image so that it + floats to the right of the current block of text: - The \a parent parameter is sent to the - QWidget constructor. - * / + \code + / *! + \div {class="float-right"} + \inlineimage qml-column.png + \enddiv - QLineEdit::QLineEdit(const QString &contents, QWidget *parent) - :QWidget(parent) - { - ... - } + * / + \endcode - \endcode + If qdoc is generating HTML, it will translate these commands to: - will be rendered as + \code + <div class="float-right"><p><img src="images/qml-column.png" /></p></div> + \endcode - \quotation - \bold {QLineEdit::QLineEdit ( const QString & - contents, QWidget *parent )} + For HTML, the attribute value \e {float-right} then will refer to + a clause in the style.css file. which in this case could be: - Constructs a line edit containing the text \a contents. + \code + div.float-right + { + float: right; margin-left: 2em + } + \endcode - The \a parent parameter is sent to the QWidget - constructor. + If qdoc is generating DITA XML, it will translate the commands to: - \endquotation + \code + <sectiondiv outputclass="float-right"> + <p> + <fig> + <image href="images/qml-column.png" placement="inline"/> + </fig> + </p> + </sectiondiv> + \endcode - The \\a command follows the same conventions as the \l - {i}{\\i} command for \l {argument}{punctuation, parentheses - and use of braces} for the argument. However, a parameter - is always a single word, so braces are rarely - necessary. And for the same reason, parentheses seldom - occur. + Your DITA XML publishing program must then recognize the \e + {outputclass} attribute value. - \row - \o \bold \\c \target c - \o \bold {The \\c command can be used to render variables, - user-defined classes and C++ keywords like \c int, - \c for, etc.} + \note The \bold {\\div} command can be nested. + + Below is an example taken from the index.qdoc file used to + generate index.html for Qt 4.7: - The command renders its argument using a typewriter font. For - example: + \code + \div {class="indexbox guide"} + \div {class="heading"} + Qt Developer Guide + \enddiv + \div {class="indexboxcont indexboxbar"} + \div {class="section indexIcon"} \emptyspan + \enddiv + \div {class="section"} + Qt is a cross-platform application and UI + framework. Using Qt, you can write web-enabled + applications once and deploy them across desktop, + mobile and embedded operating systems without + rewriting the source code. + \enddiv + \div {class="section sectionlist"} + \list + \o \l{Getting Started Guides} {Getting started} + \o \l{Installation} {Installation} + \o \l{how-to-learn-qt.html} {How to learn Qt} + \o \l{tutorials.html} {Tutorials} + \o \l{Qt Examples} {Examples} + \o \l{qt4-7-intro.html} {What's new in Qt 4.7} + \endlist + \enddiv + \enddiv + \enddiv + \endcode - \code - / *! - The \c AnalogClock class provides a clock widget with hour - and minute hands that is automatically updated every - few seconds. - * / - \endcode + When all the class attribute values are defined as they are in the + style.css file that is used for rendering the Qt 4.7 documentation, + the above example is rendered as: + + \div {class="indexbox guide"} + \div {class="heading"} + Qt Developer Guide + \enddiv + \div {class="indexboxcont indexboxbar"} + \div {class="section indexIcon"} \emptyspan + \enddiv + \div {class="section"} + Qt is a cross-platform application and UI + framework. Using Qt, you can write web-enabled + applications once and deploy them across desktop, + mobile and embedded operating systems without + rewriting the source code. + \enddiv + \div {class="section sectionlist"} + \list + \o \l{Getting Started Guides} {Getting started} + \o \l{Installation} {Installation} + \o \l{how-to-learn-qt.html} {How to learn Qt} + \o \l{tutorials.html} {Tutorials} + \o \l{Qt Examples} {Examples} + \o \l{qt4-7-intro.html} {What's new in Qt 4.7} + \endlist + \enddiv + \enddiv + \enddiv + + When generating DITA XML, qdoc outputs the nested \e {div} commands as: - will be rendered as + \code + <sectiondiv outputclass="indexbox guide"> + <sectiondiv outputclass="heading"> + <p>Qt Developer Guide</p> + </sectiondiv> + <sectiondiv outputclass="indexboxcont indexboxbar"> + <sectiondiv outputclass="section indexIcon"/> + <sectiondiv outputclass="section"> + <p>Qt is a cross-platform application and UI + framework. Using Qt, you can write + web-enabled applications once and deploy + them across desktop, mobile and embedded + operating systems without rewriting the + source code. + </p> + </sectiondiv> + <sectiondiv outputclass="section sectionlist"> + <ul> + <li> + <xref href="gettingstarted.xml#id-606ee7a8-219b-47b7-8f94-91bc8c76e54c">Getting started</xref> + </li> + <li> + <xref href="installation.xml#id-075c20e2-aa1e-4f88-a316-a46517e50443">Installation</xref> + </li> + <li> + <xref href="how-to-learn-qt.xml#id-49f509b5-52f9-4cd9-9921-74217b9a5182">How to learn Qt</xref> + </li> + <li> + <xref href="tutorials.xml#id-a737f955-a904-455f-b4aa-0dc69ed5a64f">Tutorials</xref> + </li> + <li> + <xref href="all-examples.xml#id-98d95159-d65b-4706-b08f-13d80080448d">Examples</xref> + </li> + <li> + <xref href="qt4-7-intro.xml#id-519ae0e3-4242-4c2a-b2be-e05d1e95f177">What's new in Qt 4.7</xref> + </li> + </ul> + </sectiondiv> + </sectiondiv> + </sectiondiv> + \endcode - \quotation - The \c AnalogClock class provides a clock widget with hour - and minute hands that is automatically updated every - few seconds. - \endquotation + Your DITA XML publishing program must recognize the values of the + \e {outputclass} attribute. + + See also \l {span-command} {\\span}. - The \\c command follows the same conventions as the \l - {i}{\\i} command for \l {argument}{punctuation, parentheses - and use of braces} for the argument. + \target span -command + \section1 \\span \span {class="newStuff"} {(new)} + + The \\span command is for applying special formatting + attributes to a small block of text. + + Two arguments must be provided, each argument in curly braces, as + shown in the qdoc comment below. The first argument is not + interpreted but is used as the formatting attribute(s) of the tag + that is ultimately output by qdoc. The second argument is the text + to be rendered with the special formatting attributes. + + For example, we might want to render the first word of each + element in a numeric list in blue. - The \\c command accepts the special character \c \ within - its argument, i.e. it renders it as a normal character. So - if you want to use nested commands, you must use the \l - {tt}{teletype (\\tt)} command instead. + \code + / *! + Global variables with complex types: + \list 1 + \o \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14 + \o \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15 + \o \span {class="variableName"} {constComplex1} in globals.cpp at line 16 + \o \span {class="variableName"} {constComplex2} in globals.cpp at line 17 + \endlist + * / + \endcode - See also \l {tt}{\\tt} and \l {code}{\\code}. + Class \e {variableName} refers to a clause in your style.css. - \row - \o \bold \\tt \target tt - \o \bold {The \\tt command can be used to render variables, - user-defined classes and C++ keywords like \c int, \c - for, etc.} + \code + .variableName + { + font-family: courier; + color: blue + } + \endcode - The \\tt command behaves just like the \l {c}{\\c} command, - except that \\tt parses QDoc commands (like \l {i}{\\i}, \l - {bold}{\\bold} and \l {underline}{\\underline}) contained - within its argument. + Using the \e {variableName} clause shown above, the example is rendered as: - The command renders its argument using a monospace - font. For example: + Global variables with complex types: + \list 1 + \o \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14 + \o \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15 + \o \span {class="variableName"} {constComplex1} in globals.cpp at line 16 + \o \span {class="variableName"} {constComplex2} in globals.cpp at line 17 + \endlist - \code - / *! - After \c setupUi() populates the main container with - child widgets it scans the main container's list of - slots for names with the form - \tt{on_\i{objectName}_\i{signalName}().} - * / - \endcode + \note The \bold span command does not cause a new paragraph to be + started. - will be rendered as + See also \l {div-command} {\\div}. + + \target tt-command + \section1 \\tt (teletype font) - \quotation - After \c setupUi() populates the main container with - child widgets it scans the main container's list of - slots for names with the form - \tt{on_\i{objectName}_\i{signalName}().} - \endquotation + The \\tt command renders its argument in a monospace font. This + command behaves just like the \l {c-command} {\\c} command, except + that \\tt allows you to nest QDoc commands within the argument + (e.g. \l {i-command} {\\i}, \l {bold-command} {\\bold} and \l + {underline-command} {\\underline}). - The \\tt command follows the same conventions as the \l - {i}{\\i} command for \l {argument}{punctuation, parentheses - and use of braces} for the argument. + \code + / *! + After \c setupUi() populates the main container with + child widgets it scans the main container's list of + slots for names with the form + \tt{on_\e{objectName}_\e{signalName}().} + * / + \endcode - See also \l {c}{\\c}. + QDoc renders this as: - \row - \o \bold \\bold \target bold - \o \bold {The \\bold command renders its argument using - a bold font.} + \quotation + After \c setupUi() populates the main container with + child widgets it scans the main container's list of + slots for names with the form + \tt{on_\e{objectName}_\e{signalName}().} + \endquotation - For example: + If the text to be rendered in the code font contains spaces, enclose the + entire text in curly brackets. - \code - / *! - This is regular text; \bold {this text is - rendered using the \\bold command}. - * / - \endcode + \code + \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} + \endcode - will be rendered as + QDoc renders this as: - \quotation - This is regular text; \bold {this text is rendered using - the \\bold command}. - \endquotation + \quotation + \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} + \endquotation - The command follows the same conventions as the \l {i}{\\i} - command for \l {argument}{punctuation, parentheses and use - of braces} for the argument. + See also \l {c-command} {\\c}. - \row - \o \bold \\i \target i - \o \bold {The \\i command renders its argument in italic.} + \target bold-command + \section1 \\bold - \warning This is preliminary functionality. For - more information, see the \l - {26-qdoc-commands-compatibility.html#i-versus-e}{compatibility} - section. + The \\bold command renders its argument in bold font. - \target argument - Normally, a command argument ends at the next whitespace [1], - but braces can be used to group words [2]. For example: + \code + / *! + This is regular text; \bold {this text is + rendered using the \\bold command}. + * / + \endcode - \code - / *! - Here, we render \i {a few words} in italic. - * / - \endcode + QDoc renders this as: - will be rendered as + \quotation + This is regular text; \bold {this text is rendered using + the \\bold command}. + \endquotation - \quotation - Here, we render \i {a few words} in italic. - \endquotation + \target i-command + \section1 \\i (italics) - If you want to use other QDoc commands within an argument - that contains spaces, you always need to enclose the - argument with braces. But QDoc is smart enough to count - parentheses [3], so you don't need braces in cases like this: + The \\i command renders its argument in italics. - \code - / *! - An argument can sometimes contain whitespaces, - for example: \i QPushButton(tr("A Brand New Button")) - * / - \endcode + \warning If \\i doesn't work and you get some strange error + meesages from qdoc3 about using \\o outside of tables and lists, + use \bold{\\e} for italics instead of \\i. For more information, + see the relevant explanation in the section on \l + {26-qdoc-commands-compatibility.html#i-versus-e} {compatibility + issues}. - will be rendered as + If the argument contains spaces or other punctuation, enclose the + argument in curly brackets. - \quotation - An argument can sometimes contain whitespaces, - for example: \i QPushButton(tr("A Brand New Button")) - \endquotation + \code + / *! + Here, we render \i {a few words} in italic. + * / + \endcode - Finally, trailing punctuation is not included in an - argument [4], nor is 's [5] + QDoc renders this as: - \raw HTML - <table align="center" cellpadding="2" - cellspacing="1" border="0"> - <tr valign="top" bgcolor="#a2c511"> - <th></th> - <th>QDoc Syntax</th> - <th>Generated Documentation</th> - </tr> + \quotation + Here, we render \e {a few words} in italic. + \endquotation - <tr valign="top" bgcolor="#d0d0d0"> - <td>1</td> - <td>A variation of a command button is a \i menu - button.</td> - <td>A variation of a command button is a <i>menu</i> - button.</td> - </tr> + If you want to use other QDoc commands within an argument that + contains spaces, you always need to enclose the argument with + braces. But QDoc is smart enough to count parentheses [3], so you + don't need braces in cases like this: - <tr valign="top" bgcolor="#c0c0c0"> - <td>2</td> - <td>The QPushButton widget provides a - \i {command button}.</td> - <td>The QPushButton widget provides a - <i>command button</i>.</td> - </tr> + \code + / *! + An argument can sometimes contain whitespaces, + for example: \i QPushButton(tr("A Brand New Button")) + * / + \endcode - <tr valign="top" bgcolor="#d0d0d0"> - <td>3</td> - <td>Another class of buttons are option buttons - \i (see QRadioButton).</td> - <td>Another class of buttons are option buttons - <i> (see QRadioButton)</i>.</td> - </tr> + QDoc renders this as: - <tr valign="top" bgcolor="#c0c0c0"> - <td>4</td> - <td>A push button emits the signal \i clicked().</td> - <td>A push button emits the signal <i>clicked</i>().</td> - </tr> + \quotation + An argument can sometimes contain whitespaces, + for example: \e QPushButton(tr("A Brand New Button")) + \endquotation - <tr valign="top" bgcolor="#d0d0d0"> - <td>5</td> - <td>The \i QPushButton's checked property is - false by default.</td> - <td>The <i>QPushButton</i>'s checked property is - false by default.</td> - </tr> + Finally, trailing punctuation is not included in an argument [4], + nor is 's [5] - </table> - \endraw + \raw HTML + <table align="center" cellpadding="2" + cellspacing="1" border="0"> + <tr valign="top" bgcolor="#a2c511"> + <th></th> + <th>QDoc Syntax</th> + <th>Generated Documentation</th> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td>1</td> + <td>A variation of a command button is a \e menu + button.</td> + <td>A variation of a command button is a <i>menu</i> + button.</td> + </tr> + + <tr valign="top" bgcolor="#c0c0c0"> + <td>2</td> + <td>The QPushButton widget provides a + \e {command button}.</td> + <td>The QPushButton widget provides a + <i>command button</i>.</td> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td>3</td> + <td>Another class of buttons are option buttons + \e (see QRadioButton).</td> + <td>Another class of buttons are option buttons + <i> (see QRadioButton)</i>.</td> + </tr> + + <tr valign="top" bgcolor="#c0c0c0"> + <td>4</td> + <td>A push button emits the signal \e clicked().</td> + <td>A push button emits the signal <i>clicked</i>().</td> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td>5</td> + <td>The \e QPushButton's checked property is + false by default.</td> + <td>The <i>QPushButton</i>'s checked property is + false by default.</td> + </tr> - \row - \o \bold \\sub \target sub - \o \bold {The \\sub command renders its argument lower - than the baseline of the regular text, using a smaller font.} + </table> + \endraw - For example: + \target sub-command + \section1 \\sub - \code - / *! - Definition (Range): Consider the sequence - {x\sub n}\sub {n > 1} . The set + The \\sub command renders its argument lower than the baseline of + the regular text, using a smaller font. - {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} + \code + / *! + Definition (Range): Consider the sequence + {x\sub n}\sub {n > 1} . The set - is called the range of the sequence. - * / - \endcode + {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} - will be rendered as + is called the range of the sequence. + * / + \endcode - \quotation - Definition (Range): Consider the sequence - {x\sub n}\sub {n > 1} . The set + QDoc renders this as: - {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} + \quotation + Definition (Range): Consider the sequence + {x\sub n}\sub {n > 1} . The set - is called the range of the sequence. - \endquotation + {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} - The \\sub command follows the same conventions as the \l - {i}{\\i} command for \l {argument}{punctuation, parentheses - and use of braces} for the argument. + is called the range of the sequence. + \endquotation - \row - \o \bold \\sup \target sup - \o \bold {The \\sup command renders its argument higher than - the baseline of the regular text, using a smaller font.} + If the argument contains spaces or other punctuation, enclose the + argument in curly brackets. - For example: + \target sup-command + \section1 \\sup - \code - / *! - The series + The \\sup command renders its argument higher than + the baseline of the regular text, using a smaller font. - 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... + \code + / *! + The series - is called the \i {geometric series}. - * / - \endcode + 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... - will be rendered as + is called the \i {geometric series}. + * / + \endcode - \quotation - The series + QDoc renders this as: - 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... + \quotation + The series - is called the \i {geometric series}. - \endquotation + 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... - The \\sup command follows the same conventions as the \l - {i}{\\i} command for \l {argument}{punctuation, parentheses - and use of braces} for the argument. + is called the \e {geometric series}. + \endquotation - \row - \o \bold \\underline \target underline - \o \bold {The \\underline command renders its argument underlined.} + If the argument contains spaces or other punctuation, enclose the + argument in curly brackets. - For example: + \target underline-command + \section1 \\underline - \code - / *! - The \underline {F}ile menu gives the users the possibility - to open, and edit, an existing file, save a new or modified - file, and exit the application. - * / - \endcode + The \\underline command renders its argument underlined. - will be rendered as + \code + / *! + The \underline {F}ile menu gives the users the possibility + to open, and edit, an existing file, save a new or modified + file, and exit the application. + * / + \endcode - \quotation - The \underline {F}ile menu gives the users the possibility - to open, and edit, an existing file, save a new or modified - file, and exit the application. - \endquotation + QDoc renders this as: - The \\underline command follows the same conventions as the - \l {i}{\\i} command for \l {argument}{punctuation, - parentheses and use of braces} for the argument. \endtable -*/ + \quotation + The \underline {F}ile menu gives the users the possibility + to open, and edit, an existing file, save a new or modified + file, and exit the application. + \endquotation -/*! - \page 05-qdoc-commands-documentstructuring.html - \previouspage Text Formatting Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Verbatim Code Commands + If the argument contains spaces or other punctuation, enclose the + argument in curly brackets. - \title Document Structuring Commands + \target backslash-command + \section1 \\\\ (double backslash) - The document structuring commands divide the documentation into - sections. In total, there are six levels of sections in QDoc: \c - \part, \c \chapter, \c \section1, \c \section2, \c \section3 and - \c \section4. \c \section1 to \c \section4 correspond to the - traditional section, subsection, subsubsection and - subsubsubsection. + The \\\\ command expands to a single backslash. - \section1 Alphabetical List + 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. - \l {05-qdoc-commands-documentstructuring.html#chapter}{\\chapter}, - \l {05-qdoc-commands-documentstructuring.html#part}{\\part}, - \l {05-qdoc-commands-documentstructuring.html#sectionOne}{\\section1}, - \l {05-qdoc-commands-documentstructuring.html#sectionTwo}{\\section2}, - \l {05-qdoc-commands-documentstructuring.html#sectionThree}{\\section3}, - \l {05-qdoc-commands-documentstructuring.html#sectionFour}{\\section4} + \code + / *! + The \\\\ command is useful if you want a + backslash to appear verbatim, for example, + writing C:\\windows\\home\\. + * / + \endcode - \section1 Command Descriptions + QDoc renders this as: - \table - \header - \o Command - \o Description + \quotation + The \\\\ command is useful if you want a + backslash to appear verbatim, for example, + writing C:\\windows\\home\\. + \endquotation - \row - \o \bold \\part \target part - \o \bold {The \\part command is intended for use in - larger documents, and divides the document into parts.} + However, if you want your text to appear in a typewriter font as + well, you can use the \l {c-command} {\\c} command instead, which + accepts and renders the backslash as any other character. For + example: + + \code + / *! + The \\c command is useful if you want a + backslash to appear verbatim, and the word + that contains it written in a typewriter font, + like this: \c {C:\windows\home\}. + * / + \endcode - In general a document structuring command considers - everything that follows it until the first line break as - its argument. The argument is rendered as the unit's - title. If the title needs to be spanned over several lines, - make sure that each line (except the last one) is ended - with a backslash. + QDoc renders this as: - In total, there are six levels of sections in QDoc: \c - \part, \c \chapter, \c \section1, \c \section2, \c - \section3 and \c \section4. \c \section1 to \c \section4 - correspond to the traditional section, subsection, - subsubsection and subsubsubsection. + \quotation + The \\c command is useful if you want a + backslash to appear verbatim, and the word + that contains it written in a typewriter font, + like this: \c {C:\windows\home\}. + \endquotation - There is a strict ordering of the section units: +*/ + +/*! + \page 05-qdoc-commands-documentstructure.html + \previouspage Text Markup + \contentspage Table of Contents + \nextpage Including Code Inline + + \title Document Structure + + The document structuring commands are for dividing your document + into sections. QDoc supports six kinds of sections: \c \part, \c + \chapter, \c \section1, \c \section2, \c \section3 and \c + \section4. The \c \section1..4 commands are the most useful. The + correspond to the traditional section, subsection, etc used in + outlining. + + \target part-command + \section1 \\part + + The \\part command is intended for use in a large document, like a + book. + + In general a document structuring command considers everything + that follows it until the first line break as its argument. The + argument is rendered as the unit's title. If the title needs to be + spanned over several lines, make sure that each line (except the + last one) is ended with a backslash. + + In total, there are six levels of sections in QDoc: \c \part, \c + \chapter, \c \section1, \c \section2, \c \section3 and \c + \section4. \c \section1 to \c \section4 correspond to the + traditional section, subsection, subsubsection and + subsubsubsection. + + There is a strict ordering of the section units: \code part @@ -763,13 +960,12 @@ section4 \endcode - For example, a \c section1 unit can only appear as the top - level section or inside a \c chapter unit. Skipping a - section unit, for example from \c part to \c section1, is - not allowed. + For example, a \c section1 unit can only appear as the top level + section or inside a \c chapter unit. Skipping a section unit, for + example from \c part to \c section1, is not allowed. - You can \i begin with either of the three: \c part, \c - chapter or \c section1. For example: + You can \e begin with either of the three: \c part, \c chapter or + \c section1. \code @@ -829,7 +1025,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation \raw HTML @@ -890,154 +1086,96 @@ \endraw \endquotation - Each section level is a logical unit within the - document. Its title will appear on the table of contents - generated by the \l - {11-qdoc-commands-documentcontents.html#tableofcontents} - {\\tableofcontents} command. For example: + Each section is a logical unit in the document. The section + heading appears in the automatically generated table of contents + that normally appears in the upper righthand corner of the page. - \code - / *! - Contents: + \target chapter-command + \section1 \\chapter + + The \\chapter command is intended for use in + larger documents, and divides the document into chapters. - \tableofcontents + See \l{part} {\\part} for an explanation of the various + section units, command argument and rendering. - ... - * / - \endcode + \target sectionOne-command + \section1 \\section1 - will expand to + The \\section1 command starts a new section. - \quotation - \raw HTML - <p>Contents:</p> - - <ul> - <li><a href="#Basic Qt">Basic Qt</a></li> - <ul> - <li><a href="#Getting Started">Getting Started</a></li> - <ul> - <li><a href="#Hello Qt">Hello Qt</a></li> - <li><a href="#Making Connections"> - Making Connections</a></li> - <li><a href="#Using the Reference Documentation"> - Using the Reference Documentation</a></li> - </ul> - <li><a href="#Creating Dialogs">Creating Dialogs</a></li> - <ul> - <li><a href="#Subclassing QDialog"> - Subclassing QDialog</a></li> - </ul> - </ul> - <li><a href="#Intermediate Qt">Intermediate Qt</a></li> - <ul> - <li><a href="#Layout Management"> - Layout Management</a></li> - <ul> - <li><a href="#Basic Layouts">Basic Layouts</a></li> - </ul> - </ul> - </ul> + See \l{part} {\\part} for an explanation of the various + section units, command argument and rendering. - ... - \endraw - \endquotation - - \row - \o \bold \\chapter \target chapter - \o \bold {The \\chapter command is intended for use in - larger documents, and divides the document into chapters.} + \target sectionTwo-command + \section1 \\section2 - See \l{part}{\\part} for an explanation of the various - section units, command argument and rendering. + The \\section2 command starts a new section. - \row - \o \bold \\section1 \target sectionOne - \o \bold {The \\section1 command starts a new section.} + See \l{part} {\\part} for an explanation of the various + section units, command argument and rendering. - See \l{part}{\\part} for an explanation of the various - section units, command argument and rendering. - \row - \o \bold \\section2 \target sectionTwo - \o \bold {The \\section2 command starts a new section.} + \target sectionThree-command + \section1 \\section3 - See \l{part}{\\part} for an explanation of the various - section units, command argument and rendering. + The \\section3 command starts a new section. - \row - \o \bold \\section3 \target sectionThree - \o \bold {The \\section3 command starts a new section.} + See \l{part} {\\part} for an explanation of the various + section units, command argument and rendering. - See \l{part}{\\part} for an explanation of the various - section units, command argument and rendering. + \target sectionFour-command + \section1 \\section4 - \row - \o \bold \\section4 \target sectionFour - \o \bold {The \\section4 command starts a new section.} + The \\section4 command starts a new section. - See \l{part}{\\part} for an explanation of the various - section units, command argument and rendering. + See \l{part} {\\part} for an explanation of the various + section units, command argument and rendering. - \endtable */ /*! - \page 06-qdoc-commands-verbatimcode.html - \previouspage Document Structuring Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Quoting External Code Commands - - \title Verbatim Code Commands - - The following commands are used to render verbatim code within the - documentation. The code is rendered on a new line, using a - typewriter font and the standard indentation. + \page 06-qdoc-commands-includecodeinline.html + \previouspage Document Structure + \contentspage Table of Contents + \nextpage Including External Code + + \title Including Code Inline + + The following commands are used to render source code without + formatting. The source code begins on a new line, rendered in the + code. + + \bold{Note:} Although all these commands are for rendering C++ + code, the + \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} + {\\snippet} and + \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} + {\\codeline} commands are preferred over the others. These + commands allow equivalent code snippets for other Qt language + bindings to be substituted for the C++ snippets in the + documentation. - \bold{Note:} Although all of these commands can be used to present - C++ code, the \l{07-0-qdoc-commands-quoting.html#snippet}{\\snippet} - and \l{07-0-qdoc-commands-quoting.html#codeline}{\\codeline} commands - should be used in preference to - the others when presenting valid code. This allows auxilliary tools - for Qt language bindings to substitute the relevant code snippets in - place of the C++ ones. + \target code-command + \section1 \\code - \section1 Alphabetical List + The \\code and \\endcode commands enclose a snippet of source code. - \l {06-qdoc-commands-verbatimcode.html#badcode}{\\badcode}, - \l {06-qdoc-commands-verbatimcode.html#code}{\\code}, - \l {06-qdoc-commands-verbatimcode.html#newcode}{\\newcode}, - \l {06-qdoc-commands-verbatimcode.html#oldcode}{\\oldcode} + \note The \l {c-command} {\\c} command can be used for short code + fragments within a sentence. The \\code command is for longer code + snippets. It renders the code verbatim in a separate paragraph in + the code font. - \section1 Command Descriptions + When processing any of the \\code, \l {badcode-command} + {\\badcode}, \l {newcode-command} {\\newcode} or \l + {oldcode-command} {\\oldcode} commands, QDoc removes all + indentation that is common for the verbatim code blocks within a + \c{/}\c{*!} ... \c{*}\c{/} comment before it adds the standard + indentation. For that reason the recommended style is to use 8 + spaces for the verbatim code contained within these commands - \table - \header - \o Command - \o Description - - \row - \o \bold \\code \target code - \o \bold {The \\code command and the corresponding - \\endcode command delimit a piece of verbatim code.} - - Whereas the \l {c}{\\c} command can be used for short code - fragments within a sentence, the \\code command is for - longer code snippets and renders the code verbatim in a - separate paragraph using a typewriter font and the standard - indentation. - - When processing any of the \\code, \l {badcode}{\\badcode}, - \l {newcode}{\\newcode} and \l {oldcode}{\\oldcode} - commands, QDoc basically removes all indentation that is - common for the verbatim code blocks within a \c{/}\c{*!} ... - \c{*}\c{/} comment before it adds the standard - indentation. For that reason the recommended style is to - use 8 spaces for the verbatim code contained within these - commands (note that this doesn't apply to externally - quoted code using the \l {quotefromfile}{\\quotefromfile} - or \l {quotefile}{\\quotefile} command). - - For example: + \note This doesn't apply to externally quoted code using the \l + {quotefromfile-command} {\\quotefromfile} or \l + {quotefile-command} {\\quotefile} command. \code / *! @@ -1053,7 +1191,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \code #include <QApplication> @@ -1065,34 +1203,35 @@ } \endcode - Other QDoc commands are disabled within - \\code... \\endcode, and the special character '\\' is - accepted and rendered like the rest of the code. + Other QDoc commands are disabled within \\code... \\endcode, and + the special character '\\' is accepted and rendered like the rest + of the code. - You need to type the code manually between the \\code and - \\endcode commands. If you want to include code snippets - from a particular file, use the \l - {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile} - command instead. + To include code snippets from an external file, use the + \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} + {\\snippet} and + \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} + {\\codeline} commands. - See also \l {c}{\\c}, \l - {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile}, - \l {badcode}{\\badcode}, \l {newcode}{\\newcode} and \l - {oldcode}{\\oldcode}. + See also \l {c-command} {\\c}, \l + {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} + {\\quotefromfile}, \l {badcode-command} {\\badcode}, \l + {newcode-command} {\\newcode} and \l {oldcode-command} + {\\oldcode}. - \row - \o \bold \\badcode \target badcode - \o \bold {The \\badcode command and the corresponding - \\endcode command delimit a piece of code that doesn't - compile or is wrong for some other reason.} + \target badcode-command + \section1 \\badcode - The \\badcode command is similar the \l {code}{\\code} - command, but renders the code using a grey font instead of - black (the default). + The \\badcode and \\endcode commands delimit a snippet of code + that doesn't compile or is wrong for some other reason. - Like the \l {code}{\\code} command, it renders its code on - a new line in the documentation using a typewriter font and - the standard indentation. For example: + The \\badcode command is similar to the \l {code-command} {\\code} + command, but it renders the code snippet using a grey font instead + of black. + + 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. \code / *! @@ -1112,7 +1251,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation The statement below is rendered using the @@ -1130,30 +1269,29 @@ \endcode \endquotation - Other QDoc commands are disabled within - \\badcode... \\endcode, and the special character '\\' is - accepted and rendered like the rest of the code. + Other QDoc commands are disabled within \\badcode... \\endcode, + and the special character '\\' is accepted and rendered like the + rest of the code. - See also \l {code}{\\code}, \l {newcode}{\\newcode} and \l - {oldcode}{\\oldcode}. + See also \l {code-command} {\\code}, \l {newcode-command} + {\\newcode} and \l {oldcode-command} {\\oldcode}. - \row - \o \bold \\newcode \target newcode - \o \bold {The \\newcode command, and the associated \\oldcode - and \\endcode commands, indicate how to port a piece of - code to a new version of an API.} - - The \\newcode command, and its companion the \\oldcode - command, is a convenience combination of the \l - {code}{\\code} and \l {badcode}{\\badcode} commands: The - combination provides a text relating the two code snippets - to each other. The command requires a preceding \\oldcode - statement. - - Like the \l {code}{\\code} and \l {badcode}{\\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: + \target newcode-command + \section1 \\newcode + + The \\newcode, \\oldcode, and \\endcode commands enable you to + show how to port a snippet of code to a new version of an API. + + The \\newcode command, and its companion the \\oldcode command, is + a convenience combination of the \l {code-command} {\\code} and \l + {badcode-command} {\\badcode} commands: The combination provides a + text relating the two code snippets to each other. The command + requires a preceding \\oldcode statement. + + 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. \code / *! @@ -1168,7 +1306,7 @@ * / \endcode - is rendered like this: + QDoc renders this as: \quotation \oldcode @@ -1181,76 +1319,102 @@ \endcode \endquotation - Other QDoc commands are disabled within - \\oldcode ... \\endcode, and the '\\' character doesn't need - to be escaped. + Other QDoc commands are disabled within \\oldcode ... \\endcode, + and the '\\' character doesn't need to be escaped. - \row - \o \bold \\oldcode \target oldcode - \o \bold {The \\oldcode command requires a corresponding - \\newcode statement; otherwise QDoc fails to parse the command - and emits a warning.} + \target oldcode-command + \section1 \\oldcode - See also \l {newcode}{\\newcode} and \l {badcode}{\\badcode}. - \endtable + The \\oldcode command requires a corresponding + \\newcode statement; otherwise QDoc fails to parse the command + and emits a warning. + + See also \l {newcode-command} {\\newcode} and \l {badcode-command} {\\badcode}. + + \target qml-command + \section1 \\qml \span {class="newStuff"} {(new)} + + The \\qml and \\endqml commands enclose a snippet of QML source + code. Currently, QDoc handles \\qml and \\endqml exactly the same + as \\code and \\endcode. + + \code + / *! + \qml + import QtQuick 1.0 + + Row { + Rectangle { + width: 100; height: 100 + color: "blue" + transform: Translate { y: 20 } + } + Rectangle { + width: 100; height: 100 + color: "red" + transform: Translate { y: -20 } + } + } + \endqml + * / + \endcode + + QDoc renders this as: + + \qml + import QtQuick 1.0 + + Row { + Rectangle { + width: 100; height: 100 + color: "blue" + transform: Translate { y: 20 } + } + Rectangle { + width: 100; height: 100 + color: "red" + transform: Translate { y: -20 } + } + } + \endqml */ /*! - \page 07-0-qdoc-commands-quoting.html - \previouspage Verbatim Code Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Linking Commands + \page 07-0-qdoc-commands-includingexternalcode.html + \previouspage Including Code Inline + \contentspage Table of Contents + \nextpage Creating Links - \title Quoting External Code Commands + \title Including External Code - The following commands enable quoting from files in the - documentation: You can make QDoc include the complete contents of + The following commands enable you to include code snippets from + external files. You can make QDoc include the complete contents of a file, or you can quote specific parts of the file and skip others. The typical use of the latter is to quote a file chunk by chunk. - \bold{Note:} Although all of these commands can be used to present - C++ code, the \l{#snippet}{\\snippet} and \l{#codeline}{\\codeline} - commands should be used in preference to - the others when presenting valid code. This allows auxilliary tools - for Qt language bindings to substitute the relevant code snippets in - place of the C++ ones. - - \section1 Alphabetical List - - \l {07-0-qdoc-commands-quoting.html#codeline}{\\codeline}, - \l {07-0-qdoc-commands-quoting.html#dots}{\\dots}, - \l {07-0-qdoc-commands-quoting.html#printline}{\\printline}, - \l {07-0-qdoc-commands-quoting.html#printto}{\\printto}, - \l {07-0-qdoc-commands-quoting.html#printuntil}{\\printuntil}, - \l {07-0-qdoc-commands-quoting.html#quotefile}{\\quotefile}, - \l {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile}, - \l {07-0-qdoc-commands-quoting.html#skipline}{\\skipline}, - \l {07-0-qdoc-commands-quoting.html#skipto}{\\skipto}, - \l {07-0-qdoc-commands-quoting.html#skipuntil}{\\skipuntil}, - \l {07-0-qdoc-commands-quoting.html#snippet}{\\snippet} - - \section1 Command Descriptions - - \table - \header - \o Command - \o Description + \bold{Note:} Although all these commands are for rendering C++ + code, the + \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} + {\\snippet} and + \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} + {\\codeline} commands are preferred over the others. These + commands allow equivalent code snippets for other Qt language + bindings to be substituted for the C++ snippets in the + documentation. - \row - \o \bold \\quotefile \target quotefile - \o \bold {The \\quotefile command expands to the complete - contents of the file given as argument.} + \target quotefile-command + \section1 \\quotefile - The command considers the rest of the line as part of its - argument, make sure to follow the file name with a line - break. + The \\quotefile command expands to the complete contents of the + file given as argument. - The file's contents is rendered in a separate paragraph, - using a typewriter font and the standard indentation. The - code is shown verbatim. + The command considers the rest of the line as part of its + argument, make sure to follow the file name with a line break. - For example: + The file's contents is rendered in a separate paragraph, using a + typewriter font and the standard indentation. The code is shown + verbatim. \code / *! @@ -1263,7 +1427,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation This is a simple "Hello world" example: @@ -1274,29 +1438,26 @@ application up and running. \endquotation - \warning If you use the \l {QDoc - Compatibility}{compat.qdocconf} file this command is called - \\include. + See also \l {quotefromfile-command} {\\quotefromfile} and + \l {code-command} {\\code}. - See also \l {quotefromfile}{\\quotefromfile} and \l - {code}{\\code}. - \row - \o \bold \\quotefromfile \target quotefromfile - \o \bold {The \\quotefromfile command opens the file - given as argument for quoting.} - - The command considers the rest of the line as part of its - argument, make sure to follow the file name with a line - break. - - The command is intended for use when quoting parts from - file with the walkthrough commands: \l - {printline}{\\printline}, \l {printto}{\\printto}, \l - {printuntil}{\\printuntil}, \l {skipline}{\\skipline}, \l - {skipto}{\\skipto}, \l {skipuntil}{\\skipuntil}. This - enables you to quote specific portions of a file. For - example: + \target quotefromfile-command + \section1 \\quotefromfile + + The \\quotefromfile command opens the file given as argument for + quoting. + + The command considers the rest of the line as part of its + argument, make sure to follow the file name with a line break. + + The command is intended for use when quoting parts from file with + the walkthrough commands: \l {printline-command} {\\printline}, \l + {printto-command} {\\printto}, \l {printuntil-command} + {\\printuntil}, \l {skipline-command} {\\skipline}, \l + {skipto-command} {\\skipto}, \l {skipuntil-command} + {\\skipuntil}. This enables you to quote specific portions of a + file. \code / *! @@ -1321,7 +1482,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation The whole application is contained within @@ -1344,38 +1505,35 @@ ... \endquotation - (\l {Example File}{The complete example file...}) + (\l {Example File} {The complete example file...}) - QDoc remembers which file it's quoting, and the current - position within that file (see \l {file}{\\printline} for - more information). There is no need to "close" the file. + QDoc remembers which file it's quoting, and the current position + within that file (see \l {file} {\\printline} for more + information). There is no need to "close" the file. - Earlier we called this command \\quotefile. For more - information, see the \l - {26-qdoc-commands-compatibility.html#quotefromfile-versus-quotefile} - {compatibility} section. + Earlier we called this command \\quotefile. For more information, + see the \l + {26-qdoc-commands-compatibility.html#quotefromfile-versus-quotefile} + {compatibility} section. - See also \l {quotefile}{\\quotefile}, \l {code}{\\code} and - \l {dots}{\\dots}. + See also \l {quotefile-command} {\\quotefile}, \l {code-command} + {\\code} and \l {dots} {\\dots}. - \row - \o \bold \\printline \target printline - \o \bold {The \\printline command expands to the line - from the current position to the next non-blank line of - the current souce file.} + \target printline-command + \section1 \\printline - To ensure that the documentation always is synchronized - with the source file, a substring of the line must be - specified as an argument to the command. Note that the - command considers the rest of the line as part of its - argument, make sure to follow the substring with a line - break. + The \\printline command expands to the line from the current + position to the next non-blank line of the current souce file. - 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. + To ensure that the documentation remains synchronized with the + source file, a substring of the line must be specified as an + argument to the command. Note that the command considers the rest + of the line as part of its argument, make sure to follow the + substring with a line break. - For example: + 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. \code / *! @@ -1403,7 +1561,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation There has to be exactly one QApplication object @@ -1430,22 +1588,20 @@ The main function... \endquotation - (\l {Example File}{The complete example file...}) - - \target file + (\l {Example File} {The complete example file...}) - QDoc reads the file sequentially. To move the current - position forward you can use either of the \l - {skipline}{\\skip...} commands. To move the current - position backward, you can use the \l - {quotefromfile}{\\quotefromfile} command again. + \target file - \target substring + QDoc reads the file sequentially. To move the current position + forward you can use either of the \l {skipline-command} + {\\skip...} commands. To move the current position backward, you + can use the \l {quotefromfile-command} {\\quotefromfile} command + again. - If the substring argument is surrounded by slashes it is - interpreted as a \l {regular expression}. + \target substring - For example: + If the substring argument is surrounded by slashes it is + interpreted as a \l {regular expression}. \code / *! @@ -1462,7 +1618,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation \quotefromfile widgets/scribble/mainwindow.cpp @@ -1477,39 +1633,36 @@ application. \endquotation - (\l {widgets/scribble}{The complete example file...}) + (\l {widgets/scribble} {The complete example file...}) - The regular expression \c /^\}/ makes QDoc print until the - first '}' character occurring at the beginning of the line - without indentation. /.../ encloses the regular expression, - and '^' means the beginning of the line. The '}' character - must be escaped since it is a special character in regular - expressions. + The regular expression \c /^\}/ makes QDoc print until the first + '}' character occurring at the beginning of the line without + indentation. /.../ encloses the regular expression, and '^' means + the beginning of the line. The '}' character must be escaped since + it is a special character in regular expressions. - QDoc will emit a warning if the specified substring or - regular expression cannot be located, i.e. if the source - code has changed. + QDoc will emit a warning if the specified substring or regular + expression cannot be located, i.e. if the source code has changed. - See also \l {printto}{\\printto} and \l - {printuntil}{\\printuntil}. + See also \l {printto-command} {\\printto} and \l + {printuntil-command} {\\printuntil}. - \row - \o \bold \\printto \target printto - \o \bold {The \\printto command expands to all the lines - from the current position up to and \i excluding the - next line containing a given substring.} + \target printto-command + \section1 \\printto - The command considers the rest of the line as part of its - argument, make sure to follow the substring with a line - break. The command also follows the same conventions for \l - {file}{positioning} and \l {substring}{argument} as the \l - {printline}{\\printline} command. + The \\printto command expands to all the lines from the current + position up to and \e excluding the next line containing a given + substring. - 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. + The command considers the rest of the line as part of its + argument, make sure to follow the substring with a line break. The + command also follows the same conventions for \l {file} + {positioning} and \l {substring} {argument} as the \l + {printline-command} {\\printline} command. - For example: + 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. \code / *! @@ -1524,7 +1677,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation The whole application is contained within the @@ -1538,28 +1691,27 @@ and \c argv parameters... \endquotation - (\l {Example File}{The complete example file...}) + (\l {Example File} {The complete example file...}) - See also \l {printline}{\\printline} and \l - {printuntil}{\\printuntil}. + See also \l {printline-command} {\\printline} and \l + {printuntil-command} {\\printuntil}. - \row - \o \bold \\printuntil \target printuntil - \o \bold {The \\printuntil command expands to all the lines - from the current position up to and \i including the next line - containing a given substring.} + \target printuntil-command + \section1 \\printuntil - The command considers the rest of the line as part of its - argument, make sure to follow the substring with a line - break. The command also follows the same conventions for \l - {file}{positioning} and \l {substring}{argument} as the \l - {printline}{\\printline} command. + The \\printuntil command expands to all the lines from the current + position up to and \e including the next line containing a given + substring. - 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. + The command considers the rest of the line as part of its + argument, make sure to follow the substring with a line break. The + command also follows the same conventions for \l {file} + {positioning} and \l {substring} {argument} as the \l + {printline-command} {\\printline} command. - For example: + 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. \code / *! @@ -1576,7 +1728,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation The whole application is contained within the @@ -1587,33 +1739,33 @@ \printuntil hello First we create a \l - {http://qt.nokia.com/doc/4.0/qapplication}{QApplication} + {http://qt.nokia.com/doc/4.0/qapplication} {QApplication} object using the \c argc and \c argv parameters, then we create a \l - {http://qt.nokia.com/doc/4.0/qpushbutton}{QPushButton}. + {http://qt.nokia.com/doc/4.0/qpushbutton} {QPushButton}. \endquotation - (\l {Example File}{The complete example file...}) + (\l {Example File} {The complete example file...}) - See also \l {printline}{\\printline} and \l - {printto}{\\printto}. + See also \l {printline-command} {\\printline} and \l + {printto-command} {\\printto}. - \row - \o \bold \\skipline \target skipline - \o \bold {The \\skipline command ignores the next non-blank - line in the current source file.} - - Doc reads the file sequentially, and the \\skipline command - is used to move the current position (omitting a line of - the source file). See the remark about \l {file}{file - positioning} above. - - The command considers the rest of the line as part of its - argument, make sure to follow the substring with a line - break. The command also follows the same conventions for \l - {substring}{argument} as the \l {printline}{\\printline} - command, and it is used in conjunction with the \l - {quotefromfile}{\\quotefromfile} command. For example: + \target skipline-command + \section1 \\skipline + + The \\skipline command ignores the next non-blank line in the + current source file. + + Doc reads the file sequentially, and the \\skipline command is + used to move the current position (omitting a line of the source + file). See the remark about \l {file} {file positioning} above. + + The command considers the rest of the line as part of its + argument, make sure to follow the substring with a line break. 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. \code / *! @@ -1631,7 +1783,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation \l @@ -1649,30 +1801,30 @@ that contains its definition. \endquotation - (\l {Example File}{The complete example file...}) + (\l {Example File} {The complete example file...}) - See also \l {skipto}{\\skipto}, \l - {skipuntil}{\\skipuntil} and \l {dots}{\\dots}. + See also \l {skipto-command} {\\skipto}, \l {skipuntil-command} + {\\skipuntil} and \l {dots} {\\dots}. - \row - \o \bold \\skipto \target skipto - \o \bold {The \\skipto command ignores all the lines from the - current position up to and \i excluding the next line - containing a given substring.} + \target skipto-command + \section1 \\skipto - QDoc reads the file sequentially, and the \\skipto command - is used to move the current position (omitting one or - several lines of the source file). See the remark about \l - {file}{file positioning} above. + The \\skipto command ignores all the lines from the current + position up to and \e excluding the next line containing a given + substring. - The command considers the rest of the line as part of its - argument, make sure to follow the substring with a line - break. + QDoc reads the file sequentially, and the \\skipto command is used + to move the current position (omitting one or several lines of the + source file). See the remark about \l {file} {file positioning} + above. - The command also follows the same conventions for \l - {substring}{argument} as the \l {printline}{\\printline} - command, and it is used in conjunction with the \l - {quotefromfile}{\\quotefromfile} command. For example: + The command considers the rest of the line as part of its + argument, make sure to follow the substring with a line break. + + 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. \code / *! @@ -1691,7 +1843,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation The whole application is contained within @@ -1707,30 +1859,30 @@ reasonable size ... \endquotation - (\l {Example File}{The complete example file...}) + (\l {Example File} {The complete example file...}) - See also \l {skipline}{\\skipline}, \l - {skipuntil}{\\skipuntil} and \l {dots}{\\dots}. + See also \l {skipline-command} {\\skipline}, \l + {skipuntil-command} {\\skipuntil} and \l {dots} {\\dots}. - \row - \o \bold \\skipuntil \target skipuntil - \o \bold {The \\skipuntil command ignores all the lines from - the current position up to and \i including the next line - containing a given substring.} + \target skipuntil-command + \section1 \\skipuntil - QDoc reads the file sequentially, and the \\skipuntil - command is used to move the current position (omitting one - or several lines of the source file). See the remark about - \l {file}{file positioning} above. + The \\skipuntil command ignores all the lines from the current + position up to and \e including the next line containing a given + substring. - The command considers the rest of the line as part of its - argument, make sure to follow the substring with a line - break. + QDoc reads the file sequentially, and the \\skipuntil command is + used to move the current position (omitting one or several lines + of the source file). See the remark about \l {file} {file + positioning} above. - The command also follows the same conventions for \l - {substring}{argument} as the \l {printline}{\\printline} - command, and it is used in conjunction with the \l - {quotefromfile}{\\quotefromfile} command. For example: + The command considers the rest of the line as part of its + argument, make sure to follow the substring with a line break. + + 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. \code / *! @@ -1748,7 +1900,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation The first thing we did in the \c main() function was to @@ -1764,20 +1916,21 @@ will return when the application exits... \endquotation - (\l {Example File}{The complete example file...}) + (\l {Example File} {The complete example file...}) - See also \l {skipline}{\\skipline}, \l {skipto}{\\skipto} - and \l {dots}{\\dots}. + See also \l {skipline-command} {\\skipline}, \l {skipto-command} + {\\skipto} and \l {dots} {\\dots}. - \row - \o \bold \\dots \target dots - \o \bold {The \\dots command indicates that parts of the - source file have been omitted when quoting a file.} + \target dots-command + \section1 \\dots - The command is used in conjunction with the \l - {quotefromfile}{\\quotefromfile} command, and should be - stated on its own line. The dots are rendered on a new - line, using a typewriter font. For example: + The \\dots command indicates that parts of the source file have + been omitted when quoting a file. + + 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. \code / *! @@ -1790,7 +1943,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotefromfile examples/main.cpp \skipto main @@ -1799,54 +1952,54 @@ \skipuntil exec \printline } - (\l {Example File}{The complete example file...}) + (\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: + The default indentation is 4 spaces, but this can be adjusted + using the command's optional argument. - \code - / *! - \dots 0 - \dots - \dots 8 - \dots 12 - \dots 16 - * / - \endcode + \code + / *! + \dots 0 + \dots + \dots 8 + \dots 12 + \dots 16 + * / + \endcode - will be rendered as + QDoc renders this as: - \dots 0 - \dots - \dots 8 - \dots 12 - \dots 16 + \dots 0 + \dots + \dots 8 + \dots 12 + \dots 16 - See also \l {skipline}{\\skipline}, \l - {skipto}{\\skipto} and \l {skipuntil}{\\skipuntil}. + See also \l {skipline-command} {\\skipline}, \l {skipto-command} + {\\skipto} and \l {skipuntil-command} {\\skipuntil}. - \row - \o \bold \\snippet \target snippet - \o \bold {The \\snippet command causes a code snippet to be included - verbatim as preformatted text, which may be syntax highlighted.} - - Each code snippet are referenced by the file that holds it and by - a unique identifier for that file. Snippet files are typically - stored in a \c{snippets} directory inside the documentation - directory (e.g., \c{$QTDIR/doc/src/snippets}). + \target snippet-command + \section1 \\snippet + + The \\snippet command causes a code snippet to be included + verbatim as preformatted text, which may be syntax highlighted. - For example, the following documentation references a snippet in - a file residing in a subdirectory of the documentation directory: + Each code snippet are referenced by the file that holds it and by + a unique identifier for that file. Snippet files are typically + stored in a \c{snippets} directory inside the documentation + directory (e.g., \c{$QTDIR/doc/src/snippets}). + + For example, the following documentation references a snippet in a + file residing in a subdirectory of the documentation directory: \code \snippet snippets/textdocument-resources/main.cpp Adding a resource \endcode - The text following the file name is the unique identifier for the - snippet. This is used to delimit the quoted code in the relevant - snippet file as shown in the following example that corresponds to - the above \c{\\snippet} command: + The text following the file name is the unique identifier for the + snippet. This is used to delimit the quoted code in the relevant + snippet file as shown in the following example that corresponds to + the above \c{\\snippet} command: \dots \code @@ -1859,18 +2012,20 @@ //! [Adding a resource] \endcode \dots - \row - \o \bold \\codeline \target codeline - \o \bold{The \\codeline command inserts a blank line of preformatted - text. It is used to insert gaps between snippets without closing - the current preformatted text area and opening a new one.} - \endtable + + \target codeline-command + \section1 \\codeline + + The \\codeline command inserts a blank line of preformatted + text. It is used to insert gaps between snippets without closing + the current preformatted text area and opening a new one. + */ /*! \page 07-1-example.html - \previouspage Quoting External Code Commands - \contentspage QDoc Manual - Table of Contents + \previouspage Including External Code + \contentspage Table of Contents \title Example File @@ -1878,541 +2033,528 @@ */ /*! - \page 08-qdoc-commands-linking.html - \previouspage Quoting External Code Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Graphic Commands + \page 08-qdoc-commands-creatinglinks.html + \previouspage Including External Code + \contentspage Table of Contents + \nextpage Including Images - \title Linking Commands + \title Creating Links - The linking commands make it possible to create hyperlinks to - classes, functions, header files and examples. They also make it - possible to link to targets within a document, as well as to other - documents and URLs. + These commands are for creating hyperlinks to classes, functions, + examples, and other targets. - \section1 Alphabetical List + \target l-command + \section1 \\l (link) - \l {08-qdoc-commands-linking.html#keyword}{\\keyword}, - \l {08-qdoc-commands-linking.html#l}{\\l}, - \l {08-qdoc-commands-linking.html#sa}{\\sa}, - \l {08-qdoc-commands-linking.html#target}{\\target} + The \\l link command is used to create a hyperlink to many + different kinds of targets. The command's general syntax is: - \section1 Command Descriptions + \code + \l {link target} {link text} + \endcode - \table - \header - \o Command - \o Description + \code + / *! + Read the \l {http://qt.nokia.com/doc/4.0/} + {Qt's Reference Documentation} carefully. + * / + \endcode - \row - \o \bold \\l \target l - \o \bold {The \\l command is used to create hyperlinks. } + QDoc renders this as: - The command's general syntax is + \quotation + Read the \l {http://qt.nokia.com/doc/4.0/} + {Qt's Reference Documentation} carefully. + \endquotation - \code - \l {link target}{link text} - \endcode + If the link target is equivalent to the link text, the second + argument can be omitted. - For example: + For example, if you have documentation like: - \code - / *! - Read the \l {http://qt.nokia.com/doc/4.0/} - {Qt's Reference Documentation} carefully. - * / - \endcode + \code + / *! + \target assertions - will be rendered as + Assertions make some statement about the text at the + point where they occur in the regexp but they do not + match any characters. - \quotation - Read the \l {http://qt.nokia.com/doc/4.0/} - {Qt's Reference Documentation} carefully. - \endquotation + ... - If the link target is equivalent to the link text, the - second argument can be omitted. + Regexps are built up from expressions, quantifiers, and + \l {assertions} {assertions}. + * / + \endcode - For example, if you have documentation like: + You can simplify this as follows: - \code - / *! - \target assertions + \code + / *! + \target assertions - Assertions make some statement about the text at the - point where they occur in the regexp but they do not - match any characters. + Assertions make some statement about the text at the + point where they occur in the regexp but they do not + match any characters. - ... + ... - Regexps are built up from expressions, quantifiers, and - \l {assertions}{assertions}. - * / - \endcode + Regexps are built up from expressions, quantifiers, and + \l assertions. + * / + \endcode - you can rewrite it as + For the one-parameter version the braces can often be omitted. + The \\l command supports several kinds of links: - \code - / *! - \target assertions + \list - Assertions make some statement about the text at the - point where they occur in the regexp but they do not - match any characters. + \o \c {\l QWidget} - The name of a class documented with the \l + {class-command} {\\class} command. - ... + \o \c {\l QWidget::sizeHint()} - The name of a member function, + documented with or without an \l {fn-command} {\\fn} command. - Regexps are built up from expressions, quantifiers, and - \l assertions. - * / - \endcode + \o \c {\l <QtGlobal>} - The subject of a \l {headerfile-command} + {\\headerfile} command. - For the one-parameter version the braces can often - be omitted. See the \l {i}{\\i} command for the \l - {argument}{argument conventions}. + \o \c {\l widgets/wiggly} - The relative path used in an \l + {example-command} {\\example} command. - The \\l command supports several kinds of links: + \o \c {\l {QWidget Class Reference}} - The title used in a + \l {title-command} {\\title} command. - \list - \o \c {\l QWidget} - a defined \l {class}{\\class} - \o \c {\l QWidget::sizeHint()} - a defined member - function (\l {fn}{\\fn}) - \o \c {\l <QtGlobal>} - a defined \l {headerfile}{\\headerfile} - \o \c {\l widgets/wiggly} - a defined - \l {example-command}{\\example} - \o \c {\l {QWidget Class Reference}} - a defined \l {title}{\\title} - \o \c {\l {Introduction}}- a defined \l{part}{\\part}, - \l{chapter}{\\chapter} or \l {sectionOne}{\\section...} - \o \c {\l fontmatching} - a defined \l {target}{\\target} - \o \c {\l {Shared Classes}} - a defined \l {keyword}{\\keyword} - \o \c {\l network.html} - a defined \l {page}{\\page} - \o \c {\l http://www.trolltech.com/} - a URL - \endlist + \o \c {\l {Introduction to QDoc}}- The text from one of the + \l{part-command} {\\part}, \l{chapter} {\\chapter} or \l + {sectionOne-command} {\\section} commands. - QDoc also tries to make a link out of any words that don't - resemble any normal English words, for example Qt class - names or functions, like QWidget or QWidget::sizeHint(). In - these cases, the \\l command can actually be omitted, but - by using the command, you ensure that QDoc will emit a - warning if it cannot find the link target. In addition, if - you only want the function name to appear in the link, you - can use the following syntax: + \o \c {\l fontmatching} - The argument of a \l {target-command} + {\\target} command. - \list - \o \c {\l {QWidget::}{sizeHint()}} - \endlist + \o \c {\l {Shared Classes}} - A keyword named in a \l + {keyword-command} {\\keyword} command. - See also \l {sa}{\\sa}, \l {target}{\\target} and \l - {keyword}{\\keyword}. + \o \c {\l network.html} - The file name used in a \l + {page-command} {\\page} command. - \row - \o \bold \\sa \target sa - \o \bold {The \\sa command defines a list of links that will - be rendered in a separate "See also" section at the bottom - of the documentation.} + \o \c {\l http://www.trolltech.com/} - A URL. - The command takes a comma-separated list of links as its - argument. If the line ends with a comma, you can continue - on a second line. The general syntax is: + \endlist - \code - \sa {the first link}, {the second link}, - {the third link}, ... - \endcode + QDoc also tries to make a link out of any words that don't + resemble any normal English words, for example Qt class names or + functions, like QWidget or QWidget::sizeHint(). In these cases, + the \\l command can actually be omitted, but by using the command, + you ensure that QDoc will emit a warning if it cannot find the + link target. In addition, if you only want the function name to + appear in the link, you can use the following syntax: - QDoc will automatically try to generate "See also" links - interconnecting a property's various functions. For - example, an setVisible() function will automatically get a - link to visible() and vice versa. + \list + \o \c {\l {QWidget::} {sizeHint()}} + \endlist - In general, QDoc will generate "See also" links that - interconnect the functions that access the same - property. It recognizes four different syntax versions: + QDoc renders this as: - \list - \o \c property() - \o \c setProperty() - \o \c isProperty() - \o \c hasProperty() - \endlist + \quotation + \l {QWidget::} {sizeHint()} + \endquotation - The \\sa command supports the same kind - of links as the \l {l}{\\l} command. For example: + See also \l {sa-command} {\\sa}, \l {target-command} {\\target} + and \l {keyword-command} {\\keyword}. - \code - / *! - Appends the actions \a actions to this widget's - list of actions. - \sa removeAction(), QMenu, addAction() - * / - void QWidget::addActions(QList<QAction *> actions) - { - ... - } - \endcode + \target sa-command + \section1 \\sa (see also) - will be rendered as + The \\sa command defines a list of links that will be rendered in + a separate "See also" section at the bottom of the documentation + unit. - \quotation - \bold {void QWidget::addActions ( QList<QAction*> - \i actions )} + The command takes a comma-separated list of links as its + argument. If the line ends with a comma, you can continue + the list on the next line. The general syntax is: - Appends the actions \i actions to this widget's - list of actions. + \code + \sa {the first link}, {the second link}, + {the third link}, ... + \endcode - See also \l {QWidget::removeAction()}{removeAction()}, - \l QMenu, and \l {QWidget::addAction()}{addAction()}. - \endquotation + QDoc will automatically try to generate "See also" links + interconnecting a property's various functions. For example, a + setVisible() function will automatically get a link to visible() + and vice versa. - See also \l {l}{\\l}, \l {target}{\\target} and \l - {keyword}{\\keyword}. + In general, QDoc will generate "See also" links that interconnect + the functions that access the same property. It recognizes four + different syntax versions: - \row - \o \bold \\target \target target - \o \bold {The \\target command defines an explicit point in the - documentation that you can later link to using the \l {l}{\\l} - and \l {sa}{\\sa} commands.} + \list + \o \c property() + \o \c setProperty() + \o \c isProperty() + \o \c hasProperty() + \endlist - The command considers the rest of the line as part of its - argument, make sure to follow the target name with a line - break. + The \\sa command supports the same kind of links as the \l + {l-command} {\\l} command. - For example: + \code + / *! + Appends the actions \a actions to this widget's + list of actions. + + \sa removeAction(), QMenu, addAction() + * / + void QWidget::addActions(QList<QAction *> actions) + { + ... + } + \endcode - \code - / *! - \target capturing parentheses - \section1 Capturing Text + QDoc renders this as: - Parentheses allow us to group elements together so that - we can quantify and capture them. + \quotation + \bold {void QWidget::addActions ( QList<QAction*> + \e actions )} - ... - * / - \endcode + Appends the actions \e actions to this widget's list of + actions. - can be referenced with + See also \l {QWidget::removeAction()} {removeAction()}, + \l QMenu, and \l {QWidget::addAction()} {addAction()}. + \endquotation - \list - \o \c {\l {capturing parentheses}} - (from elsewhere in the same comment) - \o \c {\l qregexp.html#capturing-parentheses} - (from anywhere else) - \endlist + See also \l {l-command} {\\l}, \l {target-command} {\\target} and + \l {keyword-command} {\\keyword}. - within a documentation unit, and with - \list - \o \c {\l http://www.trolltech.com/4.0/doc/html/qregexp.html#capturing-parentheses} - \endlist + \target target-command + \section1 \\target - on a more global scale. + The \\target command names a place in the documentation that you + can link to using the \l {l-command} {\\l (link)} and \l + {sa-command} {\\sa (see also)} commands. - If the target name does't contain any spaces, the brackets can - be omitted as well. + The text up to the line break becomes the target name. Be sure to + follow the target name with a line break. Curly brackets are not + required around the target name, but they may be required when the + target name is used in a link cammand. See below. - See also \l {l}{\\l}, \l {sa}{\\sa} and \l - {keyword}{\\keyword}. + \code + / *! + \target capturing parentheses + \section1 Capturing Text - \row - \o \bold \\keyword \target keyword - \o \bold {The \\keyword command defines an explicit point in the - documentation that you can later link to using the \l {l}{\\l} - and \l {sa}{\\sa} commands.} + Parentheses allow us to group elements together so that + we can quantify and capture them. - Keywords must be unique within the entire set of - documentation processed in on QDoc run. The command - considers the rest of the line as part of its argument, - make sure to follow the keyword with a line break. + ... + * / + \endcode - The \\keyword command is similar to \l {target}{\\target}, - but stronger. A keyword can be referenced from anywhere - using a simple syntax. For example: + The target name \e{capturing parentheses} can be linked from + within the same document containing the target in two ways: - \code - / *! - \class QRegExp - \reentrant - \brief The QRegExp class provides pattern - matching using regular expressions. - \ingroup tools - \ingroup misc - \ingroup shared - \mainclass + \list + \o \c {\l {capturing parentheses}} (from within the same qdoc comment) + \o \c {\l qregexp.html#capturing-parentheses} (from elsewhere in the same document) + \endlist - \keyword regular expression + \note The brackets in the link example are required because the + target name contains spaces. - Regular expressions, or "regexps", provide a way to - find patterns within text. + From other documents, the target name can be linked this way: - ... - * / - \endcode + \list + \o \c {\l http://www.trolltech.com/4.0/doc/html/qregexp.html#capturing-parentheses} + \endlist - can be referenced like this + See also \l {l-command} {\\l}, \l {sa-command} {\\sa} and \l + {keyword-command} {\\keyword}. - \code - / *! - When a string is surrounded by slashes, it's - interpreted as a \l regular expression. - * / - \endcode + \target keyword-command + \section1 \\keyword - which will be rendered as + The \\keyword command names a place in the documentation that you + can link to using the \l {l-command} {\\l (link)} and \l + {sa-command} {\\sa (see also)} commands. - \quotation - When a string is surrounded by slashes, it's - interpreted as a \l {regular expression}. - \endquotation + The \\keyword command is like the \l {target-command} {\\target} + command, but stronger. A keyword can be linked from anywhere using + a simple syntax. - If the keyword does't contain any spaces, the brackets can - be omitted as well. + Keywords must be unique over all the documents processed during + the QDoc run. The command uses the rest of the line as its + argument. Be sure to follow the keyword with a line break. - See also \l {l}{\\l}, \l {sa}{\\sa} and \l - {target}{\\target}. - \endtable -*/ -/*! - \page 09-qdoc-commands-graphic.html - \previouspage Linking Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Container Commands + \code + / *! + \class QRegExp + \reentrant + \brief The QRegExp class provides pattern + matching using regular expressions. + \ingroup tools + \ingroup misc + \ingroup shared + \mainclass - \title Graphic Commands + \keyword regular expression - The graphic commands makes it possible to include images in the - documentation. The images can be rendered as separate paragraphs, - or within running text. + Regular expressions, or "regexps", provide a way to + find patterns within text. - \section1 Alphabetical List + ... + * / + \endcode - \l {09-qdoc-commands-graphic.html#caption}{\\caption}, - \l {09-qdoc-commands-graphic.html#image}{\\image}, - \l {09-qdoc-commands-graphic.html#inlineimage}{\\inlineimage} + The location marked with the keyword can be linked with: - \section1 Command Descriptions + \code + / *! + When a string is surrounded by slashes, it is + interpreted as a \l {regular expression}. + * / + \endcode - \table - \header - \o Command - \o Description + QDoc renders this as: - \row - \o \bold \\image \target image - \o \bold {The \\image command expands to the image specified by its - argument, and renders it centered as a separate paragraph.} + \quotation + When a string is surrounded by slashes, it's + interpreted as a \l {regular expression}. + \endquotation - The \\image command replaces the old \\img command. For more - information, see the \l - {26-qdoc-commands-compatibility.html#image-versus-img} - {compatibility} section. + If the keyword text contains spaces, the brackets are required. - The command takes two arguments. The first is the name of - the image file. The second argument is optional and is a - simple description of the image equivalent to the HTML - alt="" in an image tag. The description is used for - tooltips, and when a browser doesn't support images like - the Lynx text browser. + See also \l {l-command} {\\l (link)}, \l {sa-command} {\\sa (see + also)} and \l {target-command} {\\target}. - The command considers the rest of the line after the file - name its second argument, make sure that you follow the - filename or description with a line break. Braces are only - necessary if the description spans several lines. +*/ - For example: +/*! + \page 09-qdoc-commands-includingimages.html + \previouspage Creating Links + \contentspage Table of Contents + \nextpage Tables and Lists - \code - / *! - Qt by Trolltech is a C++ toolkit for cross-platform GUI - application development. + \title Including Images - \image happyguy.jpg "Happy guy" + The graphic commands makes it possible to include images in the + documentation. The images can be rendered as separate paragraphs, + or within running text. - Qt provides single-source portability across Microsoft - Windows, Mac OS X, Linux, and all major commercial Unix - variants. It is also available for embedded devices. - * / - \endcode + \target image-command + \section1 \\image - will be rendered as + The \\image command expands to the image specified by its first + argument, and renders it centered as a separate paragraph. - \quotation - Qt by Trolltech is a C++ toolkit for cross-platform GUI - application development. + The \\image command replaces the old \\img command. For more + information, see the \l + {26-qdoc-commands-compatibility.html#image-versus-img} + {compatibility} section. - \image happyguy.jpg image "Happy guy" + The command takes two arguments. The first argument is the name of + the image file. The second argument is optional and is a simple + description of the image, equivalent to the HTML alt="" in an image + tag. The description is used for tooltips, and for when a browser + doesn't support images, like the Lynx text browser. - Qt provides single-source portability across Microsoft - Windows, Mac OS X, Linux, and all major commercial Unix - variants. It is also available for embedded devices. - \endquotation + The remaining text \e{after} the file name is the optional, + description argument. Be sure to follow the file name or the + description with a line break. Curly brackets are required if the + description argument spans multiple lines. - See also \l {inlineimage}{\\inlineimage} and \l - {caption}{\\caption}. + \code + / *! + Qt by Trolltech is a C++ toolkit for cross-platform GUI + application development. - \row - \o \bold \\inlineimage \target inlineimage - \o \bold {The \\inlineimage command expands to the image - specified by its argument; the image is rendered inline - with the rest of the text.} + \image happyguy.jpg "Happy guy" - The command takes two arguments. The first is the name of - the image file. The second argument is optional and is a - simple description of the image equivalent to the HTML - alt="" in an image tag. The description is used for - tooltips, and when a browser doesn't support images like - the Lynx text browser. + Qt provides single-source portability across Microsoft + Windows, Mac OS X, Linux, and all major commercial Unix + variants. It is also available for embedded devices. + * / + \endcode - The most common use of the \\inlineimage command is in - lists and tables. For example: + QDoc renders this as: - \code - / *! - \list 1 - \o \inlineimage happy.gif Oh so happy! - \o \inlineimage happy.gif Oh so happy! - \o \inlineimage happy.gif Oh so happy! - \endlist - * / - \endcode + \quotation + Qt by Trolltech is a C++ toolkit for cross-platform GUI + application development. - will be rendered as + \image happyguy.jpg image "Happy guy" - \list 1 - \o \inlineimage happy.gif Oh so happy! - \o \inlineimage happy.gif Oh so happy! - \o \inlineimage happy.gif Oh so happy! - \endlist + Qt provides single-source portability across Microsoft + Windows, Mac OS X, Linux, and all major commercial Unix + variants. It is also available for embedded devices. + \endquotation - And + See also \l {inlineimage-command} {\\inlineimage} and \l + {caption-command} {\\caption}. - \code - / *! - \table - \header - \o Trolltech - \o Trolltech - \row - \o \inlineimage happy.gif Oh so happy! - \o \inlineimage happy.gif Oh so happy! - \row - \o \inlineimage happy.gif Oh so happy! - \o \inlineimage happy.gif Oh so happy! - \endtable - * / - \endcode + \target inlineimage-command + \section1 \\inlineimage - will be rendered as + The \\inlineimage command expands to the image specified by its + argument. The image is rendered inline with the rest of the text. - \raw HTML - <table align="center" cellpadding="2" - cellspacing="1" border="0"> - <tr valign="top" bgcolor="#a2c511"> - <th>Trolltech</th> - <th>Trolltech</th> - </tr> + The command takes two arguments. The first argument is the name of + the image file. The second argument is optional and is a simple + description of the image, equivalent to the HTML alt="" in an image + tag. The description is used for tooltips, and for when a browser + doesn't support images, like the Lynx text browser. - <tr valign="top" bgcolor="#f0f0f0"> - <td><img src="images/happy.gif" alt="Oh so happy!" /> - </td> - <td><img src="images/happy.gif" alt="Oh so happy!" /> - </td> - </tr> + The most common use of the \\inlineimage command is in lists and + tables. Here is an example of including inline images in a list: - <tr valign="top" bgcolor="#f0f0f0"> - <td><img src="images/happy.gif" alt="Oh so happy!"/> - </td> - <td><img src="images/happy.gif" alt="Oh so happy!" /> - </td> - </tr> + \code + / *! + \list 1 + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \endlist + * / + \endcode - </table> - \endraw + QDoc renders this as: - The command can also be used to insert an image - inline with the regular text. For example: + \list 1 + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \endlist - \code - / *! - \inlineimage training.jpg Training by Trolltech - The Qt Programming course is offered as a - five day Open Enrollment Course. The classes - are open to the public.While the course is open - to anyone who wants to learn, attendees should - have significant experience in C++ development - to derive maximum benefit from the course. - * / - \endcode + Her eis an example of including inline images in a table: - will be rendered as + \code + / *! + \table + \header + \o Trolltech + \o Trolltech + \row + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \row + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \endtable + * / + \endcode - \quotation - \inlineimage training.jpg Training by Trolltech - The Qt Programming course is offered as a - five day Open Enrollment Course. The classes - are open to the public.While the course is open - to anyone who wants to learn, attendees should - have significant experience in C++ development - to derive maximum benefit from the course. - \endquotation + QDoc renders this as: - See also \l {image}{\\image} and \l {caption}{\\caption}. + \raw HTML + <table align="center" cellpadding="2" + cellspacing="1" border="0"> + <tr valign="top" bgcolor="#a2c511"> + <th>Trolltech</th> + <th>Trolltech</th> + </tr> + <tr valign="top" bgcolor="#f0f0f0"> + <td><img src="images/happy.gif" alt="Oh so happy!" /> + </td> + <td><img src="images/happy.gif" alt="Oh so happy!" /> + </td> + </tr> + <tr valign="top" bgcolor="#f0f0f0"> + <td><img src="images/happy.gif" alt="Oh so happy!"/> + </td> + <td><img src="images/happy.gif" alt="Oh so happy!" /> + </td> + </tr> + </table> + \endraw - \row - \o \bold \\caption \target caption - \o \bold {The \\caption command provides a caption for an image.} + The command can also be used to insert an image inline with the + text. - The command follows the same conventions for parentheses and use - of braces for its \l argument as the \l {i}{\\i} command. + \code + / *! + \inlineimage training.jpg Training by Trolltech + The Qt Programming course is offered as a + five day Open Enrollment Course. The classes + are open to the public.While the course is open + to anyone who wants to learn, attendees should + have significant experience in C++ development + to derive maximum benefit from the course. + * / + \endcode - \warning This is preliminary functionality. The - command is not fully implemented. + QDoc renders this as: - See also \l {image}{\\image} and \l - {inlineimage}{\\inlineimage} + \quotation + \inlineimage training.jpg Training by Trolltech + The Qt Programming course is offered as a + five day Open Enrollment Course. The classes + are open to the public.While the course is open + to anyone who wants to learn, attendees should + have significant experience in C++ development + to derive maximum benefit from the course. + \endquotation - \endtable -*/ + See also \l {image-command} {\\image} and \l {caption-command} {\\caption}. -/*! - \page 10-qdoc-commands-container.html - \previouspage Graphic Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Document Contents Commands + \target caption-command + \section1 \\caption - \title Container Commands + The \\caption command provides a caption for an image. - The container commands create tables and lists with associated - items and contents. A list is rendered left aligned as a separate - paragraph. A table is rendered centered as a separate paragraph, - and its width depends on its content. + The command takes all the text up to the end of the paragraph to + be the caption. Experiment until you get the effect you want. - \section1 Alphabetical List + \code + / *! + \table 100% + \row + \o \image windowsvista-pushbutton.png + \caption The QPushButton widget provides a command button. + \o \image windowsvista-toolbutton.png + \caption The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar. + \endtable + * / + \endcode - \l {10-qdoc-commands-container.html#header}{\\header}, - \l {10-qdoc-commands-container.html#list}{\\list}, - \l {10-qdoc-commands-container.html#o}{\\o}, - \l {10-qdoc-commands-container.html#omitvalue}{\\omitvalue}, - \l {10-qdoc-commands-container.html#row}{\\row}, - \l {10-qdoc-commands-container.html#table}{\\table}, - \l {10-qdoc-commands-container.html#value}{\\value} + QDoc renders this as: - \section1 Command Descriptions + \table 100% + \row + \o \image windowsvista-pushbutton.png + \caption The QPushButton widget provides a command button. + \o \image windowsvista-toolbutton.png + \caption The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar. + \endtable - \table - \header - \o Command - \o Description + See also \l {image-command} {\\image} and \l {inlineimage-command} + {\\inlineimage} +*/ - \row - \o \bold \\table \target table - \o \bold {The \\table command and the corresponding \\endtable - command delimit the contents of a table.} +/*! + \page 10-qdoc-commands-tablesandlists.html + \previouspage Including Images + \contentspage Table of Contents + \nextpage Special Content + + \title Tables and Lists - The command accepts a single argument specifying the - table's width in percentage: + These commands enable creating lists and tables. A list is + rendered left aligned as a separate paragraph. A table is rendered + centered as a separate paragraph. The table width depends on the + width of its contents. + + \target table-command + \section1 \\table + + The \\table and \\endtable commands delimit the contents of a + table. + + The command accepts a single argument specifying the table's width + as a percentage of the page width: \code / *! @@ -2424,15 +2566,15 @@ * / \endcode - The code above ensures that the table will fill all - available space. If the table's width is smaller than 100 %, - the table will be centered in the generated documentation. + The code above ensures that the table will fill all available + space. If the table's width is smaller than 100 %, the table will + be centered in the generated documentation. - A table can contain headers, rows and columns. A row starts - with a \l {row}{\\row} command and consists of cells, which - starts with a \l {o}{\\o} command. There is also a \l - {header}{\\header} command which is a special kind of row - with a special formatting. For example: + A table can contain headers, rows and columns. A row starts with a + \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. \code / *! @@ -2458,7 +2600,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \raw HTML <table align="center" cellpadding="2" @@ -2498,8 +2640,8 @@ </table> \endraw - You can also make cells span several rows and columns. For - example: + You can also make cells span several rows and columns. For + example: \code / *! @@ -2519,7 +2661,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \raw HTML <table align="center" cellpadding="2" cellspacing="1" @@ -2548,20 +2690,20 @@ </table> \endraw - See also \l {header}{\\header}, \l {row}{\\row} and \l {o}{\\o}. + See also \l {header-command} {\\header}, \l {row-command} {\\row} and \l {o-command} {\\o}. - \row - \o \bold \\header \target header - \o \bold {The \\header command indicates that the following - table cells are the current table's column headers.} + \target header-command + \section1 \\header - The command can only be used within the \l{table} - {\\table...\\endtable} commands. A header can contain - several cells. A cell is created with the \l {o}{\\o} - command. + The \\header command indicates that the following table cells are + the current table's column headers. - A header cell's text is centered within the table cell and - rendered using a bold font. For example: + The command can only be used within the \l{table-command} + {\\table...\\endtable} commands. A header can contain several + 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. \code / *! @@ -2577,7 +2719,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \raw HTML <table align="center" cellpadding="2" @@ -2598,23 +2740,22 @@ </table> \endraw - See also \l {table}{\\table}, \l {row}{\\row} and \l {o}{\\o}. + See also \l {table-command} {\\table}, \l {row-command} {\\row} and \l {o-command} {\\o}. - \row - \o \bold \\row \target row - \o \bold {The \\row command indicates that the following table - cells belong to the same row in the current table.} + \target row-command + \section1 \\row - The command can only be used within the \l{table} - {\\table...\\endtable} commands. A row can contain - several cells. A cell is created with the \l {o}{\\o} - command. + The \\row command begins a new row in a table. The \l {o-command} + {\\o items} that belong in the new row will immediately follow the + \\row. - The background cell color of each row alternate between two - shades of grey, making it easier to distinguish the rows - from each other. The cells' contents is left aligned. + The command can only be used within the \l{table-command} + {\\table...\\endtable} commands. A row can contain several + cells. A cell is created with the \l {o-command} {\\o} command. - For example: + 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. \code / *! @@ -2640,7 +2781,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \raw HTML <table align="center" cellpadding="2" @@ -2680,44 +2821,45 @@ </table> \endraw - See also \l {table}{\\table}, \l {header}{\\header} and \l - {o}{\\o}. + See also \l {table-command} {\\table}, \l {header-command} + {\\header} and \l {o-command} {\\o}. - \row - \o \bold \\value \target value - \o \bold {The \\value command starts the documentation of a C++ enum - item}. + \target value-command + \section1 \\value - The command's first argument is the enum item. Then follows - its associated description. The description argument ends - at the next blank line or \\value. The arguments are - rendered within a table. + The \\value command starts the documentation of a C++ enum item. - The documentation will be located in the associated class, - header file or namespace documentation. See the \l - {enum}{\\enum} documentation for an example. + The command's first argument is the enum item. Then follows its + associated description. The description argument ends at the next + blank line or \\value. The arguments are rendered within a table. - See also \l {enum}{\\enum} and \l {omitvalue}{\\omitvalue}. + The documentation will be located in the associated class, header + file or namespace documentation. See the \l {enum-command} + {\\enum} documentation for an example. - \row - \o \bold \\omitvalue \target omitvalue - \o \bold {The \\omitvalue command excludes a C++ enum item - from the documentation}. + See also \l {enum-command} {\\enum} and \l {omitvalue-command} {\\omitvalue}. - The command's only argument is the name of the enum item - that will be omitted. See the \l {enum}{\\enum} - documentation for an example. + \target omitvalue-command + \section1 \\omitvalue - See also \l {enum}{\\enum} and \l {value}{\\value}. + The \\omitvalue command excludes a C++ enum item from the + documentation. - \row - \o \bold \\list \target list - \o \bold {The \\list command and the corresponding \\endlist - command delimit a list of items.} + The command's only argument is the name of the enum item that will + be omitted. See the \l {enum-command} {\\enum} documentation for + an example. + + See also \l {enum-command} {\\enum} and \l {value-command} + {\\value}. + + \target list-command + \section1 \\list - You need to create each list item explicitly using the \l - {o}{\\o} command. A list can contain one or more items; it - can also be nested. For example: + The \\list and \\endlist commands delimit a list of items. + + Create each list item with the \l {o-command} {\\o} command. A + list always contains one or more items. Lists can be nested. For + example: \code / *! @@ -2738,7 +2880,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \list \o Qt Reference Documentation: Getting Started @@ -2755,8 +2897,8 @@ \endlist \endlist - The \\list command takes an optional argument providing - alternative appearances for the list items. For example: + The \\list command takes an optional argument providing + alternative appearances for the list items. \code / *! @@ -2768,7 +2910,7 @@ * / \endcode - will render the list items with bullets (the default): + QDoc renders the list items with bullets (the default): \list \o How to Learn Qt @@ -2776,9 +2918,12 @@ \o Tutorial and Examples \endlist - If you provide 'A' as an argument to the \\list command, - the bullets are replaced with characters following in - alphabetical order: + \warning There appears to be a bug in qdoc3 here. If you include + any of the argument types, you get a numeric list. We're looking + into it. + + If you provide 'A' as an argument to the \\list command, the + bullets are replaced with characters in alphabetical order: \list A \o How to Learn Qt @@ -2786,8 +2931,8 @@ \o Tutorial and Examples \endlist - If you replace 'A' with '1', the list items are rendered - with numbers following in ascending order: + If you replace 'A' with '1', the list items are numbered in + ascending order: \list 1 \o How to Learn Qt @@ -2796,8 +2941,8 @@ \endlist - If you provide 'i' as the argument, the default bullets are - replaced with roman numerals: + If you provide 'i' as the argument, the bullets are replaced with + roman numerals: \list i \o How to Learn Qt @@ -2805,9 +2950,9 @@ \o Tutorial and Examples \endlist - Or finally, you can make the list items appear with roman - numbers following in ascending order if you provide 'I' as - the optional argument: + Finally, you can make the list items appear with roman numbers + following in ascending order if you provide 'I' as the optional + argument: \list I \o How to Learn Qt @@ -2815,9 +2960,9 @@ \o Tutorial and Examples \endlist - You can also make the listing start at any character or - number by simply provide the number or character you want - to start at. For example: + You can also make the listing start at any character or number by + simply provide the number or character you want to start at. For + example: \code / *! @@ -2829,7 +2974,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \list G \o How to Learn Qt @@ -2837,30 +2982,30 @@ \o Tutorial and Examples \endlist - See also \l {o}{\\o}. + See also \l {o-command} {\\o}. - \row - \o \bold \\o \target o - \o \bold {The \\o command announce a table or list item.} + \target o-command + \section1 \\o (cell, item) + + The \\o command announce a table or list item. - Earlier we used the \l {i}{\\i} command for this purpose. For more - information see the \l - {26-qdoc-commands-compatibility.html#o-versus-i}{compatibility} - section. + Earlier we used the \l {i-command} {\\i} command for this + purpose. For more information see the \l + {26-qdoc-commands-compatibility.html#o-versus-i} {compatibility} + section. - The command can only be used within the \l{table} - {\\table...\\endtable} or \l{list}{\\list... \\endlist} - commands. + The command can only be used within the \l{table-command} + {\\table...\\endtable} or \l{list-command} {\\list... \\endlist} + commands. - It considers everything until the next occurrence - of the \\o command, or the currently applicable \l - {table}{\\endtable} or \l {list}{\\endlist} command, as its - argument. For examples, see \l {table}{\\table} and \l - {list}{\\list}. + It considers everything until the next occurrence of the \\o + command, or the currently applicable \l {table-command} + {\\endtable} or \l {list-command} {\\endlist} command, as its + argument. For examples, see \l {table-command} {\\table} and \l + {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: + If the command is used within a table, you can in addition specify + how many rows or columns the item should span. \code / *! @@ -2880,7 +3025,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \raw HTML <table align="center" cellpadding="2" cellspacing="1" @@ -2909,333 +3054,133 @@ </table> \endraw - If not specified, the item will span one column and one row. + If not specified, the item will span one column and one row. + + See also \l {table-command} {\\table}, \l {header-command} + {\\header}, \l {list-command} {\\list} and \l {o-command} {\\o}. - See also \l {table}{\\table}, \l {header}{\\header}, - \l {list}{\\list} and \l {o}{\\o}. - \endtable */ /*! - \page 11-qdoc-commands-documentcontents.html - \previouspage Container Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Miscellaneous Commands + \page 11-qdoc-commands-specialcontent.html + \previouspage Tables and Lists + \contentspage Table of Contents + \nextpage Miscellaneous - \title Document Contents Commands + \title Special Content The document contents commands identify parts of the documentation, i.e. parts with a special rendering, conceptual meaning or function. - \section1 Alphabetical List - - \l {11-qdoc-commands-documentcontents.html#abstract}{\\abstract}, - \l {11-qdoc-commands-documentcontents.html#brief}{\\brief}, - \l {11-qdoc-commands-documentcontents.html#footnote}{\\footnote}, - \l {11-qdoc-commands-documentcontents.html#legalese}{\\legalese}, - \l {11-qdoc-commands-documentcontents.html#tableofcontents} - {\\tableofcontents}, - \l {11-qdoc-commands-documentcontents.html#quotation}{\\quotation}, - \l {11-qdoc-commands-documentcontents.html#warning}{\\warning} - - \section1 Command Descriptions - - \table - \header - \o Command - \o Description - - \row - \o \bold \\abstract \target abstract - \o \bold {The \\abstract command and the corresponding \\endabstract - command delimit a document's abstract section.} - - The abstract section is rendered as an indented italicized - paragraph. + \target abstract-command + \section1 \\abstract - \warning This is preliminary funcionality. The - command is not fully implemented. Currently, the abstract - section is rendered as a regular HTML paragraph. For - example: + The \\abstract and \\endabstract commands delimit a + document's abstract section. - \code - / *! - \abstract - Qt by Trolltech is a C++ toolkit for cross-platform - GUI application development. Qt provides - single-source portability across Microsoft Windows, - Mac OS X, Linux, and all major commercial Unix - variants. It is also available for embedded - devices. - \endabstract - * / - \endcode + The abstract section is rendered as an indented italicized + paragraph. - will be rendered as - - \abstract - Qt by Trolltech is a C++ toolkit for cross-platform GUI - application development. Qt provides single-source - portability across Microsoft Windows, Mac OS X, Linux, - and all major commercial Unix variants. It is also - available for embedded devices. - \endabstract - - \row - \o \bold \\quotation \target quotation - \o \bold { The \\quotation command and the corresponding - \\endquotation command delimit a quotation remark.} - - This command replaces the old \\quote command. For more - information see the \l - {26-qdoc-commands-compatibility.html#quotation-versus-quote} - {compatibility} section. - - The remark is rendered as a separate centered - paragraph. For example: - - \code - / *! - While the prospect of a significantly broader market is - good news for Firstlogic, the notion also posed some - challenges. Dave Dobson, director of technology for the La - Crosse, Wisconsin-based company, said: - - - \quotation - As our solutions were being adopted into new - environments, we saw an escalating need for easier - integration with a wider range of enterprise - applications. - \endquotation - * / - \endcode - - will be rendered as - - While the prospect of a significantly broader market is - good news for Firstlogic, the notion also posed some - challenges. Dave Dobson, director of technology for the La - Crosse, Wisconsin-based company, said: - - \quotation - As our solutions were being adopted into new - environments, we saw an escalating need for easier - integration with a wider range of enterprise - applications. - \endquotation - - \row - \o \bold \\footnote \target footnote - \o \bold {The \\footnote command and the corresponding - \\endfootnote command delimit a footnote.} - - The footnote follows the standard conventions, rendered at the - bottom of the page. - - \warning This is preliminary funcionality. The - command is not fully implemented. - - For example: - - \code - / *! - In Qt 4 we have tried to simplify the constructors of - QObject/QWidget subclasses. This makes subclassing - easier, at the same time as it helps make the Qt - library more efficient. - - \footnote - Constructors no longer take a "const char *name" - parameter. If you want to specify a name for a QObject, - you must call QObject::setObjectName() after - construction. The object name is now a QString. - \endfootnote - - QWidget's WFlags data type has been split in two: - Qt::WindowFlags specifies low-level window flags (the - type of window and the frame style), whereas - Qt::WidgetAttribute specifies various higher-level - attributes about the widget (e.g., - WA_StaticContents). - * / - \endcode - - will be rendered as - - \quotation - In Qt 4 we have tried to simplify the constructors of - QObject/QWidget subclasses. This makes subclassing - easier, at the same time as it helps make the Qt - library more efficient. - - \footnote - Constructors no longer take a "const char *name" - parameter. If you want to specify a name for a QObject, - you must call QObject::setObjectName() after - construction. The object name is now a QString. - \endfootnote - - QWidget's WFlags data type has been split in two: - Qt::WindowFlags specifies low-level window flags (the - type of window and the frame style), whereas - Qt::WidgetAttribute specifies various higher-level - attributes about the widget (e.g., - WA_StaticContents). - \endquotation - - \row - \o \bold \\tableofcontents \target tableofcontents - \o \bold {The \\tableofcontents command generates a - table displaying the titles of the current documentation - unit's parts, chapters, sections, etc.} - - The command accepts a single optional argument: - - \code - \tableofcontents sectionN - \endcode - - where \c sectionN is the deepest section to include (by - default all sections are included). - - For example, it the documentation unit's structure looks - something like this: - - \quotation - \raw HTML - <a name="Basic Qt"> - <h1>Basic Qt</h1> - </a> - <p>This is the first part.</p> - - <a name="Getting started"> - <h2>Getting Started</h2> - </a> - This is the first part's first chapter.</p> - - <a name="Hello Qt"> - <h3>Hello Qt</h3> - </a> - <p>This is the first chapter's first section.</p> - - <a name="Making Connections"> - <h3>Making Connections</h3> - </a> - <p>This is the first chapter's second section.</p> + \warning The \bold{\\abstract} and \bold{\\endabstract} commands + have not been implemented. The abstract section is rendered as a + regular HTML paragraph. - <a name="Using the Reference Documentation"> - <h3>Using the Reference Documentation</h3> - </a> - <p>This is the first chapter's third section.</p> + \target quotation-command + \section1 \\quotation - <a name="Creating Dialogs"> - <h2>Creating Dialogs</h2> - </a> - <p>This is the first part's second chapter.</p> + The \\quotation and \\endquotation commands delimit a long quotation. - <a name="Subclassing QDialog"> - <h3>Subclassing QDialog</h3> - </a> - <p>This is the second chapter's first section.</p> + The text in the delimited block is surrounded by + \bold{<blockquote>} and \bold{</blockquote>} in the html output, + e.g.: - ... + \code + / *! + While the prospect of a significantly broader market is + good news for Firstlogic, the notion also posed some + challenges. Dave Dobson, director of technology for the La + Crosse, Wisconsin-based company, said: + + \quotation + As our solutions were being adopted into new + environments, we saw an escalating need for easier + integration with a wider range of enterprise + applications. + \endquotation + * / + \endcode - <a name="Intermediate Qt"> - <h1>Intermediate Qt</h1> - </a> - <p>This is the second part.</p> + The text in the \bold{\\quotation} block will appear in the generated HTML as: - <a name="Layout Management"> - <h2>Layout Management</h2> - </a> - <p>This is the second part's first chapter.</p> + \code + <blockquote> + <p>As our solutions were being adopted into new environments, + we saw an escalating need for easier integration with a wider + range of enterprise applications.</p> + </blockquote> + \endcode - <a name="Basic Layouts"> - <h3>Basic Layouts</h3> - </a> - <p>This is the first chapter's first section.</p> + The built-in style sheet for most browsers will render the + contents of the <blockquote> tag with left and right + indentations. The example above would be rendered as: - ... + \quotation + As our solutions were being adopted into new + environments, we saw an escalating need for easier + integration with a wider range of enterprise + applications. + \endquotation - \endraw - \endquotation + But you can redefine the \bold{<blockquote>} tag in your style.css file. - Then + This command replaces the old \\quote command. For more + information see the \l + {26-qdoc-commands-compatibility.html#quotation-versus-quote} + {compatibility} section. - \code - / *! - Contents: + \target footnote-command + \section1 \\footnote - \tableofcontents + The \\footnote and \\endfootnote commands delimit a footnote. - ... - * / - \endcode + The footnote is rendered at the bottom of the page. - will expand to + \warning The \bold{\\footnote} and \bold{\\endfootnote} commands + have not been implemented. The footnote is rendered as a regular + HTML paragraph. - \quotation - \raw HTML - <p>Contents:</p> + \target tableofcontents-command + \section1 \\tableofcontents - <ul> - <li><a href="#Basic Qt">Basic Qt</a></li> - <ul> - <li><a href="#Getting Started">Getting Started</a></li> - <ul> - <li><a href="#Hello Qt">Hello Qt</a></li> - <li><a href="#Making Connections"> - Making Connections</a></li> - <li><a href="#Using the Reference Documentation"> - Using the Reference Documentation</a></li> - </ul> - <li><a href="#Creating Dialogs">Creating Dialogs</a></li> - <ul> - <li><a href="#Subclassing QDialog"> - Subclassing QDialog</a></li> - </ul> - </ul> - <li><a href="#Intermediate Qt">Intermediate Qt</a></li> - <ul> - <li><a href="#Layout Management">Layout Management</a></li> - <ul> - <li><a href="#Basic Layouts">Basic Layouts</a></li> - </ul> - </ul> - </ul> + The \\tableofcontents command has been disabled because QDoc + now generates a table of contents automatically. - ... - \endraw - \endquotation + The automatically generated table of contents appears in the upper + righthand corner of the page. - Each table entry becomes a link to the corresponding part, - chapter or section. + \target brief-command + \section1 \\brief - \row - \o \bold \\brief \target brief - \o \bold {The \\brief command introduces a one-sentence - description of a class, namespace, header file, property - or variable.} + The \\brief command introduces a one-sentence description of a + class, namespace, header file, property or variable. - The brief text is used to introduce the documentation of - the associated object, and in lists generated using the \l - {generatelist}{\\generatelist} command. + The brief text is used to introduce the documentation of the + associated object, and in lists generated using the \l + {generatelist-command} {\\generatelist} command. - The \\brief command can be used in two significant - different ways: \l {brief class}{One for classes, - namespaces and header files}, and \l {brief property}{one - for properties and variables}. + The \\brief command can be used in two significant different ways: + \l {brief class} {One for classes, namespaces and header files}, + and \l {brief-property} {one for properties and variables}. - \target brief property + \target brief-property - When the \\brief command is used to describe a property or - a variable, the brief text must only be a sentence fragment - and start with "whether" (for boolean properties and - variables) or "the" (for any other property or variable). + When the \\brief command is used to describe a property or a + variable, the brief text must be a sentence fragment starting with + "whether" (for a boolean property or variable) or starting with + "the" (for any other property or variable). - For example the boolean QWidget::isWindow property: + For example the boolean QWidget::isWindow property: \code / *! @@ -3270,7 +3215,7 @@ * / \endcode - The latter will be rendered as + QDoc renders this as: \quotation \raw HTML @@ -3292,28 +3237,21 @@ \endlist See also \l - {QWidget::frameGeometry()}{frameGeometry()}, \l - {QWidget::rect()}{rect()}, ... + {QWidget::frameGeometry()} {frameGeometry()}, \l + {QWidget::rect()} {rect()}, ... \endquotation - \target brief class + \target brief class - When the \\brief command is used to describe a class, the - brief text should be a complete sentence and must start - like this: + When the \\brief command is used to describe a class, the brief + text should be a complete sentence and must start like this: \code The <classname> class is|provides|contains|specifies... \endcode - and likewise when the command is used for namespaces or - header files. - - \warning The brief statement is used as the first - paragraph of the detailed description. Do not repeat the - sentence. - - For example: + \warning The brief statement is used as the first paragraph of the + detailed description. Do not repeat the sentence. \code / *! @@ -3333,7 +3271,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation \raw HTML @@ -3342,7 +3280,7 @@ The PreviewWindow class is a custom widget displaying the names of its currently set window flags in a - read-only text editor. \l {preview window}{More...} + read-only text editor. \l {preview window} {More...} \raw HTML <h3>Properties</h3> @@ -3358,8 +3296,8 @@ \endraw \list - \o \l {constructor}{PreviewWindow}(QWidget *parent = 0) - \o void \l {function}{setWindowFlags}(Qt::WindowFlags flags) + \o \l {constructor} {PreviewWindow}(QWidget *parent = 0) + \o void \l {function} {setWindowFlags}(Qt::WindowFlags flags) \endlist \list @@ -3395,13 +3333,14 @@ <hr /> <h2>Detailed Description</h2> \endraw + The PreviewWindow class is a custom widget displaying the names of its currently set window flags in a read-only text editor. The PreviewWindow class inherits QWidget. The widget displays the names of its window flags set with the \l - {function}{setWindowFlags()} function. It is also + {function} {setWindowFlags()} function. It is also provided with a QPushButton that closes the window. ... @@ -3418,7 +3357,7 @@ <h3>PreviewWindow(QWidget *parent = 0)</h3> \endraw - Constructs a preview window widget with \i parent. + Constructs a preview window widget with \e parent. \target function \raw HTML @@ -3434,7 +3373,7 @@ the text in the widgets text editor. \endquotation - Using \\brief with a namespace can for example look like this: + Using \\brief in a \l{namespace-command}{\\namespace}: \code / *! @@ -3445,8 +3384,7 @@ * / \endcode - and finally using \\brief with a header file can look - something like this: + Using \\brief in a \l{headerfile-command}{\\headerfile}: \code / *! @@ -3460,107 +3398,83 @@ * / \endcode - See also \l{property}{\\property}, \l{class}{\\class}, - \l{namespace}{\\namespace} and \l{headerfile}{\\headerfile}. - - \row - \o \bold \\legalese \target legalese - \o \bold {The \\legalese command, and the corresponding \\endlegalese - command, delimit a licence agreement.} - - 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. - - Ideally, the license documentation is located where the - licensed code is used. - - Later the documentation identified by the \\legalese - command can be accumulated into a list using the \l - {generatelist}{\\generatelist} command with the \c legalese - argument. This is useful to generate an overview of all the - licenses associated with the source code. - - For example: - - \code - \ * ! - ... - - On X11, Qt also supports drops via the Motif Drag \& - Drop Protocol. The implementation incorporates some - code that was originally written by Daniel Dardailler, - and adapted for Qt by Matt Koss \<koss@napri.sk\> and - Trolltech. Here is the original copyright notice: - - \legalese - \code - - Copyright 1996 Daniel Dardailler. - - Permission to use, copy, modify, distribute, and sell - this software for any purpose is hereby granted without - fee, provided that the above copyright notice appear in - all copies and that both that copyright notice and this - permission notice appear in supporting documentation, - and that the name of Daniel Dardailler not be used in - advertising or publicity pertaining to distribution of - the software without specific, written prior - permission. Daniel Dardailler makes no representations - about the suitability of this software for any - purpose. It is provided "as is" without express or - implied warranty. - - Modifications Copyright 1999 Matt Koss, under the same - license as above. - - \ endcode - \endlegalese - * / - \endcode - - will be rendered as + See also \l{property-command} {\\property}, \l{class-command} + {\\class}, \l{namespace-command} {\\namespace} and + \l{headerfile-command} {\\headerfile}. - \quotation - ... + \target legalese-command + \section1 \\legalese - On X11, Qt also supports drops via the Motif Drag \& - Drop Protocol. The implementation incorporates some - code that was originally written by Daniel Dardailler, - and adapted for Qt by Matt Koss \<koss@napri.sk\> and - Trolltech. Here is the original copyright notice: + The \\legalese and \\endlegalese commands delimit a licence agreement. - \legalese - \code - - Copyright 1996 Daniel Dardailler. + In the generated HTML, the delimited text is surrounded by a \bold + {<div class="LegaleseLeft">} and \bold {</div>} tags. - Permission to use, copy, modify, distribute, and sell - this software for any purpose is hereby granted without - fee, provided that the above copyright notice appear in - all copies and that both that copyright notice and this - permission notice appear in supporting documentation, - and that the name of Daniel Dardailler not be used in - advertising or publicity pertaining to distribution of - the software without specific, written prior - permission. Daniel Dardailler makes no representations - about the suitability of this software for any - purpose. It is provided "as is" without express or - implied warranty. + For example, here is a license agreement enclosed in \\legalese + and \\endlegalese: - Modifications Copyright 1999 Matt Koss, under the same - license as above. - - \endcode - \endlegalese - \endquotation - - \row - \o \bold \\warning \target warning - \o \bold {The \\warning command renders a "Warning:" prefix to - the command's argument.} + \code + / *! + \legalese + Copyright 1996 Daniel Dardailler. + + Permission to use, copy, modify, distribute, and sell this + software for any purpose is hereby granted without fee, + provided that the above copyright notice appear in all + copies and that both that copyright notice and this + permission notice appear in supporting documentation, and + that the name of Daniel Dardailler not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Daniel + Dardailler makes no representations about the suitability of + this software for any purpose. It is provided "as is" + without express or implied warranty. + + Modifications Copyright 1999 Matt Koss, under the same + license as above. + \endlegalese + * / + \endcode - For example: + It will appear in the generated HTML as: + + \code + <div class="LegaleseLeft"> + <p>Copyright 1996 Daniel Dardailler.</p> + <p>Permission to use, copy, modify, distribute, and sell + this software for any purpose is hereby granted without fee, + provided that the above copyright notice appear in all + copies and that both that copyright notice and this + permission notice appear in supporting documentation, and + that the name of Daniel Dardailler not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Daniel + Dardailler makes no representations about the suitability of + this software for any purpose. It is provided "as is" + without express or implied warranty.</p> + + <p>Modifications Copyright 1999 Matt Koss, under the same + license as above.</p> + </div> + \endcode + + 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. + + \target warning-command + \section1 \\warning + + The \\warning command prepends "Warning:" to the command's + argument, in bold font. \code / *! @@ -3573,7 +3487,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation Qt::HANDLE is a platform-specific handle type @@ -3583,50 +3497,31 @@ \warning Using this type is not portable. \endquotation - \endtable + */ /*! \page 12-0-qdoc-commands-miscellaneous.html - \previouspage Document Contents Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Topical Commands + \previouspage Special Content + \contentspage Table of Contents + \nextpage The QDoc Configuration File - \title Miscellaneous Commands + \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. - \section1 Alphabetical List + \target expire-command + \section1 \\expire - \l {12-0-qdoc-commands-miscellaneous.html#else}{\\else}, - \l {12-0-qdoc-commands-miscellaneous.html#endif}{\\endif}, - \l {12-0-qdoc-commands-miscellaneous.html#expire}{\\expire}, - \l {12-0-qdoc-commands-miscellaneous.html#generatelist}{\\generatelist}, - \l {12-0-qdoc-commands-miscellaneous.html#if}{\\if}, - \l {12-0-qdoc-commands-miscellaneous.html#include}{\\include}, - \l {12-0-qdoc-commands-miscellaneous.html#meta}{\\meta}, - \l {12-0-qdoc-commands-miscellaneous.html#omit}{\\omit}, - \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\raw}, - \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\unicode} + The \\expire command allows you to define an expiration + date for your documentation. - \section1 Command Descriptions - - \table - \header - \o Command - \o Description - - \row - \o \bold \\expire \target expire - \o \bold {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 / *! @@ -3645,23 +3540,24 @@ * / \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 \endquotation - \row - \o \bold \\generatelist \target generatelist - \o \bold {The \\generatelist command expands to a list of - various documentation or links to documentation.} - For example in the Qt Reference Documentation: + \target generatelist-command + \section1 \\generatelist + + The \\generatelist command expands to a list of various + documentation or links to documentation. Below is an example from + the Qt Reference Documentation: \code / *! \page classes.html - \title All Qt Classes (main index) + \title All Classes For a shorter list that only includes the most frequently used classes, see \l{Qt's Main Classes}. For @@ -3672,434 +3568,308 @@ * / \endcode - is used to generate \l {All Qt Classes (main index)}. - - The command accepts the following arguments: - - \target table example - - \list - \o \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: - - \quotation - \raw HTML - <table align="center" cellpadding="2" - cellspacing="1" border="0"> - - <tr valign="top" bgcolor="#d0d0d0"> - <td> - <a href="http://qt.nokia.com/doc/4.0/qdial.html"> - QDial</a> - </td> - <td>Rounded range control (like a speedometer - or potentiometer)</td> - </tr> - - <tr valign="top" bgcolor="#d0d0d0"> - <td> - <a href="http://qt.nokia.com/doc/4.0/qdialog.html"> - QDialog</a> - </td> - <td>The base class of dialog windows</td> - </tr> - - <tr valign="top" bgcolor="#d0d0d0"> - <td> - <a href="http://qt.nokia.com/doc/4.0/qdir.html"> - QDir</a> - </td> - <td>Access to directory structures and their - contents</td> - </tr> - </table> - \endraw - \endquotation - - A class is identified within the documentation by the - the \l {class}{\\class} command, and the descriptions - are based on the argument of the \l {brief}{\\brief} - commands in the class documentation. - - \target list example - - \o \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 - <p><table width="100%"> - - <tr> - <td align="right"><b>A </b></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstractbutton.html">QAbstractButton</a></td> + This generates the \l {All Classes} page. The command accepts the + following arguments: - <td align="right"></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstractextensionmanager.html">QAbstractExtensionManager</a></td> - - <td align="right"></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstractitemmodel.html">QAbstractItemModel</a></td> - </tr> - - <tr> - <td align="right"></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstracteventdispatcher.html">QAbstractEventDispatcher</a></td> + \target table example + \section2 \c annotatedclasses - <td align="right"></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstractformbuilder.html">QAbstractFormBuilder</a></td> - - <td align="right"></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstractitemview.html">QAbstractItemView</a></td> - </tr> + 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: - <tr> - <td align="right"></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstractextensionfactory.html">QAbstractExtensionFactory</a></td> - - <td align="right"></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstractitemdelegate.html">QAbstractItemDelegate</a></td> - - <td align="right"></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstractlistmodel.html">QAbstractListModel</a></td> - </tr> - </table></p> - \endraw - \endquotation - - A class is identified within the documentation by the - the \l {class}{\\class} command. - - \o \c classesbymodule + \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 - This particular argument requests an additional argument, - i.e. a specification of the module. + 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. - For example: + \target list example + \section2 \c classes - \code - / *! - \page qtgui.html - \contentspage Qt Classes by Module - \previouspage QtCore Classes - \nextpage QtNetwork 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. This command is uded to generate the \l + {classes.html} {All Classes} page this way: - \title QtGui Classes + \code + / *! + \page classes.html + \title All Classes + \ingroup classlists - \keyword QtGui + \brief If you know the name of the class you want, find it here. - \generatelist {classesbymodule QtGui} - * / - \endcode + This is a list of all Qt classes. For a list of the classes + provided for compatibility with Qt3, see \l{Qt3 Support + Classes}. For classes that have been deprecated, see the + \l{Obsolete Classes} list. - 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. + \generatelist classes + * / + \endcode - 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}{\\inmodule} command. + \section2 \c classesbymodule - \o \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 - \o \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}{\\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: - \o \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 - <p><center><font size="+1"><b><a href="#a">A</a> <a href="#b">B</a> <a href="#c">C</a> <a href="#d">D</a> <a href="#e">E</a> <a href="#f">F</a> <a href="#g">G</a> <a href="#h">H</a> <a href="#i">I</a> <a href="#j">J</a> <a href="#k">K</a> <a href="#l">L</a> <a href="#m">M</a> <a href="#n">N</a> <a href="#o">O</a> <a href="#p">P</a> <a href="#q">Q</a> <a href="#r">R</a> <a href="#s">S</a> <a href="#t">T</a> <a href="#u">U</a> <a href="#v">V</a> <a href="#w">W</a> <a href="#x">X</a> <a href="#y">Y</a> <a href="#z">Z</a> </b></font></center></p> + \generatelist compatclasses + * / + \endcode - <p>DTDHandler: <a href="http://qt.nokia.com/doc/4.0/qxmlreader.html#DTDHandler">QXmlReader</a></p> + A support class is identified in the \\class comment with the \l + {compat-command} {\\compat} command. - <p>QAXCLASS: <a href="http://qt.nokia.com/doc/4.0/qaxfactory.html#QAXCLASS">global</a></p> + \section2 \c functionindex - <p>QAXFACTORY_BEGIN: <a href="http://qt.nokia.com/doc/4.0/qaxfactory.html#QAXFACTORY_BEGIN">global</a></p> + 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: - <p>QAXFACTORY_DEFAULT: <a href="http://qt.nokia.com/doc/4.0/qaxfactory.html#QAXFACTORY_DEFAULT">global</a></p> + \code + / *! + \page functions.html + \title All Functions + \ingroup funclists - <p>QAXFACTORY_END: <a href="http://qt.nokia.com/doc/4.0/qaxfactory.html#QAXFACTORY_END">global</a></p> + \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 - - \o \c legalese - - The \c legalese argument provides a complete list of all - the licenses. The licenses are identified within the - documentation using the \l {legalese}{\\legalese} - command. - - For example: - - \quotation - \raw HTML - <hr /> - <p> - Copyright (c) 1989 The Regents of the - University of California. All rights reserved. - </p> - - <p> - Redistribution and use in source and binary - forms are permitted provided that the above - copyright notice and this paragraph are - duplicated in all such forms and that any - documentation, advertising materials, and other - materials related to such distribution and use - acknowledge that the software was developed by - the University of California, Berkeley... - </p> - - <ul> - <li> - <a href="http://qt.nokia.com/doc/4.0/qdate.html#weekNumber">QDate::weekNumber()</a> - </li> - </ul> - - <hr /> - <p> - Copyright (c) 1991 by AT&T. - </p> - - <p> - Permission to use, copy, modify, and distribute - this software for any purpose without fee is - hereby granted, provided that this entire notice - is included in all copies of any software which - is or includes a copy or modification of this - software and in all copies of the supporting - documentation for such software... - </p> - - <ul> - <li> - <a href="http://qt.nokia.com/doc/4.0/qlocale.html">QLocale</a> - </li> - </ul> - <hr /> - \endraw - ... - \endquotation + \generatelist functionindex + * / + \endcode - \o \c mainclasses + \section2 \c legalese - The \c mainclasses argument provides a complete - alphabetical list of the main classes. Each class name - is a link to the class's reference documentation. A - class is related to the group of main classes by using - the \l {mainclass}{\\mainclass} command. + The \c legalese argument tells QDoc to generate a complete list of + licenses in the documentation. Each license is identified using + the \l {legalese-command} {\\legalese} command. This command is + used to generate the \l {licenses.html} {Qt license information} + page this way: - The list is rendered similarily to the list generated by - the \l {list example}{\c classes} argument. + \code + / *! + \page licenses.html + \title Other Licenses Used in Qt + \ingroup licensing + \brief Information about other licenses used for Qt components and third-party code. + + Qt contains some code that is not provided under the + \l{GNU General Public License (GPL)}, + \l{GNU Lesser General Public License (LGPL)} or the + \l{Qt Commercial Edition}{Qt Commercial License Agreement}, but rather under + specific licenses from the original authors. Some pieces of code were developed + by Nokia and others originated from third parties. + This page lists the licenses used, names the authors, and links + to the places where it is used. + + Nokia gratefully acknowledges these and other contributions + to Qt. We recommend that programs that use Qt also acknowledge + these contributions, and quote these license statements in an + appendix to the documentation. + + See also: \l{Licenses for Fonts Used in Qt for Embedded Linux} + + \generatelist legalese + * / + \endcode - \o \c overviews + \section2 \c mainclasses - The \c overviews argument provides a complete - alphabetical overview of the documentation. Each list - entry is a link to the respective documentation page. + The \c mainclasses argument tells QDoc to generate an alphabetical + list of the main classes. A class is marked as a main class by + including a \l {mainclass-command} {\\mainclass} command in the + \\class comment. - The list includes pages declared using commands like \l - {page}{\\page} and \l {group}{\\group}. The list omits - examples and classes, and only lists the first page of - documentation that contains two or more pages using - commands like \l {nextpage}{\\nextpage}. + \note The Qt documentation no longer includes a main classes page, + but you can generate one for your main classes if you want it. - For example: + \section2 \c overviews - \quotation - \raw HTML - <ul> + The \c overviews argument is used to tell QDoc to generate a list + by concatenating the contents of all the \l {group-command} + {\\group} pages. Qt uses it to generate the \l {overviews.html} + {overviews} page this way: - <li> - <a href="http://qt.nokia.com/doc/4.0/qtalgorithms.html"> - <QtAlgorithms> - Generic Algorithms - </a> - </li> + \code + / *! + \page overviews.html - <li> - <a href="http://qt.nokia.com/doc/4.0/qtglobal.html"> - <QtGlobal> - Global Qt Declarations - </a> - </li> + \title All Overviews and HOWTOs - <li> - <a href="http://qt.nokia.com/doc/4.0/qaxserver-demo-simple.html"> - A standard ActiveX and the "simple" ActiveQt widget - </a> - </li> + \generatelist overviews + * / + \endcode - <li> - <a href="http://qt.nokia.com/doc/4.0/aboutqt.html"> - About Qt - </a> - </li> + \section2 \c related - <li> - <a href="http://qt.nokia.com/doc/4.0/trolltech.html"> - About Trolltech - </a> - </li> + The \c related argument is used in combination with the \l + {group-command} {\\group} and \l {ingroup-command} {\\ingroup} + commands to list all the overviews related to a specified + group. For example, the page for the \l {Programming with Qt} + {Programming with Qt} page is generated this way: - <li> - <a href="http://qt.nokia.com/doc/4.0/abstractwidgets.html"> - Abstract Widget Classes - </a> - </li> + \code + / *! + \group qt-basic-concepts + \title Programming with Qt - <li> - <a href="http://qt.nokia.com/doc/4.0/accessibility.html"> - Accessibility Classes - </a> - </li> - ... - </ul> - \endraw - \endquotation + \brief The basic architecture of the Qt cross-platform application and UI framework. - \o \c related + Qt is a cross-platform application and UI framework for + writing web-enabled applications for desktop, mobile, and + embedded operating systems. This page contains links to + articles and overviews explaining key components and + techniuqes used in Qt development. - The \c related argument is used in combination with the - \l {group}{\\group} command to list all the overviews - related to the given group. Each list entry is a link to - the respective documentation page. + \generatelist {related} + * / + \endcode - \o \c relatedinline + Each page listed on this group page contains the command: - The \c related argument is used in combination with the - \l {group}{\\group} command to collect all documentation - related to the given group. The various documentation - snippets are copied directly into the group page. + \code + \ingroup qt-basic-concepts + \endcode - \o \c service + \section2 \c service - The \c service argument provides a complete alphabetical - list of the services. Each service name is a link to the - service's reference documentation. + The \c service argument tells QDoc to generate an alphabetical + list of the services. Each service name is a link to the service's + reference documentation. - A service is identified within the documentation by the - \l {service}{\\service} command. + A service is identified with the \l {service-command} {\\service} + command. - \endlist + \note This command and the \l {service-command} {\\service} + command are not used in the Qt documentation. + \target if-command + \section1 \\if - \row - \o \bold \\if \target if - \o \bold {The \\if command and the corresponding \\endif command - enclose parts of a QDoc comment that only will be included if - the condition specified by the command's argument is true.} + The \\if command and the corresponding \\endif command + enclose parts of a QDoc comment that only will be included if + 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: + The command reads the rest of the line and parses it as an C++ #if + statement. \code / *! \if defined(opensourceedition) \bold{Note:} This edition is for the development of - \l{Qt Open Source Edition}{Free and Open Source} + \l{Qt Open Source Edition} {Free and Open Source} software only; see \l{Qt Commercial Editions}. \endif * / \endcode - This QDoc comment will only be rendered if the \c - opensourceedition preprocessor symbol is defined, and - specified in the \l {definesvariable}{defines} variable in - the configuration file to make QDoc process - the code within #ifdef and #endif: + This QDoc comment will only be rendered if the \c + opensourceedition preprocessor symbol is defined, and specified in + the \l {defines-variable} {defines} variable in the configuration + file to make QDoc process the code within #ifdef and #endif: \code defines = opensourceedition \endcode - You can also define the preprocessor symbol manually on the - command line. For more information see the documentation of - the \l {definesvariable}{defines} variable. + You can also define the preprocessor symbol manually on the + command line. For more information see the documentation of the \l + {defines-variable} {defines} variable. - See also \l{endif}{\\endif}, \l{else}{\\else}, \l - {definesvariable}{defines} and \l falsehoods. + See also \l{endif-command} {\\endif}, \l{else-command} {\\else}, + \l {defines-variable} {defines} and \l {falsehoods-variable} + {falsehoods}. - \row - \o \bold \\endif \target endif - \o \bold {The \\endif command and the corresponding \\if command - enclose parts of a QDoc comment that will be included if - the condition specified by the \l {if}{\\if} command's - argument is true.} + \target endif-command + \section1 \\endif - For more information, see the documentation of the \l - {if}{\\if} command. + The \\endif command and the corresponding \\if command + enclose parts of a QDoc comment that will be included if + the condition specified by the \l {if-command} {\\if} command's + argument is true. - See also \l{if}{\\if}, \l{else}{\\else}, \l - {definesvariable}{defines} and \l falsehoods. + For more information, see the documentation of the \l {if-command} + {\\if} command. - \row - \o \bold \\else \target else - \o \bold {The \\else command specifies an alternative if the - condition in the \l {if}{\\if} command is false.} + See also \l{if-command} {\\if}, \l{else-command} {\\else}, \l + {defines-variable} {defines} and \l {falsehoods-variable} + {falsehoods}. + + \target else-command + \section1 \\else + + The \\else command specifies an alternative if the + condition in the \l {if-command} {\\if} command is false. - The \\else command can only be used within \l - {if}{\\if...\\endif} commands, but is useful when there is - only two alternatives. For example: + The \\else command can only be used within \l {if-command} + {\\if...\\endif} commands, but is useful when there is only two + alternatives. \code / *! @@ -4134,8 +3904,8 @@ * / \endcode - If the \c QT3_SUPPORT is defined, the comment will be rendered - as + If the \c QT3_SUPPORT is defined, the comment will be rendered + like this: \quotation The Qt 3 support library is provided to keep old source @@ -4146,8 +3916,8 @@ API to cohabit with the new one. \endquotation - If \c QT3_SUPPORT isn't defined but \c QT3_SUPPORT_WARNINGS - is, the comment will be rendered as + If \c QT3_SUPPORT is not defined but \c QT3_SUPPORT_WARNINGS is + defined, the comment will be rendered like this: \quotation The Qt 3 support library is provided to keep old source @@ -4186,32 +3956,35 @@ GCC 3.2+ and MSVC 7.) \endquotation - See also \l{if}{\\if}, \l{endif}{\\endif}, \l - {definesvariable}{defines} and \l falsehoods. - - \row - \o \bold \\include \target include - \o \bold {The \\include command expands to the contents of the - file specified by the command's argument.} - - \warning This is preliminary functionality. For more - information, see the \l - {26-qdoc-commands-compatibility.html#include-versus-input} - {compatibility} section. - - The command takes a file name as an argument, and is - useful when some piece of the documentation is used - repeatedly: Move the repetetive text into a separate file, - and use the \\include command whenever you want to insert - the separate documentation. - - The contents of such a file should follow QDoc syntax, - excluding 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: + See also \l{if-command} {\\if}, \l{endif-command} {\\endif}, \l + {defines-variable} {defines} and \l {falsehoods-variable} + {falsehoods}. + + \target include-command + \section1 \\include + + The \\include command sends all or part of the file specified by + its first argument to the QDoc input stream to be processed as a + qdoc comment snippet. This command is often assigned the alias, + \e {input}, in the QDoc configuration file, e.g. \e {alias.include + = input}. + + The command is useful when some snippet of commands and text is to + be used in multiple places in the documentation. In that case, + move the snippet into a separate file and use the \\include + command wherever you want to insert the snippet into the + documentation. To prevent QDoc from reading the file as a + stand-alone page of documentation, we recommend that you use the + \c .qdocinc extension for these \e {include} files. + + The command can have either one or two arguments. The first + argument is always a file name. The contents of the file must be + QDoc input, i.e. a sequence of QDoc commands and text, but without + the enclosing qdoc comment \c{/}\c{*!} ... \c{*}\c{/} delimeters. + If you want to include the entire named file, don't use the second + argument. If you want to include only part of the file, see the + \l{2-argument-form}{two argument form} below. Here is an example + of the one argument form: \code / *! @@ -4224,33 +3997,65 @@ * / \endcode - will be rendered as + Here are links to the \c .qdocinc files used above: + \l{signalandslots.qdocinc}, \l{objectmodel.qdocinc}, + \l{layoutmanagement.qdocinc}. QDoc renders this page as: \quotation \raw HTML <h1>Core Features</h1> \endraw - \include examples/signalandslots.qdocinc - \include examples/objectmodel.qdocinc - \include examples/layoutmanagement.qdocinc + \input examples/signalandslots.qdocinc + \input examples/objectmodel.qdocinc + \input examples/layoutmanagement.qdocinc \endquotation - Here is the actual \c .qdocinc files: \l - signalandslots.qdocinc, \l objectmodel.qdocinc, \l - layoutmanagement.qdocinc + \target 2-argument-form} + \section2 \\include filename snippet-identifier - \row - \o \bold \\meta \target meta - \o \bold {The \\meta command is the QDoc equivalent to the HTML - \c meta tag.} + It is kind of a pain to make a separate \c .qdocinc file for every + QDoc include snippet you want to use in multiple places in the + documentation, especially given that you probably have to put the + copyright/license notice in every one of these files. So if you + have lots of these include snippets, you can put them all in a + single file if you want, and surround each one with: + \code + //! [snippet-id1] + + QDoc commands and text... + + //! [snippet-id1] + + //! [snippet-id2] + + More QDoc commands and text... + + //! [snippet-id2] + \endcode + + Then you can use the two-argument form of the command: + + \code + \input examples/signalandslots.qdocinc snippet-id2 + \input examples/objectmodel.qdocinc another-snippet-id + \endcode + + It works as expected. The sequence of QDoc commands and text found + between the two tags with the same name as the second argument is + sent to the QDoc input stream. You can even nest these snippets, + although it's not clear why you would want to do that. - The command accepts two arguments: The first argument (the - following word) is equivalent to the HTML meta tag's \i - name variable, and the second argument (the rest of the - line) is equivalent to the tag's \i contents variable. + \target meta-command + \section1 \\meta - For example: + The \\meta command is the QDoc equivalent to the HTML + \c meta tag. + + 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. \code / *! @@ -4274,7 +4079,7 @@ * / \endcode - will be included in the generated HTML page as + QDoc renders this as: \code <head> @@ -4284,13 +4089,12 @@ </head> \endcode - \row - \o \bold \\omit \target omit - \o \bold {The \\omit command and the correspondning \\endomit - command delimit parts of the documentation that - you want QDoc to skip.} + \target omit-command + \section1 \\omit - For example: + The \\omit command and the correspondning \\endomit command + delimit parts of the documentation that you want QDoc to skip. For + example: \code / *! @@ -4314,7 +4118,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \raw HTML <table align="center" cellpadding="2" @@ -4333,94 +4137,115 @@ </table> \endraw + \target raw-command + \section1 \\raw \span {class="newStuff"} {(avoid)} - \row - \o \bold \\raw \target raw - \o \bold {The \\raw command and the corresponding - \\endraw command delimit a block of raw mark-up language code.} + The \\raw command and the corresponding + \\endraw command delimit a block of raw mark-up language code. - The command takes an argument specifying the code's format; - currently the only supported format is HTML. + \note Avoid using this command if possible, because it generates + DITA XML code that causes problems. If you are trying to generate + special table or list behavior, try to get the behavior you want + using the \l {span-command} {\\span} and \l {div-command} {\\div} + commands in your \l {table-command} {\\table} or \l {list-command} + {\\list}. + + The command takes an argument specifying the code's format; + currently the only supported format is HTML. - The \\raw command is useful if you want some special HTML - effects in your documentation. For example: + The \\raw command is useful if you want some special HTML effects + in your documentation. \code / *! - Qt has some predefined QColor objects. For example: + Qt has some predefined QColor objects. \raw HTML <style type="text/css" id="colorstyles"> - #blue { background-color: #0000ff; color: #ffffff } - #darkBlue { background-color: #000080; color: #ffffff } - #cyan { background-color: #00ffff; color: #000000 } + #color-blue { background-color: #0000ff; color: #ffffff } + #color-darkBlue { background-color: #000080; color: #ffffff } + #color-cyan { background-color: #00ffff; color: #000000 } </style> <p> - <tt id="blue">Blue(#0000ff)</tt>, - <tt id="darkBlue">dark blue(#000080)</tt> and - <tt id="cyan">cyan(#00ffff)</tt>. + <tt id="color-blue">Blue(#0000ff)</tt>, + <tt id="color-darkBlue">dark blue(#000080)</tt> and + <tt id="color-cyan">cyan(#00ffff)</tt>. + </p> \endraw * / \endcode - will be rendered as + QDoc renders this as: \quotation - Qt has some predefined QColor objects. For example: + Qt has some predefined QColor objects. \raw HTML <style type="text/css" id="colorstyles"> - #blue { background-color: #0000ff; color: #ffffff } - #darkBlue { background-color: #000080; color: #ffffff } - #cyan { background-color: #00ffff; color: #000000 } + #color-blue { background-color: #0000ff; color: #ffffff } + #color-darkBlue { background-color: #000080; color: #ffffff } + #color-cyan { background-color: #00ffff; color: #000000 } </style> <p> - <tt id="blue">Blue(#0000ff)</tt>, - <tt id="darkBlue">dark blue(#000080)</tt> and - <tt id="cyan">cyan(#00ffff)</tt>. + <tt id="color-blue">Blue(#0000ff)</tt>, + <tt id="color-darkBlue">dark blue(#000080)</tt> and + <tt id="color-cyan">cyan(#00ffff)</tt>. + </p> \endraw \endquotation - \row - \o \bold \\unicode \target unicode - \o \bold {The \\unicode command allows you to insert an - arbitrary Unicode character in the document.} + \note But you can achieve the exact same thing using qdoc + commands. In this case, all you have to do is include the color + styles in your style.css file. Then you can write: + + \code + \tt {\span {id="color-blue"} {Blue(#0000ff)}}, + \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and + \tt {\span {id="color-cyan"} {cyan(#00ffff)}}. + \endcode + + ...which is rendered again as: - The command takes an argument specifying the character as - an integer. By default, base 10 is assumed, unless a '0x' - or '0' prefix is specified (for base 16 and 8, - respectively). For example: + \tt {\span {id="color-blue"} {Blue(#0000ff)}}, + \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and + \tt {\span {id="color-cyan"} {cyan(#00ffff)}}. + + \target unicode-command + \section1 \\unicode + + The \\unicode command allows you to insert an arbitrary Unicode + character in the document. + + The command takes an argument specifying the character as an + integer. By default, base 10 is assumed, unless a '0x' or '0' + prefix is specified (for base 16 and 8, respectively). For + example: \code O G\unicode{0xEA}nio e as Rosas \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour - \unicode 0x3A3 \i{a}\sub{\i{i}} + \unicode 0x3A3 \e{a}\sub{\e{i}} \endcode - will be rendered as + QDoc renders this as: \quotation O G\unicode{0xEA}nio e as Rosas \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour - \unicode 0x3A3 \i{a}\sub{\i{i}} + \unicode 0x3A3 \e{a}\sub{\e{i}} \endquotation - - The \\raw command follows the same conventions as the \l - {i}{\\i} command for \l {argument}{punctuation and use of - braces} for the argument. - \endtable */ /*! \page 12-1-signalandslots.html - \previouspage Miscellaneous Commands - \contentspage QDoc Manual - Table of Contents + \previouspage Miscellaneous + \contentspage Table of Contents \title signalandslots.qdocinc @@ -4429,8 +4254,8 @@ /*! \page 12-2-objectmodel.html - \previouspage Miscellaneous Commands - \contentspage QDoc Manual - Table of Contents + \previouspage Miscellaneous + \contentspage Table of Contents \title objectmodel.qdocinc @@ -4439,8 +4264,8 @@ /*! \page 12-3-layoutmanagement.html - \previouspage Miscellaneous Commands - \contentspage QDoc Manual - Table of Contents + \previouspage Miscellaneous + \contentspage Table of Contents \title layoutmanagement.qdocinc @@ -4448,71 +4273,54 @@ */ /*! - \page 13-qdoc-commands-topical.html - \previouspage Miscellaneous Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Contextual Commands - - \title Topical Commands - - The topical commands tell QDoc what is being documented - (i.e. existing units like classes, functions and examples), and - some of the commands allows you to create extra pages. - - \section1 Alphabetical List - - \l {13-qdoc-commands-topical.html#class}{\\class}, - \l {13-qdoc-commands-topical.html#enum}{\\enum}, - \l {13-qdoc-commands-topical.html#example-command}{\\example}, - \l {13-qdoc-commands-topical.html#externalpage}{\\externalpage}, - \l {13-qdoc-commands-topical.html#fn}{\\fn}, - \l {13-qdoc-commands-topical.html#group}{\\group}, - \l {13-qdoc-commands-topical.html#headerfile}{\\headerfile}, - \l {13-qdoc-commands-topical.html#macro}{\\macro}, - \l {13-qdoc-commands-topical.html#module}{\\module}, - \l {13-qdoc-commands-topical.html#namespace}{\\namespace}, - \l {13-qdoc-commands-topical.html#page}{\\page}, - \l {13-qdoc-commands-topical.html#property}{\\property}, - \l {13-qdoc-commands-topical.html#service}{\\service}, - \l {13-qdoc-commands-topical.html#typedef}{\\typedef}, - \l {13-qdoc-commands-topical.html#variable}{\\variable}, + \page 13-qdoc-commands-topics.html + \previouspage Command Index + \contentspage Table of Contents + \nextpage Context Commands - \section1 General Description + \title Topic Commands - When QDoc is processing a comment, it will try to connect the - documentation to the source code. For that reason it will first - look for the topical commands. If there is no such command, it - will try to tie the documentation to the immediately following - code. If there is no topical command, and the documentation cannot - be tied to following code, the documentation is simply lost. + A topic command tells QDoc which source code element is being + documented. Some topic commands allow you to create documentation + pages that aren't tied to any underlying source code element. - \target topical argument + When QDoc processes a QDoc comment, it tries to connect the + comment to an element in the source code by first looking for a + topic command that names the source code element. If there is no + topic command, QDoc tries to connect the comment to the source + code element that immediately follows the comment. If it can't do + either of these and if there is no topic command that indicates + the comment does not have an underlying source code element (e.g. + \l{page-command} {\\page}), then the comment is discarded. - The documented unit's name is passed as the unique argument for - all the topical commands. The argument's naming convention is the - documented unit's complete name. For example: + \target topic argument + + The name of the thing being documented is the unique argument for + each topic command. The naming convention is to use the complete + name. \code \enum QComboBox::InsertPolicy \endcode - Functions is a special case, the argument's naming convention for - the \l {fn}{\\fn} command is that of the function's definition - outside the class definition. For example: + The \l {fn-command} {\\fn} command is a special case. For the \l + {fn-command} {\\fn} command, use the function's signature + including the class qualifier. \code - \fn void PreviewWindow::setWindowFlags() + \fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags) \endcode - A topical command can appear anywhere in a comment, but must stand - alone on its own line. If the argument spans several lines, make - sure that each line (except the last one) is ended with a + A topic command can appear anywhere in a comment but must stand + alone on its own line. Best practice is to put the topic commend + at the top of the comment. If the argument spans several lines, + make sure that each line (except the last one) is ended with a backslash. In addition QDoc counts parentheses, which means that if it encounters a '(' it considers everything until the closing ')' as its argument. - If a topical command is repeated with different arguments, the - same documentation will appear for both the units. For example: + If a topic command is repeated with different arguments, the + same documentation will appear for both the units. \code / *! @@ -4532,232 +4340,224 @@ ControllerWindow::setWindowFlags() functions will get the same documentation. - \section1 Command Descriptions + \target class-command + \section1 \\class - \table - \header - \o Command - \o Description - - \row - \o \bold \\class \target class - \o \bold {The \\class command tells QDoc that a class is - part of the public API, and lets you enter a detailed - description.} + The \\class command is for documenting a C++ class. The argument + is the complete name of the class. The command tells QDoc that a + class is part of the public API, and lets you enter a detailed + description. - The command follows \l {topical argument}{the general - topical command convention} for the argument, and supports - nested classes, for example: - - \code - / *! - \class QMap::iterator + \code + / *! + \class QMap::iterator - \brief The QMap::iterator class provides an STL-style - non-const iterator for QMap and QMultiMap. + \brief The QMap::iterator class provides an STL-style + non-const iterator for QMap and QMultiMap. - QMap features both \l{STL-style iterators} and - \l{Java-style iterators}. The STL-style iterators ... - * / - \endcode + QMap features both \l{STL-style iterators} and + \l{Java-style iterators}. The STL-style iterators ... + * / + \endcode - The generated HTML documentation for the specified class is - put in \c <lower-case>classname.html. For example, the - documentation for the \c PreviewWindow class is located in - \c previewwindow.html. + The HTML documentation for the named class is written to a + \c{.html} file named from the class name, in lower case, and with + the double colon qulifier(s) replaced with '-'. For example, the + documentation for the \c QMap::Iterator class is written to \c + qmap-iterator.html. - \target framework + \target framework - In addition to render the detailed description, the \\class - comand will generate the documentation framework, i.e. a - list of the class's types, properties, functions, signals - and slots with empty documentation. + The file contains the class description from the \\class comment, + plus the documentation generated from QDoc comments for all the + class members, i.e. a list of the class's types, properties, + functions, signals, and slots. - The command is typically accompanied with a \l - {brief}{\\brief} command, a \l {mainclass}{\\mainclass} - command, an \l {ingroup}{\\ingroup} command and a \l - {sa}{\\sa} command. For example: + In addition to the detailed description of the class, the \\class + comment typically contains a \l {brief-command} {\\brief} command + and one or more \l{Markup Commands}. See the \\class command for + any of the Qt class for examples. Here is a very simple example: - \code - / *! - \class PreviewWindow - \brief The PreviewWindow class is a custom widget - displaying the names of its currently set - window flags in a read-only text editor. + \code + / *! + \class PreviewWindow + \brief The PreviewWindow class is a custom widget + displaying the names of its currently set + window flags in a read-only text editor. - \mainclass - \ingroup miscellaneous + \ingroup miscellaneous - The PreviewWindow class inherits QWidget. The widget - displays the names of its window flags set with the \l - {function}{setWindowFlags()} function. It is also - provided with a QPushButton that closes the window. + The PreviewWindow class inherits QWidget. The widget + displays the names of its window flags set with the \l + {function} {setWindowFlags()} function. It is also + provided with a QPushButton that closes the window. - ... + ... - \sa QWidget - * / - \endcode + \sa QWidget + * / + \endcode - will be rendered as + The way QDoc renders this \\class will depend a lot on your \c + {style.css} file, but the general outline of the class reference + page will look like this: - \quotation - \raw HTML - <h1>PreviewWindow Class Reference</h1> - \endraw - - The PreviewWindow class is a custom widget displaying - the names of its currently set window flags in a - read-only text editor. \l {preview window}{More...} + \quotation + \raw HTML + <h1>PreviewWindow Class Reference</h1> + \endraw - \raw HTML - <h3>Properties</h3> - \endraw + The PreviewWindow class is a custom widget displaying + the names of its currently set window flags in a + read-only text editor. \l {preview window} {More...} - \list - \o 52 properties inherited from QWidget - \o 1 property inherited from QObject - \endlist + \raw HTML + <h3>Properties</h3> + \endraw - \raw HTML - <h3>Public Functions</h3> - \endraw + \list + \o 52 properties inherited from QWidget + \o 1 property inherited from QObject + \endlist - \list - \o \l {constructor}{PreviewWindow}(QWidget *parent = 0) - \o void \l {function}{setWindowFlags}(Qt::WindowFlags flags) - \endlist + \raw HTML + <h3>Public Functions</h3> + \endraw - \list - \o 183 public functions inherited from QWidget - \o 28 public functions inherited from QObject - \endlist + \list + \o \l {constructor} {PreviewWindow}(QWidget *parent = 0) + \o void \l {function} {setWindowFlags}(Qt::WindowFlags flags) + \endlist - \raw HTML - <h3>Public Slots</h3> - \endraw + \list + \o 183 public functions inherited from QWidget + \o 28 public functions inherited from QObject + \endlist - \list - \o 17 public slots inherited from QWidget - \o 1 public slot inherited from QObject - \endlist + \raw HTML + <h3>Public Slots</h3> + \endraw - \raw HTML - <h3>Additional Inherited Members</h3> - \endraw + \list + \o 17 public slots inherited from QWidget + \o 1 public slot inherited from QObject + \endlist - \list - \o 1 signal inherited from QWidget - \o 1 signal inherited from QObject - \o 4 static public members inherited from QWidget - \o 4 static public members inherited from QObject - \o 39 protected functions inherited from QWidget - \o 7 protected functions inherited from QObject - \endlist + \raw HTML + <h3>Additional Inherited Members</h3> + \endraw - \target preview window + \list + \o 1 signal inherited from QWidget + \o 1 signal inherited from QObject + \o 4 static public members inherited from QWidget + \o 4 static public members inherited from QObject + \o 39 protected functions inherited from QWidget + \o 7 protected functions inherited from QObject + \endlist - \raw HTML - <hr /> - <h2>Detailed Description</h2> - \endraw + \target preview window - The PreviewWindow class is a custom widget displaying - the names of its currently set window flags in a - read-only text editor. + \raw HTML + <hr /> + <h2>Detailed Description</h2> + \endraw - The PreviewWindow class inherits QWidget. The widget - displays the names of its window flags set with the \l - {function}{setWindowFlags()} function. It is also - provided with a QPushButton that closes the window. + The PreviewWindow class is a custom widget displaying + the names of its currently set window flags in a + read-only text editor. - ... + The PreviewWindow class inherits QWidget. The widget + displays the names of its window flags set with the \l + {function} {setWindowFlags()} function. It is also + provided with a QPushButton that closes the window. - See also QWidget. + ... - \raw HTML - <hr /> - <h2>Member Function Documentation</h2> - \endraw + See also QWidget. - \target constructor - \raw HTML - <h3>PreviewWindow(QWidget *parent = 0)</h3> - \endraw + \raw HTML + <hr /> + <h2>Member Function Documentation</h2> + \endraw - Constructs a preview window widget with \i parent. + \target constructor + \raw HTML + <h3>PreviewWindow(QWidget *parent = 0)</h3> + \endraw - \target function - \raw HTML - <h3>setWindowFlags(Qt::WindowFlags flags)</h3> - \endraw + Constructs a preview window widget with \e parent. - Sets the widgets flags using the - QWidget::setWindowFlags() function. + \target function + \raw HTML + <h3>setWindowFlags(Qt::WindowFlags flags)</h3> + \endraw - Then runs through the available window flags, - creating a text that contains the names of the flags - that matches the flags parameter, displaying - the text in the widgets text editor. - \endquotation + Sets the widgets flags using the + QWidget::setWindowFlags() function. - \row - \o \bold \\enum \target enum - \o \bold {The \\enum command allows you to document a C++ enum.} + Then runs through the available window flags, + creating a text that contains the names of the flags + that matches the flags parameter, displaying + the text in the widgets text editor. + \endquotation - The command follows \l {topical argument}{the general - topical command convention} for the argument. + \target enum-command + \section1 \\enum - The enum items are documented using the \l {value}{\\value} - command. If an item isn't documented, QDoc will emit a - warning. This can be avoided using the \l - {omitvalue}{\\omitvalue} command excluding an item from the - documentation. The enum documentation will be located in - the associated class, header file or namespace - documentation. + The \\enum command is for documenting a C++ enum type. The + argument is the full name of the enum type. - For example: + The enum values are documented in the \\enum comment using the \l + {value-command} {\\value} command. If an enum value is not + documented with \\value, QDoc emits a warning. These warnings can + be avoided using the \l {omitvalue-command} {\\omitvalue} command + to tell QDoc that an enum value should not be documented. The enum + documentation will be included on the class reference page, header + file page, or namespace page where the enum type is defined. For + example, consider the enum type \c {Corner} in the Qt namespace: - \code - enum Corner { - TopLeftCorner = 0x00000, - TopRightCorner = 0x00001, - BottomLeftCorner = 0x00002, - BottomRightCorner = 0x00003 - #if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN) - ,TopLeft = TopLeftCorner, - TopRight = TopRightCorner, - BottomLeft = BottomLeftCorner, - BottomRight = BottomRightCorner - #endif - }; - \endcode + \code + enum Corner { + TopLeftCorner = 0x00000, + TopRightCorner = 0x00001, + BottomLeftCorner = 0x00002, + BottomRightCorner = 0x00003 + #if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN) + ,TopLeft = TopLeftCorner, + TopRight = TopRightCorner, + BottomLeft = BottomLeftCorner, + BottomRight = BottomRightCorner + #endif + }; + \endcode - In case of the Qt::Corner enum, + This enum can be cocumented this way: - \code - / *! - \enum Qt::Corner - - This enum type specifies a corner in a rectangle: - - \value TopLeftCorner - The top-left corner of the rectangle. - \value TopRightCorner - The top-right corner of the rectangle. - \value BottomLeftCorner - The bottom-left corner of the rectangle. - \value BottomRightCorner - The bottom-right corner of the rectangle. - - \omitvalue TopLeft - \omitvalue TopRight - \omitvalue BottomLeft - \omitvalue BottomRight - * / - \endcode + \code + / *! + \enum Qt::Corner + + This enum type specifies a corner in a rectangle: + + \value TopLeftCorner + The top-left corner of the rectangle. + \value TopRightCorner + The top-right corner of the rectangle. + \value BottomLeftCorner + The bottom-left corner of the rectangle. + \value BottomRightCorner + The bottom-right corner of the rectangle. + + \omitvalue TopLeft + \omitvalue TopRight + \omitvalue BottomLeft + \omitvalue BottomRight + * / + \endcode - this associated QDoc comment will be rendered as + Note the inclusion of the namespace qualifier. QDoc will render + this enum type in \c {qt.html} like this: \quotation \raw HTML @@ -4800,231 +4600,258 @@ \endraw \endquotation - in qt.html. + See also \l {value-command} {\\value} and \l {omitvalue-command} {\\omitvalue}. - See also \l {value}{\\value} and \l {omitvalue}{\\omitvalue}. + \target example-command + \section1 \\example - \row - \o \bold \\example \target example-command - \o \bold {The \\example command allows you to document an - example.} + The \\example command is for documenting an example. The argument + is the example's path relative to omne of the paths listed in the + \l {exampledirs-variable} {exampledirs} variable in the QDoc + configuration file. - The command follows \l {topical argument}{the general - topical command convention} for the argument. In particular - the command's argument is the example's path relative to - the paths listed in the \l exampledirs configuration - variable. + The documentation page will be output to \c {path-to-example}.html. + QDoc will add a list of all the example's source files at the top + of the page. - The documentation will be located in \i - {path-to-example}.html, and QDoc will add a list of all the - example files at the top of this documentation page. + For example, if \l {exampledirs-variable} {exampledirs} contains + \c $QTDIR/examples/widgets/imageviewer, then - For example, if \l exampledirs contain \c - $QTDIR/examples/widgets/imageviewer, then + \code + / *! + \example widgets/imageviewer + \title ImageViewer Example + \subtitle - \code - / *! - \example widgets/imageviewer - \title ImageViewer Example - \subtitle + The example shows how to combine QLabel and QScrollArea + to display an image. - The example shows how to combine QLabel and QScrollArea - to display an image. + ... + * / + \endcode - ... - * / - \endcode + QDoc renders this example in widgets-imageviewer.html: - will be rendered as + \quotation + \raw HTML + <center><h1>Image Viewer Example</h1></center> + \endraw - \quotation - \raw HTML - <center><h1>Image Viewer Example</h1></center> - \endraw + Files: + \list + \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-imageviewer-cpp.html} + {widgets/imageviewer/imageviewer.cpp} + \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-imageviewer-h.html} + {widgets/imageviewer/imageviewer.h} + \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-main-cpp.html} + {widgets/imageviewer/main.cpp} + \endlist - Files: - \list - \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-imageviewer-cpp.html} - {widgets/imageviewer/imageviewer.cpp} - \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-imageviewer-h.html} - {widgets/imageviewer/imageviewer.h} - \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-main-cpp.html} - {widgets/imageviewer/main.cpp} - \endlist + The example shows how to combine QLabel and QScrollArea + to display an image. - The example shows how to combine QLabel and QScrollArea - to display an image. + ... + \endquotation - ... - \endquotation + \target externalpage-command + \section1 \\externalpage - in widgets-imageviewer.html. + The \\externalpage command assigns a title to an external URL. - \row - \o \bold \\fn \target fn - \o \bold {The \\fn command allows you to document a function.} - - The command follows \l {topical argument}{the general - topical command convention} for the argument. In particular - it is important that the return type of the function, - whether it is \c const or not and the complete set of - arguments with type are included in the argument. If the - referenced function doesn't exist, QDoc will emit a - warning. - - Also, the \\fn command is QDoc's default command, i.e. when - no topical command can be found within a QDoc comment, QDoc - tries to tie the documentation to the following code as if - it was function documentation. - - This means that the command normally isn't necessary since - the recommended style is to write the function - documentation directly before the function implementation - in the \c .cpp file. In fact, it should only be used for - inline functions implemented in the \c .h file. - - For example: + \code + / *! + \externalpage http://doc.trolltech.com/4.3/qtopiacore.html + \title Qtopia Core + * / + \endcode - \code - / *! - \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const + This allows you to include a link to the external page in your + documentation this way: - Returns true if this toolbar is dockable in the given - \a area; otherwise returns false. - * / - \endcode + \code + / *! + The broad scope of the \l {Qtopia Core} API enables it to + be used across a wide variety of development projects. + * / + \endcode - will be rendered as + QDoc renders this as: - \quotation - \raw HTML - <h3>bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const - </h3> - \endraw + \quotation + The broad scope of the \l + {http://doc.trolltech.com/4.3/qtopiacore.html} {Qtopia + Core} API enables it to be used across a wide variety + of development projects. + \endquotation - Returns true if this toolbar is dockable in the given - \a area; otherwise returns false. - \endquotation + To achieve the same result without using the \\externalpage + command, you would have to hard code the adress into your + documentation: - See also \l {overload}{\\overload}. + \code + / *! + The broad scope of the \l + {http://doc.trolltech.com/4.3/qtopiacore.html} {Qtopia + Core} API enables it to be used across a wide variety + of development projects. + * / + \endcode - \row - \o \bold \\group \target group - \o \bold {The \\group command creates a separate page that - lists the classes belonging to the group specified by the - command's argument.} - - The command follows \l {topical argument}{the general - topical command convention} for the argument. The \\group - command is typically followed by a \l {title}{\\title} - command and a short introduction to the group. The - generated HTML documentation for the specified group is put - in <lower-case>\i{group}.html. - - A class can be related to a group by using the \l - {ingroup}{\\ingroup} command. In addition, overviews can be - related to a group using the same command, but these must - be listed explicitly using the \l - {generatelist}{\\generatelist} command (see example below). - - Each class is listed with a link to the class reference - page and a brief description based on the classes' \l - {brief}{\\brief} texts. For example: + The \\externalpage command makes it easier to maintain the + documentation. If the adress changes, you only need to change the + argument of the \\externalpage command. - \code - / *! - \group io + \target fn-command + \section1 \\fn (function) - \title Input/Output and Networking + The \\fn command is for documenting a function. The argument is + the function's signature, including its return type, const-ness, + and list of formal arguments with types. If the named function + doesn't exist, QDoc emits a warning. - These classes are used to handle input and output to - and from external devices, processes, files etc. as - well as manipulating files and directories. - * / - \endcode + \note The \\fn command is QDoc's default command, i.e. when no + topic command can be found in a QDoc comment, QDoc tries to tie + the documentation to the following code as if it is the + documentation for a function. Hence, it is normally not necessary + to include this command when documenting a function, if the + function's QDoc comment is written immediately above the function + implementation in the \c .cpp file. But it must be present when + documenting an inline function in the \c .cpp file that is + implemented in the \c .h file. - will be rendered as + \code + / *! + \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const - \quotation - \raw HTML + Returns true if this toolbar is dockable in the given + \a area; otherwise returns false. + * / + \endcode - <h1>Input/Output and Networking</h1> - - <p>These classes are used to handle input and output - to and from external devices, processes, files etc. as - well as manipulating files and directories.</p> - - <p> - <table width="100%"> - <tr valign="top" bgcolor="#e0e0e0"> - <td><b> - <a href="http://qt.nokia.com/doc/4.0/qabstractsocket.html">QAbstractSocket</a> - </b></td> - <td> - The base functionality common to all socket types - </td></tr> - - <tr valign="top" bgcolor="#e0e0e0"> - <td><b> - <a href="http://qt.nokia.com/doc/4.0/qbuffer.html">QBuffer</a> - </b></td> - <td> - QIODevice interface for a QByteArray - </td></tr> - - <tr valign="top" bgcolor="#e0e0e0"> - <td><b> - <a href="http://qt.nokia.com/doc/4.0/qclipboard.html">QClipboard</a> - </b></td> - <td> - Access to the window system clipboard - </td></tr> - </table> - \endraw - \endquotation + QDoc renders this as: - in io.html. + \quotation + \raw HTML + <h3>bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const + </h3> + \endraw - Note that overviews related to the given group, must be - listed explicitly using the \l - {generatelist}{\\generatelist} command with the \c related - argument. For example: + Returns true if this toolbar is dockable in the given + \a area; otherwise returns false. + \endquotation - \code - / *! - \group architecture + See also \l {overload-command} {\\overload}. - \title Architecture + \target group-command + \section1 \\group - These documents describe aspects of Qt's architecture - and design, including overviews of core Qt features and - technologies. + The \\group command creates a separate page that lists the classes + belonging to the group. The argument is the group name. - \generatelist{related} - * / - \endcode + A class is included in a group by using the \l {ingroup-command} + {\\ingroup} command. Overview pages can also be related to a group + using the same command, but the list of overview pages must be + requested explicitly using the \l {generatelist-command} + {\\generatelist} command (see example below). - See also \l {ingroup}{\\ingroup} and \l - {generatelist}{\\generatelist}. + The \\group command is typically followed by a \l {title-command} + {\\title} command and a short introduction to the group. The + HTML page for the group is written to a \c {.html} file put in + <lower-case>\e{group}.html. - \row - \o \bold \\headerfile \target headerfile - \o \bold {The \\headerfile command allows you to document - global functions, types and macros declared in a header file.} + Each class name is listed as a link to the class reference page + followed by the text from the class's \l {brief-command} {\\brief} + texts. - The command follows \l {topical argument}{the general - topical command convention} for the argument, and the - generated HTML documentation for the specified header file - is put in <lower-case>\i{headerfilename}.html. + \code + / *! + \group io - A function, type or macro can be associated with a - headerfile using the \l {relates}{\\relates} command. + \title Input/Output and Networking - If the referenced header file doesn't exist, the - \\headerfile command will still create a documentation page - for a header file with the referenced file's name. + These classes are used to handle input and output to + and from external devices, processes, files etc. as + well as manipulating files and directories. + * / + \endcode - For example: + QDoc generates a group page in \c{io.html} that will look + like this: + + \quotation + \raw HTML + + <h1>Input/Output and Networking</h1> + + <p>These classes are used to handle input and output + to and from external devices, processes, files etc. as + well as manipulating files and directories.</p> + + <p> + <table width="100%"> + <tr valign="top" bgcolor="#e0e0e0"> + <td><b> + <a href="http://qt.nokia.com/doc/4.0/qabstractsocket.html">QAbstractSocket</a> + </b></td> + <td> + The base functionality common to all socket types + </td></tr> + + <tr valign="top" bgcolor="#e0e0e0"> + <td><b> + <a href="http://qt.nokia.com/doc/4.0/qbuffer.html">QBuffer</a> + </b></td> + <td> + QIODevice interface for a QByteArray + </td></tr> + + <tr valign="top" bgcolor="#e0e0e0"> + <td><b> + <a href="http://qt.nokia.com/doc/4.0/qclipboard.html">QClipboard</a> + </b></td> + <td> + Access to the window system clipboard + </td></tr> + </table> + \endraw + \endquotation + + Note that overview pages related to the group, must be listed + explicitly using the \l {generatelist-command} {\\generatelist} + command with the \c related argument. + + \code + / *! + \group architecture + + \title Architecture + + These documents describe aspects of Qt's architecture + and design, including overviews of core Qt features and + technologies. + + \generatelist{related} + * / + \endcode + + See also \l {ingroup-command} {\\ingroup} and \l + {generatelist-command} {\\generatelist}. + + \target headerfile-command + \section1 \\headerfile + + The \\headerfile command is for documenting the global functions, + types and macros that are declared in a header file but not in a + namespace. The argument is the name of the header file. The HTML + page is written to a \c {.html} file constructed from the header + file aregument. + + The documentation for a function, type, or macro that is declared + in the header file being documented is included in the header file + page using the \l {relates-command} {\\relates} command. + + If the argument doesn't exist as a header file, the \\headerfile + command creates a documentation page for the header file anyway. \code / *! @@ -5041,7 +4868,8 @@ * / \endcode - will be rendered as + QDoc generates a header file page \c{qtalgorithms.html} that looks + like this: \quotation \raw HTML @@ -5049,7 +4877,7 @@ Generic Algorithms</h1></center> <p>The <QtAlgorithms> header file provides generic template-based algorithms. - <a href="13-qdoc-commands-topical.html#header">More...</a> + <a href="13-qdoc-commands-topics.html#header-command">More...</a> </p> <h3>Functions</h3> @@ -5077,163 +4905,139 @@ ... \endquotation - in qtalgorithms.html. - - \row - \o \bold \\macro \target macro - \o \bold {The \\macro command allows you to document a C++ macro.} - - The command follows \l {topical argument}{the general - topical command convention} for the argument. - - QDoc recognizes three different macro syntax: function-like - macros like Q_ASSERT(), declaration-style macros like - Q_PROPERTY() and macros without parentheses like Q_OBJECT. - - The \\macro command must be followed by a \l - {relates}{\\relates} command which attaches the - documentation to that of a related class, header file. or - namespace. Otherwise the documentation will be lost. - - For example: - - \code - / *! - \macro void Q_ASSERT(bool test) - \relates <QtGlobal> - - Prints a warning message containing the source code - file name and line number if \a test is false. - - ... - - \sa Q_ASSERT_X(), qFatal(), {Debugging Techniques} - * / - \endcode - - will be rendered as - - \quotation - \raw HTML - <h3>void Q_ASSERT ( bool <i>test</i> )</h3> - \endraw + \target macro-command + \section1 \\macro - Prints a warning message containing the source code - file name and line number if \a test is false. + The \\macro command is for documententin a C++ macro. The argument + is the macro in one of three styles: function-like macros like + Q_ASSERT(), declaration-style macros like Q_PROPERTY(), and macros + without parentheses like Q_OBJECT. - ... + The \\macro comment must contain a \l {relates-command} + {\\relates} command that attaches the macro comment to a class, + header file, or namespace. Otherwise, the documentation will be + lost. Here are three example macro comments followed by what they + might look like in \c {qtglobal.html} or \c {qobject.html}: - See also Q_ASSERT_X(), qFatal() and \l {Debugging - Techniques}. - \endquotation + \code + / *! + \macro void Q_ASSERT(bool test) + \relates <QtGlobal> - in qtglobal.html. And + Prints a warning message containing the source code + file name and line number if \a test is false. - \code - / *! - \macro Q_PROPERTY(...) - \relates QObject + ... - This macro declares a QObject property. The syntax is: + \sa Q_ASSERT_X(), qFatal(), {Debugging Techniques} + * / + \endcode - ... + \quotation + \raw HTML + <h3>void Q_ASSERT ( bool <i>test</i> )</h3> + \endraw - \sa {Qt's Property System} - * / - \endcode + Prints a warning message containing the source code + file name and line number if \a test is false. - will be rendered as + ... - \quotation - \raw HTML - <h3>Q_PROPERTY ( ... )</h3> - \endraw + See also Q_ASSERT_X(), qFatal() and \l {Debugging Techniques}. + + \endquotation - This macro declares a QObject property. The syntax is: + \code + / *! + \macro Q_PROPERTY(...) + \relates QObject - ... + This macro declares a QObject property. The syntax is: - See also \l {Qt's Property System}. - \endquotation + ... - in qobject.html. And + \sa {Qt's Property System} + * / + \endcode - \code - / *! - \macro Q_OBJECT - \relates QObject + \quotation + \raw HTML + <h3>Q_PROPERTY ( ... )</h3> + \endraw - The Q_OBJECT macro must appear in the private section - of a class definition that declares its own signals and - slots or that uses other services provided by Qt's - meta-object system. + This macro declares a QObject property. The syntax is: - ... + ... - \sa {Meta-Object System}, {Signals and Slots}, {Qt's - Property System} - * / - \endcode + See also \l {Qt's Property System}. + \endquotation - will be rendered as + \code + / *! + \macro Q_OBJECT + \relates QObject - \quotation - \raw HTML - <h3>Q_OBJECT</h3> - \endraw + The Q_OBJECT macro must appear in the private section + of a class definition that declares its own signals and + slots or that uses other services provided by Qt's + meta-object system. - The Q_OBJECT macro must appear in the private section - of a class definition that declares its own signals and - slots or that uses other services provided by Qt's - meta-object system. + ... - ... + \sa {Meta-Object System}, {Signals and Slots}, {Qt's + Property System} + * / + \endcode - See also \l {Meta-Object System}, \l {Signals and - Slots} and \l {Qt's Property System}. - \endquotation + \quotation + \raw HTML + <h3>Q_OBJECT</h3> + \endraw - in qobject.html. + The Q_OBJECT macro must appear in the private section + of a class definition that declares its own signals and + slots or that uses other services provided by Qt's + meta-object system. - \row - \o \bold \\module \target module - \o \bold {The \\module creates a separate page that lists the - classes belonging to the module specified by the command's - argument.} + ... - The command follows \l {topical argument}{the general - topical command convention} for the argument. + See also \l {Meta-Object System}, \l {Signals & + Slots} and \l {Qt's Property System}. + \endquotation - A class can be related to a module using the \l - {inmodule}{\\inmodule} command. + \target module-command + \section1 \\module - The \\module command is typically followed by the \l - {title}{\\title} and \l {brief}{\\brief} commands. Each - class is listed with a link to the class reference page and - a brief description based on the classes' \l - {brief}{\\brief} texts. + The \\module creates a page that lists the classes belonging to + the module specified by the command's argument. A class included + in the module by including the \l {inmodule-command} {\\inmodule} + command in the \\class comment. - For example: + The \\module command is typically followed by a \l {title-command} + {\\title} and a \l {brief-command} {\\brief} command. Each class + is listed as a link to the class reference page followed by the + text from the class's \l {brief-command} {\\brief} command. For + example: - \code - / *! - \module QtNetwork + \code + / *! + \module QtNetwork - \title QtNetwork Module + \title QtNetwork Module - \brief The QtNetwork module offers classes that allow - you to write TCP/IP clients and servers. + \brief The QtNetwork module offers classes that allow + you to write TCP/IP clients and servers. - The network module provides classes to make network - programming easier and portable. It offers both - high-level classes such as QHttp and QFtp that - implement specific application-level protocols, and - lower-level classes such as QTcpSocket, QTcpServer, and - QUdpSocket. - * / - \endcode + The network module provides classes to make network + programming easier and portable. It offers both + high-level classes such as QHttp and QFtp that + implement specific application-level protocols, and + lower-level classes such as QTcpSocket, QTcpServer, and + QUdpSocket. + * / + \endcode - will be rendered as + QDoc renders this in \c {qtnetwork.html} like this: \quotation \raw HTML @@ -5242,7 +5046,7 @@ The QtNetwork module offers classes that allow you to write TCP/IP clients and servers.\l {module - details}{More...} + details} {More...} \raw HTML <p> @@ -5296,43 +5100,33 @@ \endquotation - in qtnetwork.html. + See also \l {inmodule-command} {\\inmodule} - See also \l {inmodule}{\\inmodule} + \target namespace-command + \section1 \\namespace - \row - \o \bold \\namespace \target namespace - \o \bold {The \\namespace command allows you to document a C++ - namespace.} + The \\namespace command is for documenting the contents of the C++ + namespace named as its argument. The documentation outline QDoc + generates for a namespace is similar to the outline it generates + for a C++ class. - The command follows \l {topical argument}{the general - topical command convention} for the argument. - - QDoc will generate the same additional links and - documentation for all the members of the namespace as it - does for \l {framework}{classes}. The documentation for - the specified namespace is put in <lower-case>\i - {namespace}.html. - - For example: - - \code - / *! - \namespace Qt + \code + / *! + \namespace Qt - \brief The Qt namespace contains miscellaneous - identifiers used throughout the Qt library. - * / - \endcode + \brief The Qt namespace contains miscellaneous + identifiers used throughout the Qt library. + * / + \endcode - will be rendered as + QDoc renders this in \c{qt.html} like this: \quotation \raw HTML <center><h1>Qt Namespace Reference</h1></center> <p>The Qt namespace contains miscellaneous identifiers used throughout the Qt library. - <a href="13-qdoc-commands-topical.html#name">More...</a> + <a href="13-qdoc-commands-topics.html#name">More...</a> </p> <pre>#include <Qt></pre> @@ -5362,18 +5156,13 @@ ... \endquotation - in qt.html. - - \row - \o \bold \\page \target page - \o \bold {The \\page command allows you to create a stand-alone - documentation page.} - - The command follows \l {topical argument}{the general - topical command convention} for the argument. + \target page-command + \section1 \\page - The page's title can be set using the \l {title}{\\title} - command. For example: + The \\page command is for creating a stand-alone documentation + page. The argument is the name of the file where QDoc should + store the page. The page title is set using the \l {title-command} + {\\title} command. \code / *! @@ -5398,470 +5187,587 @@ * / \endcode - will be rendered in its own HTML file: \l{About Qt}. + QDoc renders this page in \c {aboutqt.html}. - \row - \o \bold {\\externalpage} \target externalpage - \o \bold {The \\externalpage command gives a title to - an external URL.} + \target property-command + \section1 \\property - The command follows \l {topical argument}{the general - topical command convention} for the argument. + The \\property command is for documenting a Qt property. The + argument is the full property name. - For example: + 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. - \code - / *! - \externalpage http://www.trolltech.com/products/embedded/index.html - \title Qtopia Core - * / - \endcode + \code + Q_PROPERTY(QString state READ state WRITE setState) + \endcode - The QDoc comment above allows you to link to the Qtopia - Core webpage by simply linking to the given title. 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 - / *! - The broad scope of the \l {Qtopia Core} API enables it to - be used across a wide variety of development projects. - * / - \endcode + 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. - will be rendered as + \code + / *! + \property QPushButton::flat + \brief whether the border is disabled - \quotation - The broad scope of the \l - {http://www.trolltech.com/products/embedded/index.html}{Qtopia - Core} API enables it to be used across a wide variety - of development projects. - \endquotation + This property's default is false. + * / + \endcode - To achieve the same result without using the - \\externalpage command, you would have to hard code the - adress into your documentation: + QDoc includes this in \c {qpushbutton.html} like this: - \code - / *! - The broad scope of the \l - {http://www.trolltech.com/products/embedded/index.html}{Qtopia - Core} API enables it to be used across a wide variety - of development projects. - * / - \endcode + \quotation + \raw HTML + <h3>flat : bool</h3> + \endraw - The \\externalpage command makes it easier to maintain the - documentation. If the adress changes, you only need to change the - argument of the \\externalpage command. + This property holds whether the border is disabled. - \row - \o \bold \\property \target property - \o \bold {The \\property command allows you to document a Qt - property.} + This property's default is false. - The command follows \l {topical argument}{the general - topical command convention} for the argument. + Access functions: - 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: + \list + \o \bold { bool isFlat () const} + \o \bold { void setFlat ( bool )} + \endlist - \code - Q_PROPERTY(QString state READ state WRITE setState) - \endcode + \endquotation - 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 QWidget::width + \brief the width of the widget excluding any window frame - The \\property command is typically accompanied with a \l - {brief}{\\brief} command. In the case of a property, the - \l {brief}{\\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}{\\variable} - command. + See the \l {Window Geometry} documentation for an + overview of window geometry. - For example: + \sa geometry, height, size + * / + \endcode - \code - / *! - \property QPushButton::flat - \brief whether the border is disabled + QDoc includes this in \c {qwidget.html} like this: - This property's default is false. - * / - \endcode + \quotation + \raw HTML + <h3>width : const int</h3> + \endraw - will be rendered as + This property holds the width of the widget excluding + any window frame. - \quotation - \raw HTML - <h3>flat : bool</h3> - \endraw + See the \l {Window Geometry} documentation for an + overview of window geometry. - This property holds whether the border is disabled. + Access functions: - This property's default is false. + \list + \o \bold { int width () const} + \endlist - Access functions: + See also \l{QWidget::geometry} {geometry}, + \l{QWidget::height} {height}, and \l{QWidget::size} {size}. + \endquotation - \list - \o \bold { bool isFlat () const} - \o \bold { void setFlat ( bool )} - \endlist + \target service-command + \section1 \\service + + 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 qmlattachedproperty-command + \section1 \\qmlattachedproperty \span {class="newStuff"} {(new)} + + The \\qmlattachedproperty command is for documenting a QML + property that will be attached to some QML element type. See + \l{http://doc.trolltech.com/4.7/qdeclarativeintroduction.html#attached-properties} + {Attached Properties}. The argument is the rest of the line. The + argument text should be the property type, followed by the QML + element name where the property is being declared, the \c{::} + qualifier, and finally the property name. If we have a QML + attached property named \c isCurrentItem in QML element \c ListView, + and the property has type \c {bool}, the \\qmlattachedproperty for + it would look like this: - \endquotation + \code + / *! + \qmlattachedproperty bool ListView::isCurrentItem + This attached property is true if this delegate is the current + item; otherwise false. - in qpushbutton.html. And + It is attached to each instance of the delegate. - \code - / *! - \property QWidget::width - \brief the width of the widget excluding any window frame + This property may be used to adjust the appearance of the current + item, for example: - See the \l {Window Geometry} documentation for an - overview of window geometry. + \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem + * / + \endcode - \sa geometry, height, size - * / - \endcode + QDoc includes this attached property on the QML reference page for the + \l{http://doc.trolltech.com/4.7/qml-listview.html#isCurrentItem-prop} + {ListView} element. - will be rendered as + \target qmlattachedsignal-command + \section1 \\qmlattachedsignal \span {class="newStuff"} {(new)} - \quotation - \raw HTML - <h3>width : const int</h3> - \endraw + The \\qmlattachedsignal command is for documenting an attachable + \l{http://doc.trolltech.com/4.7/qdeclarativeintroduction.html#signal-handlers} + {signal handler}. The \\qmlattachedsignal command is used just like + the \l{qmlsignal-command} {\\qmlsignal} command. - This property holds the width of the widget excluding - any window frame. + The argument is the rest of the line. It should be the name of the + QML element where the signal handler is declared, the \c{::} + qualifier, and finally the signal handler name. If we have a QML + attached signal handler named \c onAdd() in the \c GridView + element, the \\qmlattachedsignal for it would look like this: - See the \l {Window Geometry} documentation for an - overview of window geometry. + \code + / *! + \qmlattachedsignal GridView::onAdd() + This attached handler is called immediately after an item is + added to the view. + * / + \endcode - Access functions: + QDoc includes this documentation on the QML reference page for the + \l{http://doc.trolltech.com/4.7/qml-gridview.html#onAdd-signal} + {GridView} element. - \list - \o \bold { int width () const} - \endlist + \target qmlbasictype-command + \section1 \\qmlbasictype \span {class="newStuff"} {(new)} - See also \l{QWidget::geometry}{geometry}, - \l{QWidget::height}{height}, and \l{QWidget::size}{size}. - \endquotation + The \\qmlbasictype command is for documenting a basic type for QML. + The argument is the type name. The type must be included in the + QML basic types group using the \l{ingroup-command}{\\ingroup} + command as shown below. This will cause QDoc to include the + documentation for the type on the + \l{http://doc.trolltech.com/4.7/qdeclarativebasictypes.html} + {QML Basic Types} page. The \l{brief-command} {\\brief} command + is also required, because it appears on the + \l{http://doc.trolltech.com/4.7/qdeclarativebasictypes.html} + {QML Basic Types} page as well. - in qwidget.html. + \code + / *! + \qmlbasictype int + \ingroup qmlbasictypes - \row - \o \bold \\service \target service + \brief An integer is a whole number, e.g. 0, 10, or -20. - \o \bold {The \\service command tells QDoc that a class is a - service class and specifies its alias, i.e. the associated - service's name.} + An integer is a whole number, e.g. 0, 10, or -20. The possible + \c int values range from around -2000000000 to around + 2000000000, although most elements will only accept a reduced + range (which they mention in their documentation). - The command takes two arguments, the service class's name - and the associated alias. For example: + Example: + \qml + Item { width: 100; height: 200 } + \endqml - \code - / *! - \service TimeService Time - ... - * / - class TimeService : public QCopObjectService - { - ... - } - \endcode + \sa {QML Basic Types} + * / + \endcode - See also \l {class}{\\class} and \l - {generatelist}{\\generatelist}. + QDoc outputs this as \l{http://doc.trolltech.com/4.7/qml-int.html} + {qml-int.html}. - \row - \o \bold \\typedef \target typedef - \o \bold {The \\typedef command allows you to document a C++ type - definition.} + \target qmlclass-command + \section1 \\qmlclass \span {class="newStuff"} {(new)} - The command follows \l {topical argument}{the general - topical command convention} for the argument. + The \\qmlclass command is for documenting a QML element that is + instantiated by a C++ class. The command has two arguments. The + first argument is the name of the QML element. The second argument + is the name of the C++ class that instantiates the QML element. - 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}{\\relates} command. For - example: + \code + / *! + \qmlclass Transform QGraphicsTransform + \ingroup qml-transform-elements + \since 4.7 + \brief The Transform elements provide a way of building + advanced transformations on Items. - \code - / *! - \typedef QObjectList - \relates QObject + The Transform element is a base type which cannot be + instantiated directly. The following concrete Transform types + are available: - Synonym for QList<QObject>. - * / - \endcode + \list + \o \l Rotation + \o \l Scale + \o \l Translate + \endlist - will be rendered as + The Transform elements let you create and control advanced + transformations that can be configured independently using + specialized properties. - \quotation - \raw HTML - <h3>typedef QObjectList</h3> - \endraw + You can assign any number of Transform elements to an \l + Item. Each Transform is applied in order, one at a time. - Synonym for QList<QObject>. - \endquotation + * / + \endcode - in qobject.html. Another, although more rare, example is + This example generates the + \l {http://doc.trolltech.com/4.7/qml-transform.html} {QML Trasform + Element} page. The \\qmlclass comment should include the \l + {since-command} {\\since} command, because all QML elements are + new. It should also include the \l{brief-command} {\\brief} + command. And since every QML element is a member of a group of QML + elements, it should also include one or more \l{ingroup-command} + {\\ingroup} commands. - \code - / *! - \typedef QMsgHandler - \relates QtGlobal + \target qmlmethod-command + \section1 \\qmlmethod \span {class="newStuff"} {(new)} - This is a typedef for a pointer to a function with the - following signature: + The \\qmlmethod command is for documenting a QML method. The + argument is the complete method signature, including return + type and parameter names and types. - \code - void myMsgHandler(QtMsgType, const char *); - \ endcode + \code + / *! + \qmlmethod void TextInput::select(int start, int end) - \sa QtMsgType, qInstallMsgHandler() - * / - \endcode + Causes the text from \a start to \a end to be selected. - will be rendered as + If either start or end is out of range, the selection is not changed. - \quotation - \raw HTML - <h3>typedef QtMsgHandler</h3> - \endraw + After calling this, selectionStart will become the lesser and + selectionEnd will become the greater (regardless of the order + passed to this method). + + \sa selectionStart, selectionEnd + * / + \endcode - This is a typedef for a pointer to a function with the - following signature: + QDoc includes this documentation on the element refence page for the + \l{http://doc.trolltech.com/4.7/qml-textinput.html#select-method} + {TextInput} element. - \raw HTML - <tt> - <pre> void myMsgHandler(QtMsgType, const char *);</pre> - </tt> - \endraw + \target qmlproperty-command + \section1 \\qmlproperty \span {class="newStuff"} {(new)} - See also QtMsgType and qInstallMsgHandler(). + The \\qmlproperty command is for documenting a QML property. The + argument is the rest of the line. The argument text should be the + property type, followed by the QML element name, the \c{::} + qualifier, and finally the property name. If we have a QML + property named \c x in QML element \c Translate, and the property + has type \c {real}, the \\qmlproperty for it would look like this: - \endquotation + \code + / *! + \qmlproperty real Translate::x - in qtglobal.html. Other type definitions are located in the - documentation of the class that defines it, for example: + The translation along the X axis. + * / + \endcode - \code - / *! - \typedef QLinkedList::Iterator + QDoc includes this QML property on the QML reference page for the + \l {http://doc.trolltech.com/4.7/qml-translate.html} {Translate} + element. - Qt-style synonym for QList::iterator. - * / - \endcode + \target qmlsignal-command + \section1 \\qmlsignal \span {class="newStuff"} {(new)} - will be rendered as + The \\qmlsignal command is for documenting a + \l{http://doc.trolltech.com/4.7/qdeclarativeintroduction.html#signal-handlers} + {signal handler}. + The argument is the rest of the line. It should be the QML element where the + signal handler is declared, the \c{::} qualifier, and finally the signal + handler name. If we have a QML signal handler named \c onAdd() in QML + element \c MouseArea, the \\qmlsignal for it would look like this: - \quotation - \raw HTML - <h3>typedef QLinkedList::Iterator</h3> - \endraw + \code + / *! + \qmlsignal MouseArea::onEntered() - Qt-style synonym for QList::iterator. - \endquotation + This handler is called when the mouse enters the mouse area. - in qlinkedlist.html. + By default the onEntered handler is only called while a button is + pressed. Setting hoverEnabled to true enables handling of + onEntered when no mouse button is pressed. - \row - \o \bold \\variable \target variable - \o \bold {The \\variable command allows you to document a - member variable or a constant.} + \sa hoverEnabled + * / + \endcode - The command follows \l {topical argument}{the general - topical command convention} for the argument. + QDoc includes this documentation on the QML reference page for the + \l{http://doc.trolltech.com/4.7/qml-mousearea.html#onEntered-signal} + {MouseArea} element. - The \\variable command is typically followed by a \l - {brief}{\\brief} command; QDoc will generate the - documentation for the variable based on the brief - description. The command follows the same rules for the \l - {brief property}{description} as the \l - {property}{\\property} command. + \target typedef-command + \section1 \\typedef - The documentation will be located in the in the associated - class, header file or namespace documentation. + 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. - In case of a member variable: + \code + / *! + \typedef QObjectList + \relates QObject - \code - / *! - \variable QStyleOption::palette - \brief the palette that should be used when painting - the control - * / - \endcode + Synonym for QList<QObject>. + * / + \endcode - will be rendered as + QDoc includes this in \c {qobject.html} as: - \quotation - \raw HTML - <h3> - <a href="http://qt.nokia.com/doc/4.0/qpalette.html"> - QPalette - </a> - QStyleOption::palette - </h3> - \endraw + \quotation + \raw HTML + <h3>typedef QObjectList</h3> + \endraw - This variable holds the palette that should be used - when painting the control. - \endquotation + Synonym for QList<QObject>. + \endquotation - in qstyleoption.html. + Another, although more rare, example: - 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 + / *! + \typedef QMsgHandler + \relates QtGlobal - \code - enum { Type = 0, UserType = 1000 }; - \endcode + This is a typedef for a pointer to a function with the + following signature: - Then + \code + void myMsgHandler(QtMsgType, const char *); + \ endcode - \code - / *! - \variable QTreeWidgetItem::Type + \sa QtMsgType, qInstallMsgHandler() + * / + \endcode - The default type for tree widget items. + QDoc includes this in \c {qtglobal.html} as: - \sa UserType, type() - * / - \endcode + \quotation + \raw HTML + <h3>typedef QtMsgHandler</h3> + \endraw - and + This is a typedef for a pointer to a function with the + following signature: - \code - / *! - \variable QTreeWidgetItem::UserType + \raw HTML + <tt> + <pre> void myMsgHandler(QtMsgType, const char *);</pre> + </tt> + \endraw - The minimum value for custom types. Values below - UserType are reserved by Qt. + See also QtMsgType and qInstallMsgHandler(). + \endquotation - \sa Type, type() - * / - \endcode + Other typedefs are located on the reference page for the class + that defines them. - will be rendered as + \code + / *! + \typedef QLinkedList::Iterator - \quotation - \raw HTML - <h3> - const int QTreeWidgetItem::Type - </h3> - \endraw + Qt-style synonym for QList::iterator. + * / + \endcode - The default type for tree widget items. + QDoc includes this one on the reference page for class QLinkedList as: - See also \l {QTreeWidgetItem::UserType}{UserType} and - \l {QTreeWidgetItem::type()}{type()}. + \quotation + \raw HTML + <h3>typedef QLinkedList::Iterator</h3> + \endraw - \raw HTML - <h3> - const int QTreeWidgetItem::UserType - </h3> - \endraw + Qt-style synonym for QList::iterator. + \endquotation - The minimum value for custom types. Values below - UserType are reserved by Qt. + \target variable-command + \section1 \\variable - See also \l {QTreeWidgetItem::Type}{Type} and - \l{QTreeWidgetItem::type()}{type()}. + 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. - \endquotation + The documentation will be located in the in the associated class, + header file or namespace documentation. - in qtreewidget.html. - \endtable + In case of a member variable: + + \code + / *! + \variable QStyleOption::palette + \brief the palette that should be used when painting + the control + * / + \endcode + + QDoc includes this in qstyleoption.html as: + + \quotation + \raw HTML + <h3> + <a href="http://qt.nokia.com/doc/4.0/qpalette.html"> + QPalette + </a> + QStyleOption::palette + </h3> + \endraw + + This variable holds the palette that should be used + when painting the control. + \endquotation + + 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: + + \code + enum { Type = 0, UserType = 1000 }; + \endcode + + For these, the \\vaqriable command can be used this way: + + \code + / *! + \variable QTreeWidgetItem::Type + + The default type for tree widget items. + + \sa UserType, type() + * / + \endcode + \code + / *! + \variable QTreeWidgetItem::UserType + + The minimum value for custom types. Values below + UserType are reserved by Qt. + + \sa Type, type() + * / + \endcode + + QDoc includes these in qtreewidget.html as: + + \quotation + \raw HTML + <h3> + const int QTreeWidgetItem::Type + </h3> + \endraw + + The default type for tree widget items. + + See also \l {QTreeWidgetItem::UserType} {UserType} and \l + {QTreeWidgetItem::type()} {type()}. + + \raw HTML + <h3> + const int QTreeWidgetItem::UserType + </h3> + \endraw + + The minimum value for custom types. Values below + UserType are reserved by Qt. + + See also \l {QTreeWidgetItem::Type} {Type} and + \l{QTreeWidgetItem::type()} {type()}. + + \endquotation */ /*! - \page 14-qdoc-commands-contextualcommands.html - \previouspage Topical Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Navigation Commands - - \title Contextual Commands - - The contextual commands provide QDoc with information, that it - wouldn't figure out otherwise, about the documented object. For - example whether a class is thread-safe or not. - - These commands can appear anywhere within a QDoc comment. - - \section1 Alphabetical List - - \l {16-qdoc-commands-status.html#compat}{\\compat}, - \l {15-qdoc-commands-navigation.html#contentspage}{\\contentspage}, - \l {15-qdoc-commands-navigation.html#indexpage}{\\indexpage}, - \l {19-qdoc-commands-grouping.html#ingroup}{\\ingroup}, - \l {19-qdoc-commands-grouping.html#inmodule}{\\inmodule}, - \l {16-qdoc-commands-status.html#internal}{\\internal}, - \l {19-qdoc-commands-grouping.html#mainclass}{\\mainclass}, - \l {15-qdoc-commands-navigation.html#nextpage}{\\nextpage}, - \l {17-qdoc-commands-thread.html#nonreentrant}{\\nonreentrant}, - \l {16-qdoc-commands-status.html#obsolete}{\\obsolete}, - \l {18-qdoc-commands-relating.html#overload}{\\overload}, - \l {16-qdoc-commands-status.html#preliminary}{\\preliminary}, - \l {15-qdoc-commands-navigation.html#previouspage}{\\previouspage}, - \l {17-qdoc-commands-thread.html#reentrant}{\\reentrant}, - \l {18-qdoc-commands-relating.html#reimp}{\\reimp}, - \l {18-qdoc-commands-relating.html#relates}{\\relates}, - \l {15-qdoc-commands-navigation.html#startpage}{\\startpage}, - \l {17-qdoc-commands-thread.html#threadsafe}{\\threadsafe}, - \l {20-qdoc-commands-title.html#title}{\\title} + \page 14-qdoc-commands-contextcommands.html + \previouspage Topic Commands + \contentspage Table of Contents + \nextpage Document Navigation + + \title Context Commands + + The context commands provide information about the element being + documented that QDoc can't deduce on its own. e.g. Is a class + thread-safe? Is a function reentrant? Which module is the class a + member of? Context commands can appear anywhere in a QDoc comment, + but they are normally placed near the top of the comment, just + below the \l {Topic Commands} {topic} command. - \section1 Categories \list - \o \l {Navigation Commands} - \o \l {Status Commands} - \o \l {Thread Support Commands} - \o \l {Relating Commands} - \o \l {Grouping Commands} - \o \l {Title Commands} + \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 {18-qdoc-commands-relating.html#inherits-command}{\\inherits}, + \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 + */ /*! \page 15-qdoc-commands-navigation.html - \previouspage Contextual Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Status Commands - - \title Navigation Commands - - 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. + \previouspage Context Commands + \contentspage Table of Contents + \nextpage Reporting Status - \section1 Alphabetical List + \title Document Navigation - \l {15-qdoc-commands-navigation.html#contentspage}{\\contentspage}, - \l {15-qdoc-commands-navigation.html#indexpage}{\\indexpage}, - \l {15-qdoc-commands-navigation.html#nextpage}{\\nextpage}, - \l {15-qdoc-commands-navigation.html#previouspage}{\\previouspage}, - \l {15-qdoc-commands-navigation.html#startpage}{\\startpage} + 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 shows a typical example using the - navigation commands. + \section1 Example \code / *! \page basicqt.html - \contentspage {Basic Qt}{Contents} + \contentspage {Basic Qt} {Contents} \nextpage Getting Started \indexpage Index @@ -5885,7 +5791,7 @@ / *! \page gettingstarted.html \previouspage Basic Qt - \contentspage {Basic Qt}{Contents} + \contentspage {Basic Qt} {Contents} \nextpage Creating Dialogs \indexpage Index @@ -5901,7 +5807,7 @@ / *! \page creatingdialogs.html \previouspage Getting Started - \contentspage {Basic Qt}{Contents} + \contentspage {Basic Qt} {Contents} \indexpage Index \startpage Basic Qt @@ -5927,8 +5833,7 @@ * / \endcode - The second page of this multipage document, "Getting Started", - will be rendered as + QDoc renders the "Getting Started" page in \c{creatingdialogs.html}: \quotation \raw HTML @@ -5963,18 +5868,16 @@ \endraw \endquotation - in creatingdialogs.html. - - In addition, the \l {indexpage}{\\indexpage} and \l - {startpage}{\\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 @@ -5986,414 +5889,377 @@ </head> \endcode - \section1 Command Descriptions - - \table - \header - \o Command - \o Description - - \row - \o \bold \\previouspage \target previouspage - \o \bold {The \\previouspage command links the current page - to the previous one in an ordered series of documents}. - - 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. - - 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. + \section1 Commands - \row - \o \bold \\nextpage \target nextpage - \o \bold {The \\nextpage command links the current - page to the next page in an ordered series of documents}. + \target previouspage-command + \section2 \\previouspage - The command follows the same syntax and argument convention - as the \l {previouspage}{\\previouspage} command. + 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. - For an example, see the \l {General Description} section. + The command must stand alone on its own line. - \row - \o \bold \\startpage \target startpage - \o \bold {The \\startpage command specifies the first document - in a collection of documents.} + \target nextpage-command + \section2 \\nextpage - The command must stand alone on its own line, and its - unique argument is the title of the first document. + 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. - 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. + \target startpage-command + \section2 \\startpage - 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. - \row - \o \bold \\contentspage \target contentspage - \o \bold {The \\contentspage command links the current - page to a contents page}. + 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. - The command follows the same syntax and argument convention - as the \l {previouspage}{\\previouspage} command. + \target contentspage-command + \section2 \\contentspage - For an example, see the \l {General Description} section. - - \row - \o \bold \\indexpage \target indexpage - \o \bold {The \\indexpage command specifies a document providing - an index for the current document}. + 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. - The command must stand alone on its own line, and its - unique argument is the title of the index document. + \target indexpage-command + \section2 \\indexpage - 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. + 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. - For an example, see the \l {General Description} section. - - \endtable + 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. */ /*! \page 16-qdoc-commands-status.html - \previouspage Navigation Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Thread Support Commands + \previouspage Document Navigation + \contentspage Table of Contents + \nextpage Thread Support - \title Status Commands + \title Reporting Status - The usage commands can indicate whether a documented object is - under development, becoming obsolete, provided for compatibility - reasons or simply not part of the public interface. They can - describe the history of minor versions. And they can also describe - a documented object's ability to handle multithreaded programming. + These commands are for indicating that a documented element is + still under development, is becoming obsolete, is provided for + compatibility reasons, or is simply not to be included in the + public interface. The \l {since-command}{\\since} command is for + including information about the version when a function or class + first appeared. - \section1 Alphabetical List + \target compat-command + \section1 \\compat - \l {16-qdoc-commands-status.html#compat}{\\compat}, - \l {16-qdoc-commands-status.html#internal}{\\internal}, - \l {16-qdoc-commands-status.html#obsolete}{\\obsolete}, - \l {16-qdoc-commands-status.html#preliminary}{\\preliminary}, - \l {16-qdoc-commands-status.html#since}{\\since} + The \\compat command is for indicating that a class or function is + part of the support library provided to keep old source code + working. - \section1 Command Description + The command must stand on its own line. - \table - \header - \o Command - \o Description - - \row - \o \bold \\preliminary \target preliminary - \o \bold {The \\preliminary command indicates that the - referenced function is under development.} - - The command must stand on its own line. + Usually an equivalent function or class is provided as an + alternative. - The \\preliminary command expands to a notification in the - function documentation, and marks the function as - preliminary when it appears in lists. 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 - / *! - \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 + / *! + \class MyQt3SupportClass + \compat + * / + \endcode - will be rendered as + QDoc renders this at the top of the MyQt3SupportClass class + reference page. - \quotation - \raw HTML - <h3> - <a href="http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum">Joining</a> - QChar::joining () const</h3> - \endraw + \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 - \bold {This function is under development and - is subject to change.} + 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. - Returns information about the joining properties of the - character (needed for certain languages such as - Arabic). - \endquotation + \code + / *! + \fn MyClass::MyQt3SupportMemberFunction + \compat - And the function's entry in QChar's list of functions will - be rendered as + Use MyNewFunction() instead. + * / + \endcode - \quotation - \list - \o ... - \o Joining - \l {http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum} - {joining}() - const \c (preliminary) - \o ... - \endlist - \endquotation + QDoc renders this in \c{myclass-qt3.html} as: - \row - \o \bold \\obsolete \target obsolete - \o \bold {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. + \quotation + \raw HTML + <h1>Qt 3 Support Members for MyClass</h1> + \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 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. - For example: + ... - \code - / *! - \fn MyClass::MyObsoleteFunction - \obsolete + \list + \o void MyQt3SupportMemberFunction() + \o ... + \endlist - Use MyNewFunction() instead. - * / - \endcode + \raw HTML + <hr /> + <h2>Member Function Documentation</h2> + <h3>void MyQt3SupportMemberFunction ()</h3> + <p>Use MyNewFunction() instead.</p> + \endraw + ... + \endquotation - will be rendered as + \target default-command + \section1 \\default \span {class="newStuff"} {(new)} - \quotation - \raw HTML - <h1>Obsolete Members for MyClass</h1> - \endraw + The \\default command is for marking a QML property as the + \l {http://doc.trolltech.com/4.7/qdeclarativeintroduction.html#default-properties} + {default property}. The word \span {class="newStuff"} {default} is shown in red in + the documentation of the property. - \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 + / *! + \qmlproperty list<Change> State::changes + This property holds the changes to apply for this state + \default - ... + By default these changes are applied against the default state. If the state + extends another state, then the changes are applied against the state being + extended. + * / + \endcode - \list - \o void MyObsoleteFunction() \c (obsolete) - \o ... - \endlist + See how QDoc renders this property on the reference page for the + \l {http://doc.trolltech.com/4.7/qml-state.html#changes-prop} {State} + element. - \raw HTML - <hr /> - <h2>Member Function Documentation</h2> - <h3>void MyObsoleteFunction ()</h3> - <p>Use MyNewFunction() instead.</p> - \endraw + \target obsolete-command + \section1 \\obsolete - ... - \endquotation + 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. - in myclass-obsolete.html + The command must stand on its own line. + 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. - \row - \o \bold \\compat \target compat - \o \bold {The \\compat command indicates that the referenced class - or function is part of the support library provided to keep - old source code working.} + \code + / *! + \fn MyClass::MyObsoleteFunction + \obsolete - The command must stand on its own line. + Use MyNewFunction() instead. + * / + \endcode - Usually an equivalent function or class is provided as an - alternative. + QDoc renders this in \c{myclass-obsolete.html} as: - 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: + \quotation + \raw HTML + <h1>Obsolete Members for MyClass</h1> + \endraw - \code - / *! - \class MyQt3SupportClass - \compat - * / - \endcode + \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. - will be rendered 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 + \list + \o void MyObsoleteFunction() \c (obsolete) + \o ... + \endlist - on the top of the MyQt3SupportClass class reference. + \raw HTML + <hr /> + <h2>Member Function Documentation</h2> + <h3>void MyObsoleteFunction ()</h3> + <p>Use MyNewFunction() instead.</p> + \endraw + ... + \endquotation - 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: + \target internal-command + \section1 \\internal - \code - / *! - \fn MyClass::MyQt3SupportMemberFunction - \compat + The \\internal command indicates that the referenced + function is not part of the public interface. - Use MyNewFunction() instead. - * / - \endcode + The command must stand on its own line. - will be rendered as + QDoc ignores the documentation as well as the documented item, + when generating the associated class reference documenation. - \quotation - \raw HTML - <h1>Qt 3 Support Members for MyClass</h1> - \endraw + \code + / *! + \internal - \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. + 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. - \list - \o void MyQt3SupportMemberFunction() - \o ... - \endlist + \target preliminary-command + \section1 \\preliminary - \raw HTML - <hr /> - <h2>Member Function Documentation</h2> - <h3>void MyQt3SupportMemberFunction ()</h3> - <p>Use MyNewFunction() instead.</p> - \endraw + The \\preliminary command is for indicating that a referenced + function is still under development. - ... - \endquotation + The command must stand on its own line. - in myclass-qt3.html + The \\preliminary command expands to a notification in the + function documentation, and marks the function as preliminary when + it appears in lists. + \code + / *! + \preliminary - \row - \o \bold \\internal \target internal - \o \bold {The \\internal command indicates that the referenced - function is not part of the public interface.} + 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 - The command must stand on its own line. + QDoc renders this as: - QDoc ignores the documentation as well as the documented - item, when generating the associated class reference - documenation. For example: + \quotation + \raw HTML + <h3> + <a href="http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum">Joining</a> + QChar::joining () const</h3> + \endraw - \code - / *! - \internal + \bold {This function is under development and + subject to change.} - 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 + Returns information about the joining properties of the + character (needed for certain languages such as + Arabic). + \endquotation - in qspinbox.cpp, will not be rendered at all. + And the function's entry in QChar's list of functions will be + rendered as: - \row - \o \bold \\since \target since - \o \bold {The \\since command tells in which minor release - the associated functionality was added.} + \quotation + \list + \o ... + \o Joining + \l {http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum} + {joining}() + const \c (preliminary) + \o ... + \endlist + \endquotation - For example: + \target since-command + \section1 \\since - \code - / *! - \since 4.1 + The \\since command tells in which minor release + the associated functionality was added. - Returns an icon for \a standardIcon. + \code + / *! + \since 4.1 - ... + Returns an icon for \a standardIcon. - \sa standardIconImplementation(), standardPixmap() - * / - QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const - { - } - \endcode + ... - will be rendered as + \sa standardIconImplementation(), standardPixmap() + * / + QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const + { + } + \endcode - \quotation - \raw HTML - <h3>QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const</h3> - \endraw + QDoc renders this as: - This function was introduced in Qt version 4.1 + \quotation + \raw HTML + <h3>QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const</h3> + \endraw - Returns an icon for \a standardIcon. + This function was introduced in Qt version 4.1 - ... + Returns an icon for \a standardIcon. - 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 {QStyle::standardIconImplementation()} + {standardIconImplementation()} and \l + {QStyle::standardPixmap()} {standardPixmap()}. + \endquotation - See also \l - {25-qdoc-configuration-derivedprojects.html#project}{\c - project}. + 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. - \endtable + See also \l {25-qdoc-configuration-derivedprojects.html#project} + {\c project}. */ /*! \page 17-qdoc-commands-thread.html - \previouspage Status Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Relating Commands - - \title Thread Support Commands - - The thread support commands specify the level of support for - multithreaded programming of a class or function. - - \section1 Alphabetical List + \previouspage Reporting Status + \contentspage Table of Contents + \nextpage Relating Things - \l {17-qdoc-commands-thread.html#nonreentrant}{\\nonreentrant}, - \l {17-qdoc-commands-thread.html#reentrant}{\\reentrant}, - \l {17-qdoc-commands-thread.html#threadsafe}{\\threadsafe} + \title Thread Support - \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 @@ -6406,15 +6272,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}{\\reentrant} and \l {threadsafe}{\\threadsafe} - commands respectively, functions in the referenced class can be - declared \c nonreentrant, using the \l - {nonreentrant}{\\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 @@ -6453,7 +6318,7 @@ } \endcode - will be rendered as + QDoc renders this as: \quotation \raw HTML @@ -6468,8 +6333,8 @@ \endcode \bold {Note:} All the functions in this class are \l - {threads.html#reentrant}{reentrant}, except \l - {QLocale::setDefault()}{setDefault()}. + {threads.html#reentrant} {reentrant}, except \l + {QLocale::setDefault()} {setDefault()}. ... @@ -6495,8 +6360,8 @@ \warning This function is not reentrant. - See also \l {QLocale::system()}{system()} and \l - {QLocale::c()}{c()}. + See also \l {QLocale::system()} {system()} and \l + {QLocale::c()} {c()}. ... \endquotation @@ -6504,7 +6369,7 @@ As shown above, QDoc generates a notification when a class is declared reentrant, and lists the exceptions (the declared nonreentrant functions). A link to the general documentation on \l - {threads.html#reentrant}{reentrancy and thread-safety} is + {threads.html#reentrant} {reentrancy and thread-safety} is included. In addition a warning, "\bold Warning: This function is not reentrant.", is generated in the nonreentrant functions' documentation. @@ -6513,514 +6378,488 @@ is declared threadsafe. For more information see the general documentation on \l - {threads.html#reentrant}{reentrancy and thread-safety}. + {threads.html#reentrant} {reentrancy and thread-safety}. - \section1 Command Descriptions + \section1 Commands - \table - \header - \o Command - \o Description + \target threadsafe-command + \section2 \\threadsafe - \row - \o \bold \\threadsafe \target threadsafe - \o \bold {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}{\\reentrant} command. For an example, see - the \l {General Description} section. + 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}{\\reentrant} and - \l{nonreentrant}{\\nonreentrant}. + See also \l{reentrant-command} {\\reentrant} and + \l{nonreentrant-command} {\\nonreentrant}. - \row - \o \bold \\reentrant \target reentrant - \o \bold {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.} + \target reentrant-command + \section2 \\reentrant - The command must stand on its own line. + 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. - For an example, see the \l {General Description} section. + The command must stand on its own line. - See also \l{nonreentrant}{\\nonreentrant} and - \l{threadsafe}{\\threadsafe}. + See also \l{nonreentrant-command} {\\nonreentrant} and + \l{threadsafe-command} {\\threadsafe}. - \row - \o \bold \\nonreentrant \target nonreentrant - \o \bold {The \\nonreentrant command indicates that the - associated class or function cannot be called by - multiple threads.} + \target nonreentrant-command + \section2 \\nonreentrant - The command must stand on its own line. + The \\nonreentrant command indicates that the associated class or + function cannot be called by multiple threads. Nonreentrant is the + default case. - For an example, see the \l {General Description} section. + The command must stand on its own line. - See also \l{reentrant}{\\reentrant} and - \l{threadsafe}{\\threadsafe}. + 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. - \endtable + See also \l{reentrant-command} {\\reentrant} and + \l{threadsafe-command} {\\threadsafe}. */ /*! \page 18-qdoc-commands-relating.html - \previouspage Thread Support Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Grouping Commands + \previouspage Thread Support + \contentspage Table of Contents + \nextpage Grouping Things - \title Relating Commands + \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 + is an overload of another function, or this function is a + reimplementation of another function, or this typedef is \e + related to some class or header file. There is also a command + for documenting that a QML element inherits some other QML + element. - \section1 Alphabetical List + \section1 Commands - \l {18-qdoc-commands-relating.html#overload}{\\overload}, - \l {18-qdoc-commands-relating.html#reimp}{\\reimp}, - \l {18-qdoc-commands-relating.html#relates}{\\relates}, + \target inherits-command + \section2 \\inherits \span {class="newStuff"} {(new)} - \section1 Command Descriptions + The \\inherits command is for documenting that one QML element + inherits some other QML element. It must be included in the + inheriting element's \l{qmlclass-command}{\\qmlclass} comment. + The argument is the name of the inherited QML element. - \table - \header - \o Command - \o Description + \code + / *! + \qmlclass PauseAnimation QDeclarativePauseAnimation + \ingroup qml-animation-transition + \since 4.7 + \inherits Animation + \brief The PauseAnimation element provides a pause for an animation. - \row - \o \bold \\overload \target overload - \o \bold {The \\overload command indicates that the - function is a secondary overload of its name.} + When used in a SequentialAnimation, PauseAnimation is a step + when nothing happens, for a specified duration. - The command must stand on its own line. + A 500ms animation sequence, with a 100ms pause between two animations: - 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. + SequentialAnimation { + NumberAnimation { ... duration: 200 } + PauseAnimation { duration: 100 } + NumberAnimation { ... duration: 200 } + } - From Qt 4.5, you can include the function name plus '()' - as a parameter to the \bold{\\overload} command, which - will include a standard \i{This function overloads...} - line of text with a link to the documentation for the - primary version of the function. + \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} + * / + \endcode - For example: + QDoc includes this line on the reference page for the + \l{http://doc.trolltech.com/4.7/qml-pauseanimation.html} {PauseAnimation} + element: - \code - / *! - \overload addAction() + \quotation + Inherits \l{http://doc.trolltech.com/4.7/qml-animation.html} {Animation} + \endquotation - 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. + \target overload-command + \section2 \\overload - \sa QWidget::addAction() - * / - QAction *QMenu::addAction(const QIcon &icon, const QString &text) - { - QAction *ret = new QAction(icon, text, this); - addAction(ret); - return ret; - } - \endcode + The \\overload command is for indicating that a function is a + secondary overload of its name. - will be rendered as + The command must stand on its own line. - \quotation - \raw HTML - <h3><a href="http://qt.nokia.com/doc/4.0/qaction.html">QAction</a> - * QMenu::addAction ( const QIcon & <i>icon</i>, - const QString & <i>text</i> ) - </h3> - \endraw + 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. - This function overloads \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction}{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 - \i icon and some \i text. The function adds the newly - created action to the menu's list of actions, and - returns it. + \code + / *! + \overload 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 + \a icon and some \a 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: + \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 - This is an overloaded member function, provided for - convenience. - \endquotation. + QDoc renders this as: - \row - \o \bold \\reimp \target reimp - \o \bold {The \\reimp command indicates that the - referenced function is a reimplementation of a virtual function, - where the reimplementation has no effect on the interface.} + \quotation + \raw HTML + <h3><a href="http://qt.nokia.com/doc/4.0/qaction.html">QAction</a> + * QMenu::addAction ( const QIcon & <i>icon</i>, + const QString & <i>text</i> ) + </h3> + \endraw - The command must stand on its own line. + This function overloads \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction} {addAction()} - QDoc will omit the reimplemented function from the class - reference. For example: + 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. - \code - / *! - \reimp - * / - void QToolButton::nextCheckState() - { - Q_D(QToolButton); - if (!d->defaultAction) - QAbstractButton::nextCheckState(); - else - d->defaultAction->trigger(); - } - \endcode + See also + \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction} + {QWidget::addAction}(). + \endquotation - will not be rendered at all; only a link to the inherited - QAbstractButton::nextCheckState() will appear in the - documentation. + 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: - \row - \o \bold \\relates \target relates - \o \bold {The \\relates command attaches the documentation of - a global function to that of a related class or header file.} + \quotation + This is an overloaded member function, provided for + convenience. + \endquotation. - The command's argument is a class name, an the command (and - its argument) must stand on its own line. + \target reimp-command + \section2 \\reimp - \code - / *! - \relates QChar + The \\reimp command is for indicating that a function is a + reimplementation of a virtual function. - Reads a char from the stream \a in into char \a chr. + The command must stand on its own line. - \sa {Format of the QDataStream operators} - * / - QDataStream &operator>>(QDataStream &in, QChar &chr) - { - quint16 u; - in >> u; - chr.unicode() = ushort(u); - return in; - } - \endcode + QDoc will omit the reimplemented function from the class + reference. - will be rendered with the QChar documentation. + \code + / *! + \reimp + * / + void QToolButton::nextCheckState() + { + Q_D(QToolButton); + if (!d->defaultAction) + QAbstractButton::nextCheckState(); + else + d->defaultAction->trigger(); + } + \endcode - \endtable + 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 + \section2 \\relates + + 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. + + \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. */ /*! \page 19-qdoc-commands-grouping.html - \previouspage Relating Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Title Commands + \previouspage Relating Things + \contentspage Table of Contents + \nextpage Naming Things - \title Grouping Commands + \title Grouping Things The grouping commands relate classes to defined groups and modules. The groups are used when generating lists of related classes in the documentation, while the modules are elements of Qt's structure. - \section1 Alphabetical List + \section1 Commands - \l {19-qdoc-commands-grouping.html#ingroup}{\\ingroup}, - \l {19-qdoc-commands-grouping.html#inmodule}{\\inmodule}, - \l {19-qdoc-commands-grouping.html#mainclass}{\\mainclass}, + \target mainclass-command + \section2 \\mainclass - \section1 Command Descriptions + The \\mainclass command relates the documented class to + a group called mainclasses. - \table - \header - \o Command - \o Description + The command must stand on its own line. - \row - \o \bold \\mainclass \target mainclass - \o \bold {The \\mainclass command relates the documented class to - a group called mainclasses.} + \code + / *! + \class QWidget qwidget.h + \brief The QWidget class is the base class of + all user interface objects. - The command must stand on its own line. + \mainclass - For example: + ... + * / + \endcode - \code - / *! - \class QWidget qwidget.h - \brief The QWidget class is the base class of - all user interface objects. + 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: - \mainclass + \l http://qt.nokia.com/doc/4.0/mainclasses.html - ... - * / - \endcode + \note The Qt documentation no longer includes the \e mainclasses + page. - 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}{\\generatelist} command with the \c - mainclasses argument: + See also \l {generatelist-command} {\\generatelist}. - \l http://qt.nokia.com/doc/4.0/mainclasses.html + \target ingroup-command + \section2 \\ingroup - See also \l {generatelist}{\\generatelist}. + The \\ingroup command indicates that the given + overview or documented class belongs to a certain group of + related docmentation. - \row - \o \bold \\ingroup \target ingroup + A class or overview may belong to many groups. - \o \bold {The \\ingroup command indicates that the given - overview or documented class belongs to a certain group of - related docmentation.} + 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. - A class or overview may belong to many groups. + \code + / *! + \class QDir + \brief The QDir class provides access to directory + structures and their contents. - 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: + \ingroup io + ... + * / + \endcode - \code - / *! - \class QDir - \brief The QDir class provides access to directory - structures and their contents. + 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. - \ingroup io - ... - * / - \endcode + 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. - 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}{\\group} command - with the \c io argument. + See also \l {group-command} {\\group}. - Note that to list overviews that are related to a given - group, you must generate the list exlicitly by using the \l - {generatelist}{\\generatelist} command with the \c related - argument. + \target inmodule-command + \section2 \\inmodule - See also \l {group}{\\group}. - \row - \o \bold \\inmodule \target inmodule - \o \bold {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. - \code - /*! - \class QDesignerTaskMenuExtension - \inmodule QtDesigner - * / - \endcode + \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}{\\generatelist} command with - the \c {{classesbymodule QtDesigner}} argument. + 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}{\\module} and \l - {generatelist}{\\generatelist}. - \endtable + See also \l {module-command} {\\module} and \l + {generatelist-command} {\\generatelist}. */ /*! - \page 20-qdoc-commands-title.html - \previouspage Grouping Commands - \contentspage QDoc Manual - Table of Contents - \nextpage QDoc Configuration - - \title Title Commands - - 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. - - \section1 Alphabetical List - - \l {20-qdoc-commands-title.html#title}{\\title}, - \l {20-qdoc-commands-title.html#subtitle}{\\subtitle} - - \section1 Command Descriptions + \page 20-qdoc-commands-namingthings.html + \previouspage Grouping Things + \contentspage Table of Contents + \nextpage Markup Commands - \table - \header - \o Command - \o Description + \title Naming Things - \row - \o \bold \\title \target title - \o \bold {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 and 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 - will be rendered 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 - <h1><center>Signal and Slots</center></h1> - \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}{\\subtitle}. + \quotation + \raw HTML + <h1><center>Signal and Slots</center></h1> + \endraw - \row - \o \bold \\subtitle \target subtitle - \o \bold {The \\subtitle command sets a subtitle for a - documentation page.} + 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}. - For example: + \target subtitle-command + \section2 \\subtitle - \code - / *! - \page qtopiacore-overview.html + The \\subtitle command sets a subtitle for a documentation page. - \title Qtopia Core - \subtitle Qt for Embedded Linux + \code + / *! + \page qtopiacore-overview.html - 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. + \title Qtopia Core + \subtitle Qt for Embedded Linux - ... - * / - \endcode + 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 - will be rendered as + QDoc renders this as: - \quotation - \raw HTML - <h1><center>Qtopia Core</center></h1> - <h2><center>Qt for Embedded Linux</center></h2> - \endraw + \quotation + \raw HTML + <h1><center>Qtopia Core</center></h1> + <h2><center>Qt for Embedded Linux</center></h2> + \endraw - 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. + 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 - ... - \endquotation + See also \l {title-command} {\\title}. - See also \l {title}{\\title}. - \endtable */ /*! \page 21-0-qdoc-configuration.html - \previouspage Title Commands - \contentspage QDoc Manual - Table of Contents - \nextpage General Configuration Variables - - \title QDoc Configuration - - \tableofcontents + \previouspage Miscellaneous + \contentspage Table of Contents + \nextpage Generic Configuration Variables - \list - \o \l {Supporting Derived Projects} - \o \l {QDoc Compatibility} - \endlist + \title The QDoc Configuration File - When running QDoc to generate the documentation, you must specify - a configuration file on the command line: + Before running QDoc, you must create a QDoc configuration file to + tell QDoc where to find the source files that contain the QDoc + comments. The pathname to your configuration file is passed to + QDoc on the command line: \quotation - \bold {/currentdirectory$ qdoc3 my-documentation.qdocconf} + \c {/current/dir$ ../../bin/qdoc3 ./config.qdocconf} \endquotation \section1 General Description - The configuration file is a list of entries of entries of the form - \i {"variable = value"}. Using the configuration variables, you - can define where QDoc should find the various source files, images - and examples, where to put generated documentation etc. The + The configuration file is a list of entries of the form \e + {"variable = value"}. Using the configuration variables, you can + define where QDoc should find the various source files, images and + examples, where to put generated documentation etc. The configuration file can also contain directives like \c include. For an example, see the \l minimum.qdocconf file. - In addition, you can use some particular configuration variables - to make QDoc support derived projects, i.e make the projects, for - example Qt Solutions, contain links to the online Qt - documentation. These variables are documented in the \l - {Supporting Derived projects} section. In this section you can - also find out how to use these variables to support your derived - projects. - - If some of the variable keys have the same values, they can be set - at the same time. For example: - - \code - {header, source}dirs = kernel - \endcode - - is equivalent to - - \code - headerdirs = kernel - sourcedirs = kernel - \endcode + You can also use configuration variables to get QDoc to support + \l{Supporting Derived Projects} {derived projects}, i.e QDoc can + generate links in your project's documentation to elements in the + Qt online documentation. See the \l {Supporting Derived projects} + section. - A variable's value can be set using either '=' or '+='. The - difference is that '=' overrides any previously set value, while - '+=' only adds the value to the previously set ones. + The value of a configuration variable can be set using either '=' + or '+='. The difference is that '=' overrides the previous value, + while '+=' adds a new value to the current one. - In general, some of the variables accepts a list of strings as - their value, while others only accept a single string. If you - provide a variable of the latter type with several strings they - will simply be concatenated. The quotes around the value string - are optional. But applying them allows you to use special - characters like '=' and ' \" ' within the string. For example: + Some configuration variables accept a list of strings as their + value, e.g. + \l {22-qdoc-configuration-generalvariables.html#sourcedirs-variable} + {\c{sourcedirs}}, while others accept only a single string. Double + quotes around a value string are optional, but including them allows + you to use special characters like '=' and ' \" ' within the valuem + string, e.g.: \code HTML.postheader = "<a href=\"index.html\">Home</a>" @@ -7037,54 +6876,46 @@ \section1 Configuration Variables - \section2 Alphabetical List - - \l {22-qdoc-configuration-generalvariables.html#alias}{alias}, - \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoredirectives} - {Cpp.ignoredirectives}, - \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoretoken} - {Cpp.ignoretokens}, - \l {22-qdoc-configuration-generalvariables.html#definesvariable}{defines}, - \l {22-qdoc-configuration-generalvariables.html#edition}{edition}, - \l {22-qdoc-configuration-generalvariables.html#exampledirs}{exampledirs}, - \l {22-qdoc-configuration-generalvariables.html#examples}{examples}, - \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions} - {examples.fileextensions}, - \l {22-qdoc-configuration-generalvariables.html#extraimages}{extraimages}, - \l {22-qdoc-configuration-generalvariables.html#falsehoods}{falsehoods}, - \l {22-qdoc-configuration-generalvariables.html#headerdirs}{headerdirs}, - \l {22-qdoc-configuration-generalvariables.html#headers}{headers}, - \l {22-qdoc-configuration-generalvariables.html#headers.fileextensions} - {headers.fileextensions}, - \l {24-qdoc-configuration-htmlvariables.html#HTML.footer}{HTML.footer}, - \l {24-qdoc-configuration-htmlvariables.html#HTML.postheader} - {HTML.postheader}, - \l {24-qdoc-configuration-htmlvariables.html#HTML.style}{HTML.style}, - \l {22-qdoc-configuration-generalvariables.html#imagedirs}{imagedirs}, - \l {22-qdoc-configuration-generalvariables.html#images}{images}, - \l {22-qdoc-configuration-generalvariables.html#images.fileextensions} - {images.fileextensions}, - \l {22-qdoc-configuration-generalvariables.html#language}{language}, - \l {22-qdoc-configuration-generalvariables.html#macro}{macro}, - \l {22-qdoc-configuration-generalvariables.html#outputdir}{outputdir}, - \l {22-qdoc-configuration-generalvariables.html#outputformats} - {outputformats}, - \l {22-qdoc-configuration-generalvariables.html#outputprefixes} - {outputprefixes}, - \l {22-qdoc-configuration-generalvariables.html#slow}{slow}, - \l {22-qdoc-configuration-generalvariables.html#sourcedirs}{sourcedirs}, - \l {22-qdoc-configuration-generalvariables.html#sources}{sources}, - \l {22-qdoc-configuration-generalvariables.html#sources.fileextensions} - {sources.fileextensions}, - \l {22-qdoc-configuration-generalvariables.html#spurious}{spurious}, - \l {22-qdoc-configuration-generalvariables.html#tabsize}{tabsize}, - \l {22-qdoc-configuration-generalvariables.html#version}{version}, - \l {22-qdoc-configuration-generalvariables.html#versionsym}{versionsym} - - \section2 Categories + \section1 Variable List + + \list + \o \l {22-qdoc-configuration-generalvariables.html#alias-variable} {alias} + \o \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoredirectives-variable} {Cpp.ignoredirectives} + \o \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoretokens-variable} {Cpp.ignoretokens} + \o \l {22-qdoc-configuration-generalvariables.html#defines-variable} {defines} + \o \l {22-qdoc-configuration-generalvariables.html#edition-variable} {edition} + \o \l {22-qdoc-configuration-generalvariables.html#exampledirs-variable} {exampledirs} + \o \l {22-qdoc-configuration-generalvariables.html#examples-variable} {examples} + \o \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions-variable} {examples.fileextensions} + \o \l {22-qdoc-configuration-generalvariables.html#extraimages-variable} {extraimages} + \o \l {22-qdoc-configuration-generalvariables.html#falsehoods-variable} {falsehoods} + \o \l {22-qdoc-configuration-generalvariables.html#headerdirs-variable} {headerdirs} + \o \l {22-qdoc-configuration-generalvariables.html#headers-variable} {headers} + \o \l {22-qdoc-configuration-generalvariables.html#headers.fileextensions-variable} {headers.fileextensions} + \o \l {24-qdoc-configuration-htmlvariables.html#HTML.footer-variable} {HTML.footer} + \o \l {24-qdoc-configuration-htmlvariables.html#HTML.postheader-variable} {HTML.postheader} + \o \l {24-qdoc-configuration-htmlvariables.html#HTML.style-variable} {HTML.style} + \o \l {22-qdoc-configuration-generalvariables.html#imagedirs-variable} {imagedirs} + \o \l {22-qdoc-configuration-generalvariables.html#images-variable} {images} + \o \l {22-qdoc-configuration-generalvariables.html#images.fileextensions-variable} {images.fileextensions} + \o \l {22-qdoc-configuration-generalvariables.html#language-variable} {language} + \o \l {22-qdoc-configuration-generalvariables.html#macro-variable} {macro} + \o \l {22-qdoc-configuration-generalvariables.html#outputdir-variable} {outputdir} + \o \l {22-qdoc-configuration-generalvariables.html#outputformats-variable} {outputformats} + \o \l {22-qdoc-configuration-generalvariables.html#slow-variable} {slow} + \o \l {22-qdoc-configuration-generalvariables.html#sourcedirs-variable} {sourcedirs} + \o \l {22-qdoc-configuration-generalvariables.html#sources-variable} {sources} + \o \l {22-qdoc-configuration-generalvariables.html#sources.fileextensions-variable} {sources.fileextensions} + \o \l {22-qdoc-configuration-generalvariables.html#spurious-variable} {spurious} + \o \l {22-qdoc-configuration-generalvariables.html#tabsize-variable} {tabsize} + \o \l {22-qdoc-configuration-generalvariables.html#version-variable} {version} + \o \l {22-qdoc-configuration-generalvariables.html#versionsym-variable} {versionsym} + \endlist + + \section1 Categories \list - \o \l {General Configuration Variables} + \o \l {Generic Configuration Variables} \o \l {C++ Specific Configuration Variables} \o \l {HTML Specific Configuration Variables} \endlist @@ -7099,8 +6930,9 @@ /*! \page 21-1-minimum-qdocconf.html - \previouspage QDoc Configuration - \contentspage QDoc Manual - Table of Contents + \previouspage qt.qdocconf + \contentspage Table of Contents + \nextpage Table of Contents \title minimum.qdocconf @@ -7109,8 +6941,9 @@ /*! \page 21-2-qt-qdocconf.html - \previouspage QDoc Configuration - \contentspage QDoc Manual - Table of Contents + \previouspage Compatibility Issues + \contentspage Table of Contents + \nextpage minimum.qdocconf \title qt.qdocconf @@ -7119,11 +6952,11 @@ /*! \page 22-qdoc-configuration-generalvariables.html - \previouspage QDoc Configuration - \contentspage QDoc Manual - Table of Contents + \previouspage The QDoc Configuration File + \contentspage Table of Contents \nextpage Creating Help Project Files - \title General Configuration Variables + \title Generic Configuration Variables With the general QDoc configuration variables, you can define where QDoc will find the various source files it needs to generate @@ -7131,938 +6964,877 @@ documentation. You can also do some minor manipulation of QDoc itself, controlling its output and processing behavior. - \section1 Alphabetical List - - \l {22-qdoc-configuration-generalvariables.html#alias}{alias}, - \l {22-qdoc-configuration-generalvariables.html#codeindent}{codeindent}, - \l {22-qdoc-configuration-generalvariables.html#definesvariable}{defines}, - \l {22-qdoc-configuration-generalvariables.html#edition}{edition}, - \l {22-qdoc-configuration-generalvariables.html#exampledirs}{exampledirs}, - \l {22-qdoc-configuration-generalvariables.html#examples}{examples}, - \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions} - {examples.fileextensions}, - \l {22-qdoc-configuration-generalvariables.html#extraimages}{extraimages}, - \l {22-qdoc-configuration-generalvariables.html#falsehoods}{falsehoods}, - \l {22-qdoc-configuration-generalvariables.html#generateindex}{generateindex}, - \l {22-qdoc-configuration-generalvariables.html#headerdirs}{headerdirs}, - \l {22-qdoc-configuration-generalvariables.html#headers}{headers}, - \l {22-qdoc-configuration-generalvariables.html#headers.fileextensions} - {headers.fileextensions}, - \l {22-qdoc-configuration-generalvariables.html#imagedirs}{imagedirs}, - \l {22-qdoc-configuration-generalvariables.html#images}{images}, - \l {22-qdoc-configuration-generalvariables.html#images.fileextensions} - {images.fileextensions}, - \l {22-qdoc-configuration-generalvariables.html#language}{language}, - \l {22-qdoc-configuration-generalvariables.html#macro}{macro}, - \l {22-qdoc-configuration-generalvariables.html#outputdir}{outputdir}, - \l {22-qdoc-configuration-generalvariables.html#outputformats} - {outputformats}, - \l {22-qdoc-configuration-generalvariables.html#outputprefixes} - {outputprefixes}, - \l {22-qdoc-configuration-generalvariables.html#slow}{slow}, - \l {22-qdoc-configuration-generalvariables.html#sourcedirs}{sourcedirs}, - \l {22-qdoc-configuration-generalvariables.html#sources}{sources}, - \l {22-qdoc-configuration-generalvariables.html#sources.fileextensions} - {sources.fileextensions}, - \l {22-qdoc-configuration-generalvariables.html#spurious}{spurious}, - \l {22-qdoc-configuration-generalvariables.html#tabsize}{tabsize}, - \l {22-qdoc-configuration-generalvariables.html#tagfile}{tagfile}, - \l {22-qdoc-configuration-generalvariables.html#version}{version}, - \l {22-qdoc-configuration-generalvariables.html#versionsym}{versionsym} - - \section1 Variable Descriptions + \target alias-variable + \section1 alias - \table + The \c alias variable renames a QDoc command. - \header - \o Variable - \o Description + The general syntax is \tt {alias.\e{original-command-name} = \e + temporary-command-name}. - \row - \o \bold alias \target alias - \o \bold {The \c alias variable renames a QDoc command.} + \code + alias.i = e + \endcode - The general syntax is \tt {alias.\i{original-command-name} - = \i temporary-command-name}. + This renames the built-in command \\i (italics) to \\e. The \c + alias variable is often used for compatibility reasons; for more + information see the \l {Compatibility Issues} {compatibility + section}. - For example: + See also \l {macro-command} {macro}. - \code - alias.i = e - \endcode + \target codeindent-variable + \section1 codeindent - renames the built-in command \\i (italics) to \\e. + The \c codeindent variable specifies the level of indentation that + QDoc uses when writing code snippets. - The \c alias variable is often used for compatibility - reasons; for more information see the \l {QDoc - Compatibility}{compatibility section}. + QDoc originally used a hard-coded value of four spaces for code + indentation to ensure that code snippets could be easily + distinguished from surrounding text. Since we can use \l{HTML + Specific Configuration Variables#HTML.stylesheets} {stylesheets} + to adjust the appearance of certain types of HTML elements, this + level of indentation is not always required. - See also \l macro. + \target defines-variable + \section1 defines - \row - \o \bold codeindent \target codeindent - \o \bold {The \c codeindent variable specifies the level of - indentation that QDoc uses when writing code snippets.} + The \c defines variable specifies the C++ preprocessor symbols + that QDoc will recognize and respond to. - QDoc originally used a hard-coded value of four spaces for - code indentation to ensure that code snippets could be easily - distinguished from surrounding text. Since we can use - \l{HTML Specific Configuration Variables#HTML.stylesheets}{stylesheets} to - adjust the appearance of certain types of HTML elements, this - level of indentation is not always required. + When a preprocessor symbol is specified using the \c defines + variable, you can also use the \l {if-command} {\\if} command to + enclose documentation that only will be included if the + preprocessor symbol is defined. - \row - \o \bold defines \target definesvariable - \o \bold {The \c defines variable specifies the C++ preprocessor - symbols that QDoc will recognize and respond to.} + The values of the variable are regular expressions (see QRegExp + for details). By default, no symbol is defined, meaning that code + protected with #ifdef...#endif will be ignored. - When a preprocessor symbol is specified using the \c - defines variable, you can also use the \l {if}{\\if} - command to enclose documentation that only will be included - if the preprocessor symbol is defined. + \code + defines = Q_QDOC \ + QT_.*_SUPPORT \ + QT_.*_LIB \ + QT_COMPAT \ + QT3_SUPPORT \ + Q_WS_.* \ + Q_OS_.* \ + Q_BYTE_ORDER \ + __cplusplus + \endcode - The values of the variable are regular expressions (see - QRegExp for details). By default, no symbol is defined, - meaning that code protected with #ifdef...#endif will be - ignored. + This ensures that QDoc will process the code that requires these + symbols to be defined. For example: - For example: + \code + #ifdef Q_WS_WIN + HDC getDC() const; + void releaseDC(HDC) const; + #endif + \endcode - \code - defines = Q_QDOC \ - QT_.*_SUPPORT \ - QT_.*_LIB \ - QT_COMPAT \ - QT3_SUPPORT \ - Q_WS_.* \ - Q_OS_.* \ - Q_BYTE_ORDER \ - __cplusplus - \endcode + Since the Q_WS_.* regular expression (specified using the \c + defines variable) matches Q_WS_WIN, QDoc will process the code + within #ifdef and #endif in our example. - ensures that QDoc will process the code that requires these - symbols to be defined. For example: + You can also define preprocessor symbols manually on the command + line using the -D option. For example: - \code - #ifdef Q_WS_WIN - HDC getDC() const; - void releaseDC(HDC) const; - #endif - \endcode + \code + currentdirectory$ qdoc3 -Dconsoleedition qt.qdocconf + \endcode - Since the Q_WS_.* regular expression (specified using the - \c defines variable) matches Q_WS_WIN, QDoc will process - the code within #ifdef and #endif in our example. + In this case the -D option ensures that the \c consoleedition + preprocessor symbol is defined when QDoc processes the source + files defined in the qt.qdocconf file. - You can also define preprocessor symbols manually on the - command line using the -D option. For example: + See also \l {falsehoods-variable} {falsehoods} and \l {if-command} {\\if}. - \code - currentdirectory$ qdoc3 -Dconsoleedition qt.qdocconf - \endcode + \target edition-variable + \section1 edition - In this case the -D option ensures that the \c - consoleedition preprocessor symbol is defined when QDoc - processes the source files defined in the qt.qdocconf file. + The \c edition variable specifies which modules are included in + each edition of a package, and provides QDoc with information to + provide class lists for each edition. - See also \l falsehoods and \l {if}{\\if}. + This feature is mostly used when providing documentation for Qt + packages. - \row - \o \bold edition \target edition - \o \bold {The \c edition variable specifies which modules are - included in each edition of a package, and provides QDoc - with information to provide class lists for each edition.} + The \c edition variable is always used with a particular edition + name to define the modules for that edition: - This feature is mostly used when providing documentation - for Qt packages. + \code + edition.Console = QtCore QtNetwork QtSql QtXml + edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \ + QtDesigner QtAssistant Qt3Support QAxContainer \ + QAxServer + edition.DesktopLight = QtCore QtGui Qt3SupportLight + \endcode - The \c edition variable is always used with a particular - edition name to define the modules for that edition: + In the above examples, the \c Console edition only includes the + contents of four modules. Only the classes from these modules will + be used when the \l{Miscellaneous#generatelist-command} + {generatelist} command is used to generate a list of classes for + this edition: - \code - edition.Console = QtCore QtNetwork QtSql QtXml - edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \ - QtDesigner QtAssistant Qt3Support QAxContainer \ - QAxServer - edition.DesktopLight = QtCore QtGui Qt3SupportLight - \endcode + \code + \generatelist{classesbyedition Console} + \endcode - In the above examples, the \c Console edition only includes - the contents of four modules. Only the classes from these - modules will be used when the - \l{Miscellaneous Commands#generatelist}{generatelist} command - is used to generate a list of classes for this edition: + \target exampledirs-variable + \section1 exampledirs - \code - \generatelist{classesbyedition Console} - \endcode + The \c exampledirs variable specifies the directories containing + the source code of the example files. - \row - \o \bold exampledirs \target exampledirs - \o \bold {The \c exampledirs variable specifies the directories - containing the source code of the example files.} + The \l {examples-variable} {examples} {examples} and \l + {exampledirs-variable} {exampledirs} variables are used by the \l + {quotefromfile-command} {\\quotefromfile}, \l {quotefile-command} + {\\quotefile} and \l {example-command} {\\example} commands. If + both the \l {examples-variable} {examples} and \l + {exampledirs-variable} {exampledirs} variables are defined, QDoc + will search in both, first in \l {examples-variable} {examples} + then in \l {exampledirs-variable} {exampledirs}. - The \l {examples}{\c examples} and \c exampledirs variables - are used by the \l {quotefromfile}{\\quotefromfile}, \l - {quotefile}{\\quotefile} and \l {example}{\\example} - commands. If both the \l {examples}{\c examples} and \c - exampledirs variables are defined, QDoc will search in - both, first in \l {examples}{\c examples} then in \c - exampledirs. + QDoc will search through the directories in the specified order, + and accept the first matching file it finds. It will only search + in the specified directories, \e not in subdirectories. - QDoc will search through the directories in the specified - order, and accept the first matching file it finds. It will - only search in the specified directories, \i not in - subdirectories. + \code + exampledirs = $QTDIR/doc/src \ + $QTDIR/examples \ + $QTDIR \ + $QTDIR/qmake/examples - For example: + examples = $QTDIR/examples/widgets/analogclock/analogclock.cpp + \endcode - \code - exampledirs = $QTDIR/doc/src \ - $QTDIR/examples \ - $QTDIR \ - $QTDIR/qmake/examples + When processing - examples = $QTDIR/examples/widgets/analogclock/analogclock.cpp - \endcode + \code + \quotefromfile widgets/calculator/calculator.cpp + \endcode - When processing + QDoc will then see if there exists a file called \c calculator.cpp + listed as a value in the \l {examples} {\c examples} variable. If + it doesn't, it will search in the \c exampledirs variable, and + first see if there exists a file called - \code - \quotefromfile widgets/calculator/calculator.cpp - \endcode + \code + $QTDIR/doc/src/widgets/calculator/calculator.cpp + \endcode - QDoc will then see if there exists a file called \c - calculator.cpp listed as a value in the \l {examples}{\c - examples} variable. If it doesn't, it will search in the \c - exampledirs variable, and first see if there exists a file - called + If it doesn't, QDoc will continue looking for a file called - \code - $QTDIR/doc/src/widgets/calculator/calculator.cpp - \endcode + \code + $QTDIR/examples/widgets/calculator/calculator.cpp + \endcode - If it doesn't, QDoc will continue looking for a file - called + and so forth. - \code - $QTDIR/examples/widgets/calculator/calculator.cpp - \endcode + See also \l examples. - and so forth. + \target examples-variable + \section1 examples - See also \l examples. + The \c examples variable allows you to specify individual example + files in addition to those located in the directories specified by + the \l {exampledirs-variable} {\c exampledirs} variable. - \row - \o \bold examples \target examples - \o \bold {The \c examples variable allows you to specify individual - example files in addition to those located in the directories - specified by the \l {exampledirs}{\c exampledirs} variable.} - - The \c examples and \l {exampledirs}{\c exampledirs} - variables are used by the \l - {quotefromfile}{\\quotefromfile}, \l - {quotefile}{\\quotefile} and \l {example}{\\example} - commands. If both the \c examples and \l {exampledirs}{\c - exampledirs} variables are defined, QDoc will search in - both, first in \c examples then in \l {exampledirs}{\c - exampledirs}. - - QDoc will search through the values listed for the \c - examples variable, in the specified order, and accept - the first one it finds. - - For an extensive example, see the \l {exampledirs}{\c - exampledirs} command. But note that if you know the file is - listed in the \c examples variable, you don't need to - specify its path: + The \c examples and \l {exampledirs-variable} {\c exampledirs} + variables are used by the \l {quotefromfile-command} + {\\quotefromfile}, \l {quotefile-command} {\\quotefile} and \l + {example} {\\example} commands. If both the \c examples and \l + {exampledirs-variable} {\c exampledirs} variables are defined, + QDoc will search in both, first in \c examples then in \l + {exampledirs-variable} {\c exampledirs}. - \code - \quotefromfile calculator.cpp - \endcode + QDoc will search through the values listed for the \c examples + variable, in the specified order, and accept the first one it + finds. - See also \l exampledirs. + For an extensive example, see the \l {exampledirs-variable} {\c + exampledirs} command. But note that if you know the file is listed + in the \c examples variable, you don't need to specify its path: - \row - \o \bold examples.fileextensions \target examples.fileextensions - \o \bold {The \c examples.fileextensions variable specifies the - file extensions that qdoc will look for when collecting example - files for display in the documentation.} + \code + \quotefromfile calculator.cpp + \endcode - The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml - and *.ui. However, if + See also \l {exampledirs-variable} {exampledirs}. - The extensions are given as standard wildcard expressions. - You can add a file extension to the filter using '+='. For - example: + \target examples.fileextensions-variable + \section1 examples.fileextensions - \code - examples.fileextensions += *.qrc - \endcode + The \c examples.fileextensions variable specifies the file + extensions that qdoc will look for when collecting example files + for display in the documentation. - See also \l{headers.fileextensions}. + The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml + and *.ui. However, if - \row - \o \bold extraimages \target extraimages - \o \bold {The \c extraimages variable tells QDoc to incorporate - specific images in the generated documentation.} + The extensions are given as standard wildcard expressions. You + can add a file extension to the filter using '+='. For example: - QDoc will not recognize images used within HTML (or any - other markup language). If we want the images to be copied - from the directories specified by \l {imagedirs}{\c - imagedirs} (the images in question must be located in these - directories) to the output directory, we must specify the - images using the \c extraimages variable. + \code + examples.fileextensions += *.qrc + \endcode - The general syntax is \tt {extraimages.\i{format} = \i - image}. The file extension is optional. + See also \l{headers.fileextensions}. - For example, in \l qt.qdocconf we use a couple of images - within the HTML.postheader variable which value is pure - HTML. For that reason, these images are specified using the - \c extraimages variable: + \target extraimages-variable + \section1 extraimages - \code - extraimages.HTML = qt-logo - \endcode + The \c extraimages variable tells QDoc to incorporate specific + images in the generated documentation. - See also \l images and \l imagedirs. + QDoc will not recognize images used within HTML (or any other + markup language). If we want the images to be copied from the + directories specified by \l {imagedirs} {\c imagedirs} (the images + in question must be located in these directories) to the output + directory, we must specify the images using the \c extraimages + variable. - \row - \o \bold falsehoods \target falsehoods - \o \bold {The \c falsehoods variable defines the truth value of - specified preprocessor symbols as false.} + The general syntax is \tt {extraimages.\e{format} = \e image}. The + file extension is optional. - If this variable is not set for a preprocessor symbol, QDoc - assumes its truth value is true. The exception is '0', - which value always is false. + For example, in \l qt.qdocconf we use a couple of images within + the HTML.postheader variable which value is pure HTML. For that + reason, these images are specified using the \c extraimages + variable: - QDoc will recognize, and is able to evaluate, the following - preprocessor syntax: + \code + extraimages.HTML = qt-logo + \endcode - \code - #ifdef NOTYET - ... - #endif + See also \l images and \l imagedirs. - #if defined (NOTYET) - ... - #end if - \endcode + \target falsehoods-variable + \section1 falsehoods - However, faced with unknown syntax like + The \c falsehoods variable defines the truth value of specified + preprocessor symbols as false. - \code - #if NOTYET - ... - #endif - \endcode + If this variable is not set for a preprocessor symbol, QDoc + assumes its truth value is true. The exception is '0', which value + always is false. - QDoc will evaluate it as true by default, \i unless the - preprocessor symbol is specified within the \c falsehoods - variable entry: + QDoc will recognize, and is able to evaluate, the following + preprocessor syntax: - \code - falsehoods = NOTYET - \endcode + \code + #ifdef NOTYET + ... + #endif - See also \l defines. + #if defined (NOTYET) + ... + #end if + \endcode - \row - \o \bold generateindex \target generateindex - \o \bold{The \c generateindex variable contains a boolean value that - specifies whether to generate an index file when HTML documentation - is generated.} - - By default, an index file is always generated with HTML documentation, - so this variable is typically only used when disabling this feature - (by setting the value to \c false) or when enabling index generation - for the WebXML output (by setting the value to \c true). - \row - \o \bold headerdirs \target headerdirs - \o \bold {The \c headerdirs variable specifies the directories - containing the header files associated with the \c .cpp source - files used in the documentation.} + However, faced with unknown syntax like - For example: + \code + #if NOTYET + ... + #endif + \endcode - \code - headerdirs = $QTDIR/src \ - $QTDIR/extensions/activeqt \ - $QTDIR/extensions/motif \ - $QTDIR/tools/designer/src/lib/extension \ - $QTDIR/tools/designer/src/lib/sdk \ - $QTDIR/tools/designer/src/lib/uilib - \endcode + QDoc will evaluate it as true by default, \e unless the + preprocessor symbol is specified within the \c falsehoods variable + entry: - When executed, the first QDoc will do is to read through - the headers specified in the \l {headers}{\c headers} - variable, and the ones located in the directories specified - in the \c headerdir variable (including all - subdirectories), building an internal structure of the - classes and their functions. - - Then it will read through the sources specified in the \l - {sources}{\c sources}, and the ones located in the - directories specified in the \l {sourcedirs}{\c sourcedirs} - varible (including all subdirectories), merging the - documentation with the structure it retrieved from the - header files. - - If both the \c headers and \c headerdirs variables are - defined, QDoc will read through both, first \l {headers}{\c - headers} then \c headerdirs. - - In the specified directories, QDoc will only read the files - with the fileextensions specified in the \l - {headers.fileextensions}{\c headers.fileextensions} - variable. The default extensions are *.ch, *.h, *.h++, - *.hh, *.hpp and *.hxx". The files specified by \l - {headers}{\c headers} will be read independent of their - fileextensions. - - See also \l headers and \l headers.fileextensions. + \code + falsehoods = NOTYET + \endcode - \row - \o \bold headers \target headers - \o \bold {The \c headers variable allows you to specify individual - header files in addition to those located in the directories - specified by the \l {headerdirs}{\c headerdirs} variable.} + See also \l defines. - For example: + \target generateindex-variable + \section1 generateindex - \code - headers = $QTDIR/src/gui/widgets/qlineedit.h \ - $QTDIR/src/gui/widgets/qpushbutton.h - \endcode + The \c generateindex variable contains a boolean value that + specifies whether to generate an index file when HTML + documentation is generated. - When processing the \c headers variable, QDoc behaves in the - same way as it does when processing the \l {headerdirs}{\c - headerdirs} variable. For more information, see the \l - {headerdirs}{\c headerdirs} variable. + By default, an index file is always generated with HTML + documentation, so this variable is typically only used when + disabling this feature (by setting the value to \c false) or when + enabling index generation for the WebXML output (by setting the + value to \c true). - See also \l headerdirs. + \target headerdirs-variable + \section1 headerdirs - \row - \o \bold headers.fileextensions \target headers.fileextensions - \o \bold {The \c headers.fileextensions variable specify the - extension used by the headers.} + The \c headerdirs variable specifies the directories containing + the header files associated with the \c .cpp source files used in + the documentation. - When processing the header files specified in the \l - {headerdirs}{\c headerdirs} variable, QDoc will only read - the files with the fileextensions specified in the \c - headers.fileextensions variable. In this way QDoc avoid - spending time reading irrelevant files. + \code + headerdirs = $QTDIR/src \ + $QTDIR/extensions/activeqt \ + $QTDIR/extensions/motif \ + $QTDIR/tools/designer/src/lib/extension \ + $QTDIR/tools/designer/src/lib/sdk \ + $QTDIR/tools/designer/src/lib/uilib + \endcode - The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp - and *.hxx. + When executed, the first QDoc will do is to read through the + headers specified in the \l {headers} {\c headers} variable, and + the ones located in the directories specified in the \c headerdir + variable (including all subdirectories), building an internal + structure of the classes and their functions. - The extensions are given as standard wildcard expressions. - You can add a file extension to the filter using '+='. For - example: + Then it will read through the sources specified in the \l + {sources-variable} {\c sources}, and the ones located in the + directories specified in the \l {sourcedirs-variable} {\c + sourcedirs} varible (including all subdirectories), merging the + documentation with the structure it retrieved from the header + files. - \code - header.fileextensions += *.H - \endcode + If both the \c headers and \c headerdirs variables are defined, + QDoc will read through both, first \l {headers} {\c headers} then + \c headerdirs. - \warning The above assignment may not work as described. + In the specified directories, QDoc will only read the files with + the fileextensions specified in the \l {headers.fileextensions} + {\c headers.fileextensions} variable. The default extensions are + *.ch, *.h, *.h++, *.hh, *.hpp and *.hxx". The files specified by + \l {headers} {\c headers} will be read independent of their + fileextensions. - See also \l headerdirs. + See also \l headers and \l headers.fileextensions. - \row - \o \bold imagedirs \target imagedirs - \o \bold {The \c imagedirs variable specifies the directories - containing the images used in the documentation.} + \target headers-variable + \section1 headers - The \l {images}{\c images} and \c imagedirs variables are - used by the \l {image}{\\image} and \l - {inlineimage}{\\inlineimage} commands. If both the \l - {images}{\c images} and \c imagedirs variables are defined, - QDoc will search in both, first in \l {images}{\c images} - then in \c imagedirs. + The \c headers variable allows you to specify individual header + files in addition to those located in the directories specified by + the \l {headerdirs} {\c headerdirs} variable. - QDoc will search through the directories in the specified - order, and accept the first matching file it finds. It will - only search in the specified directories, \i not in - subdirectories. + \code + headers = $QTDIR/src/gui/widgets/qlineedit.h \ + $QTDIR/src/gui/widgets/qpushbutton.h + \endcode - For example: + When processing the \c headers variable, QDoc behaves in the same + way as it does when processing the \l {headerdirs} {\c headerdirs} + variable. For more information, see the \l {headerdirs} {\c + headerdirs} variable. - \code - imagedirs = $QTDIR/doc/src/images \ - $QTDIR/examples + See also \l headerdirs. - images = $QTDIR/doc/src/images/calculator-example.png - \endcode + \target headers.fileextensions-variable + \section1 headers.fileextensions - When processing + The \c headers.fileextensions variable specify the extension used + by the headers. - \code - \image calculator-example.png - \endcode + When processing the header files specified in the \l {headerdirs} + {\c headerdirs} variable, QDoc will only read the files with the + fileextensions specified in the \c headers.fileextensions + variable. In this way QDoc avoid spending time reading irrelevant + files. - QDoc will then see if there exists a file called - calculator-example.png listed as a value in the \c images - variable. If it doesn't, it will search in the \c imagedirs - variable, and first see if there exists a file called + The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp and + *.hxx. - \code - $QTDIR/doc/src/images/calculator-example.png - \endcode + The extensions are given as standard wildcard expressions. You + can add a file extension to the filter using '+='. For example: - If it doesn't, QDoc will look for a file called + \code + header.fileextensions += *.H + \endcode - \code - $QTDIR/examples/calculator-example.png - \endcode + \warning The above assignment may not work as described. - You can filter the images in an image directory using the - \l {images.fileextensions}{\c images.fileextensions} - variable. The general idea behind the \l - {images.fileextensions}{\c images.fileextensions} variable - is to enable different image format for different output - format. + See also \l headerdirs. - \warning The \l {images.fileextensions}{\c - images.fileextensions} variable's functionality is - preliminay since QDoc at this point only support HTML. + \target imagedirs-variable + \section1 imagedirs - See also \l images and \l images.fileextensions. + The \c imagedirs variable specifies the directories containing the + images used in the documentation. - \row - \o \bold images \target images - \o \bold {The \c images variable allows you to specify individual - image files in addition to those located in the directories - specified by the \l {imagedirs}{\c imagedirs} variable.} + The \l {images} {\c images} and \c imagedirs variables are used by + the \l {image-command} {\\image} and \l {inlineimage-command} + {\\inlineimage} commands. If both the \l {images} {\c images} and + \c imagedirs variables are defined, QDoc will search in both, + first in \l {images} {\c images} then in \c imagedirs. - For example: + QDoc will search through the directories in the specified order, + and accept the first matching file it finds. It will only search + in the specified directories, \e not in subdirectories. - \code - images = $QTDIR/doc/src/images/calculator-example.png - \endcode + \code + imagedirs = $QTDIR/doc/src/images \ + $QTDIR/examples - When processing the \c images variable, QDoc behaves in the - same way as it does when processing the \l {imagedirs}{\c - imagedirs} variable. For more information, see the \l - {imagedirs}{\c imagedirs} variable. + images = $QTDIR/doc/src/images/calculator-example.png + \endcode - See also \l imagedirs and \l images.fileextensions. + When processing - \row - \o \bold images.fileextensions \target images.fileextensions - \o \bold {The images.fileextensions variable filters the files within - an image directory.} + \code + \image calculator-example.png + \endcode - The variable's values (the extensions) are given as - standard wildcard expressions. The general syntax is: \tt - {images.fileextensions.\i{format} = *.\i{extension}}. + QDoc will then see if there exists a file called + calculator-example.png listed as a value in the \c images + variable. If it doesn't, it will search in the \c imagedirs + variable, and first see if there exists a file called - The idea is to enable different image format for different - output format. For example: + \code + $QTDIR/doc/src/images/calculator-example.png + \endcode - \code - images.fileextensions.HTML = *.png - images.fileextensions.LOUT = *.eps - \endcode + If it doesn't, QDoc will look for a file called - Then, when processing the \l {image}{\\image} and \l - {inlineimage}{\\inlineimage} commands, QDoc will only - search for files with extensions specified in the output - format's associated image extension variable. + \code + $QTDIR/examples/calculator-example.png + \endcode - \warning This is preliminary functionality since QDoc at - this point only support HTML. + You can filter the images in an image directory using the \l + {images.fileextensions} {\c images.fileextensions} variable. The + general idea behind the \l {images.fileextensions} {\c images.fileextensions} + variable is to enable different image format for different output format. - The default extensions for HTML are *.png, *.jpg, *.jpeg - and *.gif. + \warning The \l {images.fileextensions} {\c images.fileextensions} + variable's functionality is preliminay since QDoc at this point + only support HTML. - You can add a file extension to the filter using '+='. For - example: + See also \l images and \l images.fileextensions. - \code - images.fileextensions.HTML += *.eps - \endcode + \target images-variable + \section1 images - See also \l imagedirs and \l images. + The \c images variable allows you to specify individual image + files in addition to those located in the directories specified by + the \l {imagedirs} {\c imagedirs} variable. - \row - \o \bold language \target language - \o \bold {The \c language variable specifies the language of the - source code that is used in the documentation.} + \code + images = $QTDIR/doc/src/images/calculator-example.png + \endcode - Currently, C++ is the only language that QDoc - understands. It is also the default language, and doesn't - really need to be specified. But for example in \l - qt.qdocconf: + When processing the \c images variable, QDoc behaves in the same + way as it does when processing the \l {imagedirs} {\c imagedirs} + variable. For more information, see the \l {imagedirs} {\c + imagedirs} variable. - \code - language = Cpp - \endcode + See also \l imagedirs and \l images.fileextensions. - identifies the language of the Qt source code as C++. + \target images.fileextensions-variable + \section1 images.fileextensions - \row - \o \bold macro \target macro - \o \bold {The \c macro variable can be used to create your - own QDoc commands.} + The images.fileextensions variable filters the files within an + image directory. - The general syntax is \tt {macro.\i{command} = - "\i{definition}}". The definition can be described using - QDoc syntax. In addition it is possible to provide an HTML - definition by appending .HTML to the variable. + The variable's values (the extensions) are given as standard + wildcard expressions. The general syntax is: \tt + {images.fileextensions.\e{format} = *.\e{extension}}. - For example in \l qt.qdocconf: + The idea is to enable different image format for different output + format. - \code - macro.gui = "\\bold" - macro.raisedaster.HTML = "<sup>*</sup>" - \endcode + \code + images.fileextensions.HTML = *.png + images.fileextensions.LOUT = *.eps + \endcode - makes sure that the \\gui command renders its argument using a - bold font, and that \\raisedaster renders a '*'. + Then, when processing the \l {image-command} {\\image} and \l + {inlineimage-command} {\\inlineimage} commands, QDoc will only + search for files with extensions specified in the output format's + associated image extension variable. - \row - \o \bold naturallanguage \target naturallanguage - \o \bold {The \c naturallanguage variable specifies the natural - language used for the documentation generated by qdoc.} + \warning This is preliminary functionality since QDoc at this + point only support HTML. - For example: + The default extensions for HTML are *.png, *.jpg, *.jpeg and + *.gif. - \code - naturallanguage = zh-Hans - \endcode + You can add a file extension to the filter using '+='. For + example: - By default, the natural language is \c en for compatibility - with legacy documentation. + \code + images.fileextensions.HTML += *.eps + \endcode - qdoc will add the natural language information to the HTML - it generates, using the \c lang and \c xml:lang attributes. + See also \l imagedirs and \l images. - See also \l sourceencoding, \l outputencoding, - \l{http://www.w3.org/TR/xhtml1/#C_7}{C.7. The lang and xml:lang Attributes} and - \l{http://www.w3.org/TR/i18n-html-tech-lang/#ri20040429.113217290}{Best Practice 13: Using Hans and Hant codes}. + \target language-variable + \section1 language - \row - \o \bold outputdir \target outputdir - \o \bold {The \c outputdir variable specifies the directory - where QDoc will put the generated documentation.} + The \c language variable specifies the language of the source code + that is used in the documentation. - In qt.qdocconf: + Currently, C++ is the only language that QDoc understands. It is + also the default language, and doesn't really need to be + specified. But for example in \l qt.qdocconf: - \code - outputdir = $QTDIR/doc/html - \endcode + \code + language = Cpp + \endcode - locates the generated Qt reference documentation in - $QTDIR/doc/html. For example, the documentation of the - QWidget class is located in + identifies the language of the Qt source code as C++. - \code - $QTDIR/doc/html/qwidget.html - \endcode + \target macro-variable + \section1 macro - The associated images will be put in an \c images subdirectory. + The \c macro variable can be used to create your own QDoc + commands. - \warning When running QDoc multiple times using the same output - directory, all files from the previous run will be lost. + The general syntax is \tt {macro.\e{command} = + "\e{definition}}". The definition can be described using QDoc + syntax. In addition it is possible to provide an HTML definition + by appending .HTML to the variable. - \row - \o \bold outputencoding \target outputencoding - \o \bold {The \c outputencoding variable specifies the encoding - used for the documentation generated by qdoc.} + For example in \l qt.qdocconf: - For example: + \code + macro.gui = "\\bold" + macro.raisedaster.HTML = "<sup>*</sup>" + \endcode - \code - outputencoding = UTF-8 - \endcode + makes sure that the \\gui command renders its argument using a + bold font, and that \\raisedaster renders a '*'. - By default, the output encoding is \c ISO-8859-1 (Latin1) for - compatibility with legacy documentation. When generating - documentation for some languages, particularly non-European - languages, this is not sufficient and an encoding such as UTF-8 - is required. + \target naturallanguage-variable + \section1 naturallanguage - qdoc will encode HTML using this encoding and generate the - correct declarations to indicate to browsers which encoding - is being used. The \l naturallanguage configuration variable - should also be specified to provide browsers with a complete - set of character encoding and language information. + The \c naturallanguage variable specifies the natural language + used for the documentation generated by qdoc. - See also \l outputencoding and \l naturallanguage. + \code + naturallanguage = zh-Hans + \endcode - \row - \o \bold outputformats \target outputformats - \o \bold {The \c outputformats variable specifies the format of - the generated documentation.} + By default, the natural language is \c en for compatibility with + legacy documentation. - Currently, QDoc only supports the HTML format. It is also - the default format, and doesn't need to be specified. + qdoc will add the natural language information to the HTML it + generates, using the \c lang and \c xml:lang attributes. - \row - \o \bold outputprefixes \target outputprefixes - \o \bold {The \c outputprefixes variable specifies a mapping between - types of files and the prefixes to prepend to the HTML file names - in the generated documentation.} + See also \l {sourceencoding-variable} {sourceencoding}, + \l {outputencoding-variable} {outputencoding}, + \l{http://www.w3.org/TR/xhtml1/#C_7} + {C.7. The lang and xml:lang Attributes} and + \l{http://www.w3.org/TR/i18n-html-tech-lang/#ri20040429.113217290} + {Best Practice 13: Using Hans and Hant codes}. - For example: + \target outputdir-variable + \section1 outputdir - \code - outputprefixes = QML - outputprefixes.QML = qt-components- - \endcode + The \c outputdir variable specifies the directory where QDoc will + put the generated documentation. - Be default, files containing the API documentation for QML elements - or components are prefixed with "qml-". In the above example, the - prefix "qt-components-" is used instead. + In qt.qdocconf: - \row - \o \bold qhp \target qhp - \o \bold{The \c qhp variable is used to define the information to be - written out to Qt Help Project (\c{qhp}) files.} + \code + outputdir = $QTDIR/doc/html + \endcode - See the \l{Creating Help Project Files} chapter for information - about this process. + locates the generated Qt reference documentation in + $QTDIR/doc/html. For example, the documentation of the QWidget + class is located in - \row - \o \bold slow (removed) \target slow - \o \bold {The \c slow variable previously specified whether QDoc should - do time-consuming processing, such as syntax highlighting.} + \code + $QTDIR/doc/html/qwidget.html + \endcode - This option has been replaced by the \l{syntaxhighlighing} option. + The associated images will be put in an \c images subdirectory. - For compatibility, the \c -slow command-line option has been - retained. This has the effect of enabling syntax highlighting. + \warning When running QDoc multiple times using the same output + directory, all files from the previous run will be lost. - \row - \o \bold sourcedirs \target sourcedirs - \o \bold {The \c sourcedirs variable specifies the directories - containing the \c .cpp or \c .qdoc files used in - the documentation.} + \target outputencoding-variable + \section1 outputencoding - For example in \l qt.qdocconf + The \c outputencoding variable specifies the encoding used for the + documentation generated by qdoc. - \code - sourcedirs = $QTDIR/src \ - $QTDIR/doc/src \ - $QTDIR/extensions/activeqt \ - $QTDIR/extensions/motif \ - $QTDIR/tools/designer/src/lib/extension \ - $QTDIR/tools/designer/src/lib/sdk \ - $QTDIR/tools/designer/src/lib/uilib - \endcode + \code + outputencoding = UTF-8 + \endcode - When executed, the first QDoc will do is to read through - the headers specified in the \l {header}{\c header} - variable, and the ones located in the directories specified - in the \c headerdir variable (including all - subdirectories), building an internal structure of the - classes and their functions. - - Then it will read through the sources specified in the \l - {sources}{\c sources}, and the ones located in the - directories specified in the \l {sourcedirs}{\c sourcedirs} - varible (including all subdirectories), merging the - documentation with the structure it retrieved from the - header files. - - If both the \c sources and \c sourcedirs variables are - defined, QDoc will read through both, first \l {sources}{\c - sources} then \c sourcedirs. - - In the specified directories, QDoc will only read the files - with the fileextensions specified in the \l - {sources.fileextensions}{\c sources.fileextensions} - variable. The default extensions are *.c++, *.cc, *.cpp and - *.cxx. The files specified by \l {sources}{\c sources} will - be read independent of their fileextensions. - - See also \l sources and \l sources.fileextensions. + By default, the output encoding is \c ISO-8859-1 (Latin1) for + compatibility with legacy documentation. When generating + documentation for some languages, particularly non-European + languages, this is not sufficient and an encoding such as UTF-8 is + required. - \row - \o \bold sourceencoding \target sourceencoding - \o \bold {The \c sourceencoding variable specifies the encoding - used for the source code and documentation.} + qdoc will encode HTML using this encoding and generate the correct + declarations to indicate to browsers which encoding is being + used. The \l naturallanguage configuration variable should also be + specified to provide browsers with a complete set of character + encoding and language information. - For example: + See also \l outputencoding and \l naturallanguage. - \code - sourceencoding = UTF-8 - \endcode + \target outputformats-variable + \section1 outputformats - By default, the source encoding is \c ISO-8859-1 (Latin1) for - compatibility with legacy documentation. For some languages, - particularly non-European languages, this is not sufficient - and an encoding such as UTF-8 is required. + The \c outputformats variable specifies the format of + the generated documentation. - Although qdoc will use the encoding to read source and - documentation files, limitations of C++ compilers may prevent - you from using non-ASCII characters in source code comments. - In cases like these, it is possible to write API documentation - completely in documentation files. + Currently, QDoc only supports the HTML format. It is also + the default format, and doesn't need to be specified. - See also \l naturallanguage and \l outputencoding. + \target outputprefixes + \section1 outputprefixes - \row - \o \bold sources \target sources - \o \bold {The \c sources variable allows you to specify - individual source files in addition to those located in the - directories specified by the \l {sourcedir}{\c sourcedir} - variable.} + The \c outputprefixes variable specifies a mapping between types of files + and the prefixes to prepend to the HTML file names in the generated + documentation. - For example: + \code + outputprefixes = QML + outputprefixes.QML = qt-components- + \endcode - \code - sources = $QTDIR/src/gui/widgets/qlineedit.cpp \ - $QTDIR/src/gui/widgets/qpushbutton.cpp - \endcode + By default, files containing the API documentation for QML elements + or components are prefixed with "qml-". In the above example, the + prefix "qt-components-" is used instead. - When processing the \c sources variable, QDoc behaves in the - same way as it does when processing the \l {sourcedirs}{\c - sourcedirs} variable. For more information, see the \l - {sourcedirs}{\c sourcedirs} variable. + \target qhp-variable + \section1 qhp - See also \l sourcedirs. + The \c qhp variable is used to define the information to be + written out to Qt Help Project (\c{qhp}) files. - \row - \o \bold sources.fileextensions \target sources.fileextensions - \o \bold {The \c sources.fileextensions variable filters the - files within a source directory.} + See the \l{Creating Help Project Files} chapter for information + about this process. - When processing the source files specified in the \l - {sourcedirs}{\c sourcedirs} variable, QDoc will only read - the files with the fileextensions specified in the \c - sources.fileextensions variable. In this way QDoc avoid - spending time reading irrelevant files. - The default extensions are *.c++, *.cc, *.cpp and *.cxx. + \target slow-variable + \section1 slow - The extensions are given as standard wildcard expressions. - You can add a file extension to the filter using '+='. For - example: + The \c slow variable specifies whether QDoc should do + time-consuming processing, such as syntax highlighting. The + default value is false. - \code - sources.fileextensions += *.CC - \endcode + \note This option has been replaced by the \l{syntaxhighlighting} option. - \warning The above assignment may not work as described. + For compatibility, the \c -slow command-line option has been + retained. This has the effect of enabling syntax highlighting. - See also \l sourcedirs and \l sources. + \target sourcedirs-variable + \section1 sourcedirs - \row - \o \bold spurious \target spurious - \o \bold {The \c spurious variable excludes specified - QDoc warnings from the output.} + The \c sourcedirs variable specifies the directories containing + the \c .cpp or \c .qdoc files used in the documentation. - The warnings are specified using standard wildcard - expressions. For example: + For example in \l qt.qdocconf - \code - spurious = "Cannot find .*" \ - "Missing .*" - \endcode + \code + sourcedirs = $QTDIR/src \ + $QTDIR/doc/src \ + $QTDIR/extensions/activeqt \ + $QTDIR/extensions/motif \ + $QTDIR/tools/designer/src/lib/extension \ + $QTDIR/tools/designer/src/lib/sdk \ + $QTDIR/tools/designer/src/lib/uilib + \endcode - makes sure that warnings matching either of these - expressions, will not be part of the output when running - QDoc. For example would the following warning be omitted - from the output: + When executed, the first QDoc will do is to read through the + headers specified in the \l {header-command} {\c header} variable, + and the ones located in the directories specified in the \c + headerdir variable (including all subdirectories), building an + internal structure of the classes and their functions. - \code - qt-4.0/src/opengl/qgl_mac.cpp:156: Missing parameter name - \endcode + Then it will read through the sources specified in the \l + {sources} {\c sources}, and the ones located in the directories + specified in the \l {sourcedirs} {\c sourcedirs} varible + (including all subdirectories), merging the documentation with the + structure it retrieved from the header files. - \row - \o \bold syntaxhighlighting \target syntaxhighlighting - \o \bold{The \c syntaxhighlighting variable specifies whether QDoc - should perform syntax highlighting on source code quoted in the - documentation it output.} + If both the \c sources and \c sourcedirs variables are defined, + QDoc will read through both, first \l {sources} {\c sources} then + \c sourcedirs. - For example: + In the specified directories, QDoc will only read the files with + the fileextensions specified in the \l {sources.fileextensions} + {\c sources.fileextensions} variable. The default extensions are + *.c++, *.cc, *.cpp and *.cxx. The files specified by \l {sources} + {\c sources} will be read independent of their fileextensions. - \code - syntaxhighlighting = true - \endcode + See also \l {sources-variable} {sources} and + \l {sources.fileextensions-variable} {sources.fileextensions}. - will enable syntax highlighting for all supported programming - languages. + \target sourceencoding-variable + \section1 sourceencoding - \row - \o \bold tabsize \target tabsize - \o \bold {The \c tabsize variable defines the size of a tab - character.} + The \c sourceencoding variable specifies the encoding used for the + source code and documentation. - For example: + \code + sourceencoding = UTF-8 + \endcode - \code - tabsize = 4 - \endcode + By default, the source encoding is \c ISO-8859-1 (Latin1) for + compatibility with legacy documentation. For some languages, + particularly non-European languages, this is not sufficient and an + encoding such as UTF-8 is required. - will give the tab character the size of 4 spaces. + Although qdoc will use the encoding to read source and + documentation files, limitations of C++ compilers may prevent you + from using non-ASCII characters in source code comments. In cases + like these, it is possible to write API documentation completely + in documentation files. - The default value of the variable is 8, and doesn't need to - be specified. + See also \l {naturallanguage-variable} {naturallanguage} and + \l {outputencoding-variable} {outputencoding}. - \row - \o \bold tagfile \target tagfile - \o \bold{The \c tagfile variable specifies the Doxygen tag file to be written - when HTML is generated.} - \row - \o \bold version \target version - \o \bold {The \c version variable specifies the version number of the - documented software.} + \target sources-variable + \section1 sources - For example: + The \c sources variable allows you to specify individual source + files in addition to those located in the directories specified by + the \l {sourcedirs-variable} {sourcedirs} variable. - \code - version = 4.0.1 - \endcode + \code + sources = $QTDIR/src/gui/widgets/qlineedit.cpp \ + $QTDIR/src/gui/widgets/qpushbutton.cpp + \endcode - When a version number is specified (using the \tt{\l - version} or \tt {\l versionsym} variables in a \c .qdocconf - file), it is accessible through the corresponding \\version - command for use in the documentation. + When processing the \c sources variable, QDoc behaves in the same + way as it does when processing the \l {sourcedirs-variable} + {sourcedirs} variable. For more information, see the \l + {sourcedirs-variable} {sourcedirs} variable. - \warning The \\version command's functionality is not - fully implemented; currently it only works within raw HTML - code. + See also \l {sourcedirs-variable} {sourcedirs}. - See also \l versionsym. + \target sources.fileextensions-variable + \section1 sources.fileextensions - \row - \o \bold versionsym \target versionsym - \o \bold {The \c versionsym variable specifies a C++ - preprocessor symbol that defines the version number - of the documented software.} + The \c sources.fileextensions variable filters the files within a + source directory. - For example in \l qt.qdocconf: + When processing the source files specified in the \l {sourcedirs} + {\c sourcedirs} variable, QDoc will only read the files with the + fileextensions specified in the \c sources.fileextensions + variable. In this way QDoc avoid spending time reading irrelevant + files. - \code - versionsym = QT_VERSION_STR - \endcode + The default extensions are *.c++, *.cc, *.cpp and *.cxx. - QT_VERSION_STR is defined in qglobal.h as follows + The extensions are given as standard wildcard expressions. You + can add a file extension to the filter using '+='. For example: - \code - #define QT_VERSION_STR "4.0.1" - \endcode + \code + sources.fileextensions += *.CC + \endcode - When a version number is specified (using the \tt{\l - version} or \tt {\l versionsym} variables in a \c .qdocconf - file), it is accessible through the corresponding \\version - command for use in the documentation. + \warning The above assignment may not work as described. - \warning The \\version command's functionality is not fully - implemented; currently it only works within raw HTML code. + See also \l {sourcedirs-variable} {sourcedirs} and \l + (sources-variable} {sources}. - See also \l {version}{\\version}. - \endtable + \target spurious-variable + \section1 spurious + + The \c spurious variable excludes specified QDoc warnings from the + output. The warnings are specified using standard wildcard + expressions. + + \code + spurious = "Cannot find .*" \ + "Missing .*" + \endcode + + makes sure that warnings matching either of these expressions, + will not be part of the output when running QDoc. For example + would the following warning be omitted from the output: + + \code + qt-4.0/src/opengl/qgl_mac.cpp:156: Missing parameter name + \endcode + + \target syntaxhighlighting + \section1 syntaxhighlighting + + The \c syntaxhighlighting variable specifies whether QDoc should + perform syntax highlighting on source code quoted in the + documentation it generates. + + \code + syntaxhighlighting = true + \endcode + + will enable syntax highlighting for all supported programming + languages. + + \target tabsize-variable + \section1 tabsize + + The \c tabsize variable defines the size of a tab character. + + \code + tabsize = 4 + \endcode + + will give the tab character the size of 4 spaces. The default + value of the variable is 8, and doesn't need to be specified. + + \target tagfile-variable + \section1 tagfile + + The \c tagfile variable specifies the Doxygen tag file to be + written when HTML is generated. + + \target version-variable + \section1 version + + The \c version variable specifies the version number of the + documented software. + + \code + version = 4.0.1 + \endcode + + When a version number is specified (using the \tt{\l version} or + \tt {\l versionsym} variables in a \c .qdocconf file), it is + accessible through the corresponding \\version command for use in + the documentation. + + \warning The \\version command's functionality is not fully + implemented; currently it only works within raw HTML code. + + See also \l versionsym. + + \target versionsym-variable + \section1 versionsym + + The \c versionsym variable specifies a C++ preprocessor symbol + that defines the version number of the documented software. + + For example in \l qt.qdocconf: + + \code + versionsym = QT_VERSION_STR + \endcode + + QT_VERSION_STR is defined in qglobal.h as follows + + \code + #define QT_VERSION_STR "4.0.1" + \endcode + + When a version number is specified (using the \tt{\l version} or + \tt {\l versionsym} variables in a \c .qdocconf file), it is + accessible through the corresponding \\version command for use in + the documentation. + + \warning The \\version command's functionality is not fully + implemented; currently it only works within raw HTML code. + + See also \l {version} {\\version}. */ /*! \page 22-creating-help-project-files.html - \previouspage General Configuration Variables - \contentspage QDoc Manual - Table of Contents + \previouspage Generic Configuration Variables + \contentspage Table of Contents \nextpage C++ Specific Configuration Variables \title Creating Help Project Files @@ -8131,7 +7903,7 @@ /*! \page 23-qdoc-configuration-cppvariables.html \previouspage Creating Help Project Files - \contentspage QDoc Manual - Table of Contents + \contentspage Table of Contents \nextpage HTML Specific Configuration Variables \title C++ Specific Configuration Variables @@ -8139,137 +7911,114 @@ The C++ specific configuration variables are provided to avoid erroneous documentation due to non-standard C++ constructs. - \section1 Alphabetical List - - \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoredirectives} - {Cpp.ignoredirectives}, - \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoretoken} - {Cpp.ignoretokens} - - \section1 Variable Descriptions + \target Cpp.ignoredirectives-variable + \section1 Cpp.ignoredirectives - \table - - \header - \o Variable - \o Description + The \c Cpp.ignoredirectives variable makes QDoc ignore the + specified non-standard constructs, within C++ source code. - \row - \o \bold Cpp.ignoredirectives \target Cpp.ignoredirectives - \o \bold {The \c Cpp.ignoredirectives variable makes QDoc ignore - the specified non-standard constructs, within C++ source code.} + If not specified by the \tt {\l Cpp.ignoretokens} or \tt {\l + Cpp.ignoredirectives} variables, non-standard constructs + (typically macros) can result in erroneous documentation. - If not specified by the \tt {\l Cpp.ignoretokens} or \tt - {\l Cpp.ignoredirectives} variables, non-standard - constructs (typically macros) can result in erroneous - documentation. + In \l qt.qdocconf: - In \l qt.qdocconf: + \code + Cpp.ignoredirectives = Q_DECLARE_INTERFACE \ + Q_DECLARE_OPERATORS_FOR_FLAGS \ + Q_DECLARE_PRIVATE \ + Q_DECLARE_PUBLIC \ + Q_DISABLE_COPY \ + Q_DUMMY_COMPARISON_OPERATOR \ + Q_ENUMS \ + Q_FLAGS \ + Q_INTERFACES \ + __attribute__ + \endcode - \code - Cpp.ignoredirectives = Q_DECLARE_INTERFACE \ - Q_DECLARE_OPERATORS_FOR_FLAGS \ - Q_DECLARE_PRIVATE \ - Q_DECLARE_PUBLIC \ - Q_DISABLE_COPY \ - Q_DUMMY_COMPARISON_OPERATOR \ - Q_ENUMS \ - Q_FLAGS \ - Q_INTERFACES \ - __attribute__ - \endcode + makes sure that when processing the code below, for example, QDoc + will simply ignore the 'Q_ENUMS' and 'Q_FLAGS' expressions: - makes sure that when processing the code below, for - example, QDoc will simply ignore the 'Q_ENUMS' and - 'Q_FLAGS' expressions: + \code + class Q_CORE_EXPORT Qt { + Q_OBJECT + Q_ENUMS(Orientation TextFormat BackgroundMode + DateFormat ScrollBarPolicy FocusPolicy + ContextMenuPolicy CaseSensitivity + LayoutDirection ArrowType) + Q_ENUMS(ToolButtonStyle) + Q_FLAGS(Alignment) + Q_FLAGS(Orientations) + Q_FLAGS(DockWidgetAreas) + + public: + ... + }; + \endcode - \code - class Q_CORE_EXPORT Qt { - Q_OBJECT - Q_ENUMS(Orientation TextFormat BackgroundMode - DateFormat ScrollBarPolicy FocusPolicy - ContextMenuPolicy CaseSensitivity - LayoutDirection ArrowType) - Q_ENUMS(ToolButtonStyle) - Q_FLAGS(Alignment) - Q_FLAGS(Orientations) - Q_FLAGS(DockWidgetAreas) - - public: - ... - }; - \endcode + The Q_OBJECT macro, however, is an exception: QDoc recognizes this + particular non-standard construct, so there is no need specifying + it using the \tt {\l Cpp.ignoredirectives} variable. - The Q_OBJECT macro, however, is an exception: QDoc - recognizes this particular non-standard construct, so there - is no need specifying it using the \tt {\l - Cpp.ignoredirectives} variable. + Regarding the Q_CORE_EXPORT macro; see the documentation of the + \tt {\l Cpp.ignoretokens} variable. - Regarding the Q_CORE_EXPORT macro; see the documentation of - the \tt {\l Cpp.ignoretokens} variable. + See also \l Cpp.ignoretokens. - See also \l Cpp.ignoretokens. + \target Cpp.ignoretokens-variable + \section1 Cpp.ignoretokens - \row - \o \bold Cpp.ignoretokens \target Cpp.ignoretokens - \o \bold {The \c Cpp.ignoretokens variable makes QDoc ignore - the specified non-standard constructs, within C++ source code.} + The \c Cpp.ignoretokens variable makes QDoc ignore the specified + non-standard constructs, within C++ source code. - If not specified by the \tt {\l Cpp.ignoretokens} or \tt - {\l Cpp.ignoredirectives} variables, non-standard - constructs (typically macros) can result in erroneous - documentation. + If not specified by the \tt {\l Cpp.ignoretokens} or \tt {\l + Cpp.ignoredirectives} variables, non-standard constructs + (typically macros) can result in erroneous documentation. - In \l qt.qdocconf: + In \l qt.qdocconf: - \code - Cpp.ignoretokens = QAXFACTORY_EXPORT \ - QM_EXPORT_CANVAS \ - ... - Q_COMPAT_EXPORT \ - Q_CORE_EXPORT \ - Q_EXPLICIT \ - Q_EXPORT \ - ... - Q_TYPENAME \ - Q_XML_EXPORT - \endcode - - makes sure that when processing the code below, for - example, QDoc will simply ignore the 'Q_CORE_EXPORT' - expression: + \code + Cpp.ignoretokens = QAXFACTORY_EXPORT \ + QM_EXPORT_CANVAS \ + ... + Q_COMPAT_EXPORT \ + Q_CORE_EXPORT \ + Q_EXPLICIT \ + Q_EXPORT \ + ... + Q_TYPENAME \ + Q_XML_EXPORT + \endcode - \code - class Q_CORE_EXPORT Qt { - Q_OBJECT - Q_ENUMS(Orientation TextFormat BackgroundMode - DateFormat ScrollBarPolicy FocusPolicy - ContextMenuPolicy CaseSensitivity - LayoutDirection ArrowType) - Q_ENUMS(ToolButtonStyle) - Q_FLAGS(Alignment) - Q_FLAGS(Orientations) - Q_FLAGS(DockWidgetAreas) - - public: - ... - }; - \endcode + makes sure that when processing the code below, for example, QDoc + will simply ignore the 'Q_CORE_EXPORT' expression: - Regarding the Q_OBJECT, Q_ENUMS and Q_FLAGS macros; see the - documentation of the \tt {\l Cpp.ignoredirectives} - variable. + \code + class Q_CORE_EXPORT Qt { + Q_OBJECT + Q_ENUMS(Orientation TextFormat BackgroundMode + DateFormat ScrollBarPolicy FocusPolicy + ContextMenuPolicy CaseSensitivity + LayoutDirection ArrowType) + Q_ENUMS(ToolButtonStyle) + Q_FLAGS(Alignment) + Q_FLAGS(Orientations) + Q_FLAGS(DockWidgetAreas) + public: + ... + }; + \endcode - See also \l Cpp.ignoredirectives. + Regarding the Q_OBJECT, Q_ENUMS and Q_FLAGS macros; see the + documentation of the \tt {\l Cpp.ignoredirectives} variable. - \endtable + See also \l Cpp.ignoredirectives. */ - /*! \page 24-qdoc-configuration-htmlvariables.html \previouspage C++ Specific Configuration Variables - \contentspage QDoc Manual - Table of Contents + \contentspage Table of Contents \nextpage Supporting Derived Projects \title HTML Specific Configuration Variables @@ -8279,219 +8028,188 @@ documentation's footer or postheader. The format of the variable values are raw HTML. - \section1 Alphabetical List - - \l {24-qdoc-configuration-htmlvariables.html#HTML.footer}{HTML.footer}, - \l {24-qdoc-configuration-htmlvariables.html#HTML.postheader} - {HTML.postheader}, - \l {24-qdoc-configuration-htmlvariables.html#HTML.style}{HTML.style}, - \l {24-qdoc-configuration-htmlvariables.html#HTML.stylesheets}{HTML.stylesheets} + \target HTML.footer-variable + \section1 HTML.footer + The \c HTML.footer variable defines the content of the generated + HTML documentation's footer. - \section1 Variable Descriptions + The footer is rendered at the bottom of the generated + documentation page. - \table + The variable's value is given as raw HTML code enclosed by + quotation marks. Note that if the value spans several lines, each + line needs to be enclosed by quotation marks. - \header - \o Variable - \o Description + For example in \l qt.qdocconf: - \row - \o \bold HTML.footer \target HTML.footer - \o \bold {The \c HTML.footer variable defines the content - of the generated HTML documentation's footer.} + \code + HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \ + ... + "</tr></table></div></address>" + \endcode - The footer is rendered at the bottom of the generated - documentation page. + The complete variable entry in \l qt.qdocconf provides the + standard footer of the \l {http://qt.nokia.com/doc/4.0/index.html} + {Qt Reference Documentation}. - The variable's value is given as raw HTML code enclosed by - quotation marks. Note that if the value spans several - lines, each line needs to be enclosed by quotation marks. + \target HTML.postheader-variable + \section1 HTML.postheader - For example in \l qt.qdocconf: + The \c HTML.postheader variable defines the content of the + generated HTML documentation's postheader. - \code - HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \ - ... - "</tr></table></div></address>" - \endcode + The header is rendered at the top of the generated documentation + page. - The complete variable entry in \l qt.qdocconf provides the - standard footer of the \l - {http://qt.nokia.com/doc/4.0/index.html}{Qt Reference - Documentation}. + The variable's value is given as raw HTML enclosed by quotation + marks. Note that if the value spans several lines, each line needs + to be enclosed by quotation marks. - \row - \o \bold HTML.postheader \target HTML.postheader - \o \bold {The \c HTML.postheader variable defines the content - of the generated HTML documentation's postheader.} + For example in \l qt.qdocconf: - The header is rendered at the top of the generated - documentation page. + \code + HTML.postheader = "<table border=\"0\"..." \ + ... + "<img src=\"images/trolltech-logo.png\" \ + "align=\"right\" width=\"203\" height=\"32\""\ + "border=\"0\" />" \ + "</td></tr>" \ + "</table>" + \endcode - The variable's value is given as raw HTML enclosed by - quotation marks. Note that if the value spans several - lines, each line needs to be enclosed by quotation marks. + The complete variable entry in \l qt.qdocconf provides the + standard header of the \l {http://qt.nokia.com/doc/4.0/index.html} + {Qt Reference Documentation}. - For example in \l qt.qdocconf: + \target HTML.style-variable + \section1 HTML.style - \code - HTML.postheader = "<table border=\"0\"..." \ - ... - "<img src=\"images/trolltech-logo.png\" \ - "align=\"right\" width=\"203\" height=\"32\""\ - "border=\"0\" />" \ - "</td></tr>" \ - "</table>" - \endcode + The HTML.style variable defines the style for + the generated HTML documentation. - The complete variable entry in \l qt.qdocconf provides the - standard header of the \l - {http://qt.nokia.com/doc/4.0/index.html}{Qt Reference - Documentation}. + The variable's value is given as raw HTML enclosed by quotation + marks. Note that if the value spans several lines, each line needs + to be enclosed by quotation marks. - \row - \o \bold HTML.style \target HTML.style - \o \bold {The HTML.style variable defines the style for - the generated HTML documentation.} + For example in \l qt.qdocconf: - The variable's value is given as raw HTML enclosed by - quotation marks. Note that if the value spans several - lines, each line needs to be enclosed by quotation marks. + \code + HTML.style = "h3.fn,span.fn" \ + "{ margin-left: 1cm; text-indent: -1cm; }\n" \ + "a:link { color: #004faf; text-decoration: none }\n" \ + "a:visited" \ + "{ color: #672967; text-decoration: none }\n" \ + "td.postheader { font-family: sans-serif }\n" \ + "tr.address { font-family: sans-serif }\n" \ + "body { background: #ffffff; color: black; }" + \endcode - For example in \l qt.qdocconf: + provides the HTML style for the \l + {http://qt.nokia.com/doc/4.0/index.html} {Qt Reference + Documentation}. - \code - HTML.style = "h3.fn,span.fn" \ - "{ margin-left: 1cm; text-indent: -1cm; }\n" \ - "a:link { color: #004faf; text-decoration: none }\n" \ - "a:visited" \ - "{ color: #672967; text-decoration: none }\n" \ - "td.postheader { font-family: sans-serif }\n" \ - "tr.address { font-family: sans-serif }\n" \ - "body { background: #ffffff; color: black; }" - \endcode + \target HTML.stylesheets-variable + \section1 HTML.stylesheets - provides the HTML style for the \l - {http://qt.nokia.com/doc/4.0/index.html}{Qt Reference - Documentation}. + The HTML.stylesheets variable defines a list of stylesheets + to use for the generated HTML documentation. - \row - \o \bold HTML.stylesheets \target HTML.stylesheets - \o \bold {The HTML.stylesheets variable defines a list of stylesheets - to use for the generated HTML documentation.} + Using separate stylesheets for the documentation makes it easier + to customize and experiment with the style used once the contents + has been generated. Typically, it is only necessary to define a + single stylesheet for any set of documentation; for example: - Using separate stylesheets for the documentation makes it easier to - customize and experiment with the style used once the contents has - been generated. Typically, it is only necessary to define a single - stylesheet for any set of documentation; for example: + \code + HTML.stylesheets = classic.css + \endcode - \code - HTML.stylesheets = classic.css - \endcode + QDoc expects to find stylesheets in the directory containing the + \l qt.qdocconf file, and it will copy those specified to the output + directory alongside the HTML pages. - QDoc expects to find stylesheets in the directory containing the - \l qt.qdocconf file, and it will copy those specified to the output - directory alongside the HTML pages. - \endtable */ /*! \page 25-qdoc-configuration-derivedprojects.html \previouspage HTML Specific Configuration Variables - \contentspage QDoc Manual - Table of Contents - \nextpage QDoc Compatibility + \contentspage Table of Contents + \nextpage Compatibility Issues \title Supporting Derived Projects - \tableofcontents + Some configuration variables allow you to use QDoc to support + Qt-based projects; i.e allow your project to contain links to the + online Qt documentation. This means that QDoc will be able to + create links to the class reference documentation, without any + explicit linking command. - Some particular configuration variables allow you to use QDoc to - support Qt-based projects; i.e to make projects, such as Qt Solutions, - contain references to the online Qt documentation. This - means that QDoc will be able to create links to the class reference - documentation, without any explicit linking command. + \target description-variable + \section1 description - \section1 The Configuration Variables + The description variable holds a short description of the + associated project. - \section2 Alphabetical List + See also \l project. - \l{25-qdoc-configuration-derivedprojects.html#description}{description}, - \l{25-qdoc-configuration-derivedprojects.html#indexes}{indexes}, - \l{25-qdoc-configuration-derivedprojects.html#project}{project}, - \l{25-qdoc-configuration-derivedprojects.html#url}{url} + \target indexes-variable + \section1 indexes - \section2 Variable Descriptions + The \c indexes variable lists the index files that will be used to + generate references. - \table - \header - \o Variable - \o Description - \row - \o \bold description \target description - \o \bold {The description variable holds a short description of - the associated project.} + For example. to make a derived Qt project contain links to the Qt + Reference documentation, you need to specify the associated index + file: - See also \l project. - - \row - \o \bold indexes \target indexes - \o \bold {The \c indexes variable lists the index files - that will be used to generate references.} - - For example. to make a derived Qt project contain links to - the Qt Reference documentation, you need to specify the - associated index file: + \code + indexes = $QTDIR/doc/html/qt.index + \endcode - \code - indexes = $QTDIR/doc/html/qt.index - \endcode + See also \l project and \l url. - See also \l project and \l url. + \target project-variable + \section1 project - \row - \o \bold project \target project - \o \bold {The \c project variable provides a name for the project - associated with the \c .qdocconf file.} + The \c project variable provides a name for the project associated + with the \c .qdocconf file. - The project's name is used to form a file name for the - associated project's \i index file. For example: + The project's name is used to form a file name for the associated + project's \e index file. - \code - project = QtMotif - \endcode + \code + project = QtMotif + \endcode - This will cause an index file called \c qtmotif.index to be - created. + This will cause an index file called \c qtmotif.index to be + created. - See also \l description and \l indexes. - \row - \o \bold url \target url - \o \bold {The \c url variable holds the base URL for the - reference documentation associated with the current project.} + See also \l description and \l indexes. - The URL is stored in the generated index file for the - project. When we use the index on its own, QDoc will use - this as the base URL when constructing links to classes, - functions, and other things listed in the index. + \target url-variable + \section1 url - For example: + The \c url variable holds the base URL for the reference + documentation associated with the current project. - \code - project = Qt - description = Qt Reference Documentation - url = http://qt.nokia.com/doc/4.0 + The URL is stored in the generated index file for the + project. When we use the index on its own, QDoc will use this as + the base URL when constructing links to classes, functions, and + other things listed in the index. - ... - \endcode + \code + project = Qt + description = Qt Reference Documentation + url = http://qt.nokia.com/doc/4.0 - This makes sure that whenever \c qt.index is used to generate - references to for example Qt classes, the base URL is - \c http://qt.nokia.com/doc/4.0. + ... + \endcode - See also \l indexes. + This makes sure that whenever \c qt.index is used to generate + references to for example Qt classes, the base URL is \c + http://qt.nokia.com/doc/4.0. - \endtable + See also \l indexes. \target howto \section1 How to Support Derived Projects @@ -8544,7 +8262,7 @@ The code above requires that you run QDoc from the directory that contains this file. You need to include the compat.qdocconf file for compatibility reasons; this is further explained in the - \l {QDoc Compatibility} section. + \l {Compatibility Issues} section. \bold {To resolve the actual links to Qt classes, the mini-project's \c .qdocconf file needs to assign a value to the \l @@ -8561,47 +8279,43 @@ /*! \page 26-qdoc-commands-compatibility.html \previouspage Supporting Derived Projects - \contentspage QDoc Manual - Table of Contents - \nextpage QDoc Commands - Alphabetical List + \contentspage Table of Contents + \nextpage qt.qdocconf - \title QDoc Compatibility - - \tableofcontents + \title Compatibility Issues \section1 General Description \target reason - QDoc is a tool that constantly evolves to suit our needs, for that - reason there are some compatibility issues in the transition - between old and new practices. + Because QDoc evolves to suit our documentation needs, there can be + some compatibility issues when converting to a new version. - To make the transition as smooth and rapid as possible, the - general idea is to adopt the new commands and usage in new - documentation. While waiting for the occurrences of the old - practices to be eliminated from the old parts of the - documentation, you can map the new commands and usage to the old - ones using a compat.qdocconf file. + To allow you to proceed at your own speed when converting your + qdoc comments to use new qdoc commands and formats, the ability to + include a configuration file called \c {compat.qdocconf} is + provided. - A compat.qdocconf file is a separate \c .qdocconf file which you - can include in your main configuration file. It typically contains - the mapping between old and new commands using the \l alias and \l - {22-qdoc-configuration-generalvariables.html#macro}{macro} - configuration variables. + A \c {compat.qdocconf} file is a separate configuration file, + which you include in your main configuration file. It typically + contains the mappings from old qdoc commands to new ones using + \l {alias} and + \l {22-qdoc-configuration-generalvariables.html#macro-variable} + {macro} configuration variables. \section1 Qt Compatibility In Qt's documentation there still exist occurrences of old - commands, and the Qt \l {qt.qdocconf}{configuration file} needs to + commands, and the Qt \l {qt.qdocconf} {configuration file} needs to include the compat.qdocconf file tailored for Qt. For more detailed information about the commands creating compatibility - issues, see the \l {Command Comments}{command comments}. + issues, see the \l {Command Comments} {command comments}. - \section2 Qt's current compat.qdocconf file + \section1 Qt's current compat.qdocconf file \quotefile files/compat.qdocconf - \section2 Command Comments + \section1 Command Comments \table \header @@ -8619,7 +8333,7 @@ \\e command name. \bold {We still need to use the \\e command to render in - italic in new documentation for \l {reason}{compatibility + italic in new documentation for \l {reason} {compatibility reasons}}. \row @@ -8633,7 +8347,7 @@ \bold {We still need to use the \\input command to include plain text in new documentation for \l - {reason}{compatibility reasons}}. + {reason} {compatibility reasons}}. \row \o \\quotefile \target quotefile-versus-include @@ -8646,7 +8360,7 @@ \bold {We still need to use the \\include command to quote the entire contents of a source file in new documentation - for \l {reason}{compatibility reasons}}. + for \l {reason} {compatibility reasons}}. \row \o \\quotefromfile \target quotefromfile-versus-quotefile @@ -8656,7 +8370,7 @@ that command to quote an entire file, we introduce the new \\quotefromfile command to quote from file. - \bold {Use \l {quotefromfile}{\\quotefromfile} to quote + \bold {Use \l {quotefromfile-command} {\\quotefromfile} to quote parts from a source file in new documentation}. \row @@ -8667,7 +8381,7 @@ in italic instead, we introduce the new \\o command for this purpose. - \bold {Use \l {o}{\\o} to indicate list and table items in + \bold {Use \l {o-command} {\\o} to indicate list and table items in new documentation}. \row @@ -8676,7 +8390,7 @@ \o These commands are equivalent, and represent a simple name change. - \bold {Use \l {quotation}{\\quotation} in new + \bold {Use \l {quotation} {\\quotation} in new documentation}. \row @@ -8685,116 +8399,129 @@ \o These commands are equivalent, and represent a simple name change. - \bold {Use \l {image}{\\image} in new documentation}. + \bold {Use \l {image-command} {\\image} in new documentation}. \endtable */ /*! \page 27-qdoc-commmands-alphabetical.html - \previouspage QDoc Compatibility - \contentspage QDoc Manual - Table of Contents + \previouspage Introduction to QDoc + \contentspage Table of Contents + \nextpage Topic Commands + + \title Command Index - \title QDoc Commands - Alphabetical List + This is a complete, alphabetized list of the QDoc commands. \list - \o \l {04-qdoc-commands-textformatting.html#a}{\\a} - \o \l {11-qdoc-commands-documentcontents.html#abstract}{\\abstract} - \o \l {06-qdoc-commands-verbatimcode.html#badcode}{\\badcode} - \o \l {04-qdoc-commands-textformatting.html#bold}{\\bold} - \o \l {11-qdoc-commands-documentcontents.html#brief}{\\brief} - \o \l {04-qdoc-commands-textformatting.html#c}{\\c} - \o \l {09-qdoc-commands-graphic.html#caption}{\\caption} - \o \l {05-qdoc-commands-documentstructuring.html#chapter}{\\chapter} - \o \l {13-qdoc-commands-topical.html#class}{\\class} - \o \l {06-qdoc-commands-verbatimcode.html#code}{\\code} - \o \l {07-0-qdoc-commands-quoting.html#codeline}{\\codeline}, - \o \l {16-qdoc-commands-status.html#compat}{\\compat} - \o \l {15-qdoc-commands-navigation.html#contentspage}{\\contentspage} - \o \l {07-0-qdoc-commands-quoting.html#dots}{\\dots} - \o \l {12-0-qdoc-commands-miscellaneous.html#else}{\\else} - \o \l {12-0-qdoc-commands-miscellaneous.html#endif}{\\endif} - \o \l {13-qdoc-commands-topical.html#enum}{\\enum} - \o \l {13-qdoc-commands-topical.html#example-command}{\\example} - \o \l {12-0-qdoc-commands-miscellaneous.html#expire}{\\expire} - \o \l {13-qdoc-commands-topical.html#externalpage}{\\externalpage} - \o \l {13-qdoc-commands-topical.html#fn}{\\fn} - \o \l {11-qdoc-commands-documentcontents.html#footnote}{\\footnote} - \o \l {12-0-qdoc-commands-miscellaneous.html#generatelist}{\\generatelist} - \o \l {13-qdoc-commands-topical.html#group}{\\group} - \o \l {10-qdoc-commands-container.html#header}{\\header} - \o \l {13-qdoc-commands-topical.html#headerfile}{\\headerfile} - \o \l {04-qdoc-commands-textformatting.html#i}{\\i} - \o \l {12-0-qdoc-commands-miscellaneous.html#if}{\\if} - \o \l {09-qdoc-commands-graphic.html#image}{\\image} - \o \l {12-0-qdoc-commands-miscellaneous.html#include}{\\include} - \o \l {15-qdoc-commands-navigation.html#indexpage}{\\indexpage} - \o \l {19-qdoc-commands-grouping.html#ingroup}{\\ingroup} - \o \l {19-qdoc-commands-grouping.html#inmodule}{\\inmodule} - \o \l {09-qdoc-commands-graphic.html#inlineimage}{\\inlineimage} - \o \l {16-qdoc-commands-status.html#internal}{\\internal} - \o \l {08-qdoc-commands-linking.html#keyword}{\\keyword} - \o \l {08-qdoc-commands-linking.html#l}{\\l} - \o \l {11-qdoc-commands-documentcontents.html#legalese}{\\legalese} - \o \l {10-qdoc-commands-container.html#list}{\\list} - \o \l {13-qdoc-commands-topical.html#macro}{\\macro} - \o \l {19-qdoc-commands-grouping.html#mainclass}{\\mainclass} - \o \l {12-0-qdoc-commands-miscellaneous.html#meta}{\\meta} - \o \l {13-qdoc-commands-topical.html#module}{\\module} - \o \l {13-qdoc-commands-topical.html#namespace}{\\namespace} - \o \l {15-qdoc-commands-navigation.html#nextpage}{\\nextpage} - \o \l {06-qdoc-commands-verbatimcode.html#newcode}{\\newcode} - \o \l {17-qdoc-commands-thread.html#nonreentrant}{\\nonreentrant} - \o \l {10-qdoc-commands-container.html#o}{\\o} - \o \l {16-qdoc-commands-status.html#obsolete}{\\obsolete} - \o \l {06-qdoc-commands-verbatimcode.html#oldcode}{\\oldcode} - \o \l {12-0-qdoc-commands-miscellaneous.html#omit}{\\omit} - \o \l {10-qdoc-commands-container.html#omitvalue}{\\omitvalue} - \o \l {18-qdoc-commands-relating.html#overload}{\\overload} - \o \l {13-qdoc-commands-topical.html#page}{\\page} - \o \l {05-qdoc-commands-documentstructuring.html#part}{\\part} - \o \l {16-qdoc-commands-status.html#preliminary}{\\preliminary} - \o \l {15-qdoc-commands-navigation.html#previouspage}{\\previouspage} - \o \l {07-0-qdoc-commands-quoting.html#printline}{\\printline} - \o \l {07-0-qdoc-commands-quoting.html#printto}{\\printto} - \o \l {07-0-qdoc-commands-quoting.html#printuntil}{\\printuntil} - \o \l {13-qdoc-commands-topical.html#property}{\\property} - \o \l {11-qdoc-commands-documentcontents.html#quotation}{\\quotation} - \o \l {07-0-qdoc-commands-quoting.html#quotefile}{\\quotefile} - \o \l {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile} - \o \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\raw} - \o \l {17-qdoc-commands-thread.html#reentrant}{\\reentrant} - \o \l {18-qdoc-commands-relating.html#reimp}{\\reimp} - \o \l {18-qdoc-commands-relating.html#relates}{\\relates} - \o \l {10-qdoc-commands-container.html#row}{\\row} - \o \l {08-qdoc-commands-linking.html#sa}{\\sa} - \o \l {05-qdoc-commands-documentstructuring.html#sectionOne}{\\section1} - \o \l {05-qdoc-commands-documentstructuring.html#sectionTwo}{\\section2} - \o \l {05-qdoc-commands-documentstructuring.html#sectionThree}{\\section3} - \o \l {05-qdoc-commands-documentstructuring.html#sectionFour}{\\section4} - \o \l {13-qdoc-commands-topical.html#service}{\\service} - \o \l {16-qdoc-commands-status.html#since}{\\since} - \o \l {07-0-qdoc-commands-quoting.html#skipline}{\\skipline} - \o \l {07-0-qdoc-commands-quoting.html#skipto}{\\skipto} - \o \l {07-0-qdoc-commands-quoting.html#skipuntil}{\\skipuntil} - \o \l {07-0-qdoc-commands-quoting.html#snippet}{\\snippet}, - \o \l {15-qdoc-commands-navigation.html#startpage}{\\startpage} - \o \l {04-qdoc-commands-textformatting.html#sub}{\\sub} - \o \l {20-qdoc-commands-title.html#subtitle}{\\subtitle} - \o \l {04-qdoc-commands-textformatting.html#sup}{\\sup} - \o \l {10-qdoc-commands-container.html#table}{\\table} - \o \l {11-qdoc-commands-documentcontents.html#tableofcontents} - {\\tableofcontents} - \o \l {08-qdoc-commands-linking.html#target}{\\target} - \o \l {17-qdoc-commands-thread.html#threadsafe}{\\threadsafe} - \o \l {20-qdoc-commands-title.html#title}{\\title} - \o \l {04-qdoc-commands-textformatting.html#tt}{\\tt} - \o \l {13-qdoc-commands-topical.html#typedef}{\\typedef} - \o \l {04-qdoc-commands-textformatting.html#underline}{\\underline} - \o \l {13-qdoc-commands-topical.html#variable}{\\variable} - \o \l {10-qdoc-commands-container.html#value}{\\value} - \o \l {11-qdoc-commands-documentcontents.html#warning}{\\warning} + \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} + \o \l {04-qdoc-commands-textmarkup.html#bold-command} {\\bold} + \o \l {11-qdoc-commands-specialcontent.html#brief-command} {\\brief} + \o \l {04-qdoc-commands-textmarkup.html#c-command} {\\c} + \o \l {09-qdoc-commands-includingimages.html#caption-command} {\\caption} + \o \l {05-qdoc-commands-documentstructure.html#chapter-command} {\\chapter} + \o \l {13-qdoc-commands-topics.html#class-command} {\\class} + \o \l {06-qdoc-commands-includecodeinline.html#code-command} {\\code} + \o \l {07-0-qdoc-commands-includingexternalcode.html#codeline-command} {\\codeline}, + \o \l {16-qdoc-commands-status.html#compat-command} {\\compat} + \o \l {15-qdoc-commands-navigation.html#contentspage-command} {\\contentspage} + \o \l {16-qdoc-commands-status.html#default-command} {\\default} \span {class="newStuff"} {(new)} + \o \l {04-qdoc-commands-textmarkup.html#div-command} {\\div} \span {class="newStuff"} {(new)} + \o \l {07-0-qdoc-commands-includingexternalcode.html#dots-command} {\\dots} + \o \l {12-0-qdoc-commands-miscellaneous.html#else-command} {\\else} + \o \l {12-0-qdoc-commands-miscellaneous.html#endif-command} {\\endif} + \o \l {13-qdoc-commands-topics.html#enum-command} {\\enum} + \o \l {13-qdoc-commands-topics.html#example-command} {\\example} + \o \l {12-0-qdoc-commands-miscellaneous.html#expire-command} {\\expire} + \o \l {13-qdoc-commands-topics.html#externalpage-command} {\\externalpage} + \o \l {13-qdoc-commands-topics.html#fn-command} {\\fn} + \o \l {11-qdoc-commands-specialcontent.html#footnote-command} {\\footnote} + \o \l {12-0-qdoc-commands-miscellaneous.html#generatelist-command} {\\generatelist} + \o \l {13-qdoc-commands-topics.html#group-command} {\\group} + \o \l {10-qdoc-commands-tablesandlists.html#header-command} {\\header} + \o \l {13-qdoc-commands-topics.html#headerfile-command} {\\headerfile} + \o \l {04-qdoc-commands-textmarkup.html#i-command} {\\i} + \o \l {12-0-qdoc-commands-miscellaneous.html#if-command} {\\if} + \o \l {09-qdoc-commands-includingimages.html#image-command} {\\image} + \o \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\include} + \o \l {15-qdoc-commands-navigation.html#indexpage-command} {\\indexpage} + \o \l {19-qdoc-commands-grouping.html#ingroup-command} {\\ingroup} + \o \l {18-qdoc-commands-relating.html#inherits-command}{\\inherits} \span {class="newStuff"} {(new)} + \o \l {19-qdoc-commands-grouping.html#inmodule-command} {\\inmodule} + \o \l {09-qdoc-commands-includingimages.html#inlineimage-command} {\\inlineimage} + \o \l {16-qdoc-commands-status.html#internal-command} {\\internal} + \o \l {08-qdoc-commands-creatinglinks.html#keyword-command} {\\keyword} + \o \l {08-qdoc-commands-creatinglinks.html#l-command} {\\l} + \o \l {11-qdoc-commands-specialcontent.html#legalese-command} {\\legalese} + \o \l {10-qdoc-commands-tablesandlists.html#list-command} {\\list} + \o \l {13-qdoc-commands-topics.html#macro-command} {\\macro} + \o \l {19-qdoc-commands-grouping.html#mainclass-command} {\\mainclass} + \o \l {12-0-qdoc-commands-miscellaneous.html#meta-command} {\\meta} + \o \l {13-qdoc-commands-topics.html#module-command} {\\module} + \o \l {13-qdoc-commands-topics.html#namespace-command} {\\namespace} + \o \l {15-qdoc-commands-navigation.html#nextpage-command} {\\nextpage} + \o \l {06-qdoc-commands-includecodeinline.html#newcode-command} {\\newcode} + \o \l {17-qdoc-commands-thread.html#nonreentrant-command} {\\nonreentrant} + \o \l {10-qdoc-commands-tablesandlists.html#o-command} {\\o} + \o \l {16-qdoc-commands-status.html#obsolete-command} {\\obsolete} + \o \l {06-qdoc-commands-includecodeinline.html#oldcode-command} {\\oldcode} + \o \l {12-0-qdoc-commands-miscellaneous.html#omit-command} {\\omit} + \o \l {10-qdoc-commands-tablesandlists.html#omitvalue-command} {\\omitvalue} + \o \l {18-qdoc-commands-relating.html#overload-command} {\\overload} + \o \l {13-qdoc-commands-topics.html#page-command} {\\page} + \o \l {05-qdoc-commands-documentstructure.html#part-command} {\\part} + \o \l {16-qdoc-commands-status.html#preliminary-command} {\\preliminary} + \o \l {15-qdoc-commands-navigation.html#previouspage-command} {\\previouspage} + \o \l {07-0-qdoc-commands-includingexternalcode.html#printline-command} {\\printline} + \o \l {07-0-qdoc-commands-includingexternalcode.html#printto-command} {\\printto} + \o \l {07-0-qdoc-commands-includingexternalcode.html#printuntil-command} {\\printuntil} + \o \l {13-qdoc-commands-topics.html#property-command} {\\property} + \o \l {13-qdoc-commands-topics.html#qmlattachedproperty-command} {\\qmlattachedproperty} \span {class="newStuff"} {(new)} + \o \l {13-qdoc-commands-topics.html#qmlattachedsignal-command} {\\qmlattachedsignal} \span {class="newStuff"} {(new)} + \o \l {13-qdoc-commands-topics.html#qmlbasictype-command} {\\qmlbasictype} \span {class="newStuff"} {(new)} + \o \l {13-qdoc-commands-topics.html#qmlclass-command} {\\qmlclass} \span {class="newStuff"} {(new)} + \o \l {13-qdoc-commands-topics.html#qmlmethod-command} {\\qmlmethod} \span {class="newStuff"} {(new)} + \o \l {13-qdoc-commands-topics.html#qmlproperty-command} {\\qmlproperty} \span {class="newStuff"} {(new)} + \o \l {13-qdoc-commands-topics.html#qmlsignal-command} {\\qmlsignal} \span {class="newStuff"} {(new)} + \o \l {11-qdoc-commands-specialcontent.html#quotation-command} {\\quotation} + \o \l {07-0-qdoc-commands-includingexternalcode.html#quotefile-command} {\\quotefile} + \o \l {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} {\\quotefromfile} + \o \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\raw} \span {class="newStuff"} {(avoid)} + \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 {10-qdoc-commands-tablesandlists.html#row-command} {\\row} + \o \l {08-qdoc-commands-creatinglinks.html#sa-command} {\\sa} + \o \l {05-qdoc-commands-documentstructure.html#sectionOne-command} {\\section1} + \o \l {05-qdoc-commands-documentstructure.html#sectionTwo-command} {\\section2} + \o \l {05-qdoc-commands-documentstructure.html#sectionThree-command} {\\section3} + \o \l {05-qdoc-commands-documentstructure.html#sectionFour-command} {\\section4} + \o \l {13-qdoc-commands-topics.html#service-command} {\\service} + \o \l {16-qdoc-commands-status.html#since-command} {\\since} + \o \l {07-0-qdoc-commands-includingexternalcode.html#skipline-command} {\\skipline} + \o \l {07-0-qdoc-commands-includingexternalcode.html#skipto-command} {\\skipto} + \o \l {07-0-qdoc-commands-includingexternalcode.html#skipuntil-command} {\\skipuntil} + \o \l {07-0-qdoc-commands-includingexternalcode.html#snippet-command} {\\snippet}, + \o \l {04-qdoc-commands-textmarkup.html#span-command} {\\span} \span {class="newStuff"} {(new)} + \o \l {15-qdoc-commands-navigation.html#startpage-command} {\\startpage} + \o \l {04-qdoc-commands-textmarkup.html#sub-command} {\\sub} + \o \l {20-qdoc-commands-namingthings.html#subtitle-command} {\\subtitle} + \o \l {04-qdoc-commands-textmarkup.html#sup-command} {\\sup} + \o \l {10-qdoc-commands-tablesandlists.html#table-command} {\\table} + \o \l {11-qdoc-commands-specialcontent.html#tableofcontents-command} {\\tableofcontents} + \o \l {08-qdoc-commands-creatinglinks.html#target-command} {\\target} + \o \l {17-qdoc-commands-thread.html#threadsafe-command} {\\threadsafe} + \o \l {20-qdoc-commands-namingthings.html#title-command} {\\title} + \o \l {04-qdoc-commands-textmarkup.html#tt-command} {\\tt} + \o \l {13-qdoc-commands-topics.html#typedef-command} {\\typedef} + \o \l {04-qdoc-commands-textmarkup.html#underline-command} {\\underline} + \o \l {13-qdoc-commands-topics.html#variable-command} {\\variable} + \o \l {10-qdoc-commands-tablesandlists.html#value-command} {\\value} + \o \l {11-qdoc-commands-specialcontent.html#warning-command} {\\warning} \endlist */ |