|
|
              
MiscellaneousThese commands provide miscellaneous functions connected to the visual appearance of the documentation, and to the process of generating the documentation. \annotatedlistThe \annotatedlist command expands to a list of the members of a group, each member listed with its brief text. Below is an example from the Qt Reference Documentation: / *! ... \section1 Drag and Drop Classes These classes deal with drag and drop and the necessary mime type encoding and decoding. \annotatedlist draganddrop * / This generates a list of all the classes in the draganddrop group. A class in the draganddrop group will have the \ingroup command in its \class or \qmlclass comment. \generatelistThe \generatelist command expands to a list of various documentation or links to documentation. Below is an example from the Qt Reference Documentation: / *! \page classes.html \title All Classes For a shorter list that only includes the most frequently used classes, see \l{Qt's Main Classes}. For a list of Qt 3 support classes, see \l{Qt3Support Classes}. \generatelist classes * / This generates the All Classes page. The command accepts the following arguments: annotatedclassesThe 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:
A C++ class is documented with the \class command. The annotation for the class is taken from the argument of the class comment's \brief command. classesThe 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 All Classes page this way: / *! \page classes.html \title All Classes \ingroup classlists \brief If you know the name of the class you want, find it here. 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. \generatelist classes * / A C++ class is documented with the \class command. classesbymoduleWhen 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 \brief command. This command is used to generate the Phonon Module page this way. / *! \page phonon-module.html \module Phonon \title Phonon Module \ingroup modules \brief The Phonon module contains namespaces and classes for multimedia functionality. \generatelist{classesbymodule Phonon} ... * / Each class that is a member of the specified module must be marked with the \inmodule command in its \class comment. compatclassesThe compatclasses argument generates a list in alphabetical order of the support classes. It is normally used only to generate the Qt3 Support Classes page this way: / *! \page compatclasses.html \title Qt3 Support Classes \ingroup classlists \brief These classes ease the porting of code from Qt 3 to Qt 4. These are the classes that Qt provides for compatibility with Qt 3. Most of these are provided by the Qt3Support module. \generatelist compatclasses * / A support class is identified in the \class comment with the \compat command. functionindexThe functionindex argument provides a complete alphabetical list of all the documented member functions. It is normally used only to generate the Qt function index page this way: / *! \page functions.html \title All Functions \ingroup funclists \brief All documented Qt functions listed alphabetically with a link to where each one is declared. 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. \generatelist functionindex * / legaleseThe legalese argument tells QDoc to generate a complete list of licenses in the documentation. Each license is identified using the \legalese command. This command is used to generate the Qt license information page this way: / *! \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 * / mainclassesThe mainclasses argument tells QDoc to generate an alphabetical list of the main classes. A class is marked as a main class by including a \mainclass command in the \class comment. Note: The Qt documentation no longer includes a main classes page, but you can generate one for your main classes if you want it. overviewsThe overviews argument is used to tell QDoc to generate a list by concatenating the contents of all the \group pages. Qt uses it to generate the overviews page this way: / *! \page overviews.html \title All Overviews and HOWTOs \generatelist overviews * / relatedThe related argument is used in combination with the \group and \ingroup commands to list all the overviews related to a specified group. For example, the page for the Programming with Qt page is generated this way: / *! \group qt-basic-concepts \title Programming with Qt \brief The basic architecture of the Qt cross-platform application and UI framework. 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. \generatelist {related} * / Each page listed on this group page contains the command: \ingroup qt-basic-concepts serviceThe 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 with the \service command. Note: This command and the \service command are not used in the Qt documentation. \ifThe \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. / *! \if defined(opensourceedition) \b{Note:} This edition is for the development of \l{Qt Open Source Edition} {Free and Open Source} software only; see \l{Qt Commercial Editions}. \endif * / This QDoc comment will only be rendered if the opensourceedition preprocessor symbol is defined, and specified in the defines variable in the configuration file to make QDoc process the code within #ifdef and #endif: defines = opensourceedition
You can also define the preprocessor symbol manually on the command line. For more information see the documentation of the defines variable. See also \endif, \else, defines and falsehoods. \endifThe \endif command and the corresponding \if command enclose parts of a QDoc comment that will be included if the condition specified by the \if command's argument is true. For more information, see the documentation of the \if command. See also \if, \else, defines and falsehoods. \elseThe \else command specifies an alternative if the condition in the \if command is false. The \else command can only be used within \if...\endif commands, but is useful when there is only two alternatives. / *! The Qt 3 support library is provided to keep old source code working. In addition to the \c Qt3Support classes, Qt 4 provides compatibility functions when it's possible for an old API to cohabit with the new one. \if !defined(QT3_SUPPORT) \if defined(QT3_SUPPORTWARNINGS) The compiler emits a warning when a compatibility function is called. (This works only with GCC 3.2+ and MSVC 7.) \else To use the Qt 3 support library, you need to have the line QT += qt3support in your .pro file (qmake automatically define the QT3_SUPPORT symbol, turning on compatibility function support). You can also define the symbol manually (e.g., if you don't want to link against the \c Qt3Support library), or you can define \c QT3_SUPPORT_WARNINGS instead, telling the compiler to emit a warning when a compatibility function is called. (This works only with GCC 3.2+ and MSVC 7.) \endif \endif * / If the QT3_SUPPORT is defined, the comment will be rendered like this:
If QT3_SUPPORT is not defined but QT3_SUPPORT_WARNINGS is defined, the comment will be rendered like this:
If none of the symbols are defined, the comment will be rendered as
See also \if, \endif, defines and falsehoods. \includeThe \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, input, in the QDoc configuration file, e.g. 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 .qdocinc extension for these 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 /*! ... */ 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 two argument form below. Here is an example of the one argument form: / *! \page corefeatures.html \title Core Features \include examples/signalandslots.qdocinc \include examples/objectmodel.qdocinc \include examples/layoutmanagement.qdocinc * / Here are links to the .qdocinc files used above: signalandslots.qdocinc, objectmodel.qdocinc, layoutmanagement.qdocinc. QDoc renders this page as shown here. \include filename snippet-identifierIt is kind of a pain to make a separate .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: //! [snippet-id1] QDoc commands and text... //! [snippet-id1] //! [snippet-id2] More QDoc commands and text... //! [snippet-id2] Then you can use the two-argument form of the command: \input examples/signalandslots.qdocinc snippet-id2 \input examples/objectmodel.qdocinc another-snippet-id 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. \metaThe \meta command is mainly used for including metadata in DITA XML files. It is also used when generating HTML output for specifying the maintainer(s) of a C++ class. The command has two arguments: The first argument is the name of the metadata attribute you wish to set, and the second argument is the value for the attribute. Each argument should be enclosed in curly brackets, as shown in this example: / *! \class QWidget \brief The QWidget class is the base class of all user interface objects. \ingroup basicwidgets \meta {technology} {User Interface} \meta {platform} {OS X 10.6} \meta {platform} {Symbian} \meta {platform} {MeeGo} \meta {audience} {user} \meta {audience} {programmer} \meta {audience} {designer} * / When running QDoc to generate HTML, the example above will have no effect on the generated output, but if you run QDoc to generate DITA XML, the example will generate the following: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE cxxClass PUBLIC "-//NOKIA//DTD DITA C++ API Class Reference Type v0.6.0//EN" "dtd/cxxClass.dtd"> <!--qwidget.cpp--> <cxxClass id="id-9a14268e-6b09-4eee-b940-21a00a0961df"> <apiName>QWidget</apiName> <shortdesc>the QWidget class is the base class of all user interface objects.</shortdesc> <prolog> <author>Qt Development Frameworks</author> <publisher>Nokia</publisher> <copyright> <copyryear year="2011"/> <copyrholder>Nokia</copyrholder> </copyright> <permissions view="all"/> <metadata> <audience type="designer"/> <audience type="programmer"/> <audience type="user"/> <category>Class reference</category> <prodinfo> <prodname>Qt Reference Documentation</prodname> <vrmlist> <vrm version="4" release="7" modification="3"/> </vrmlist> <component>QtGui</component> </prodinfo> <othermeta name="platform" content="MeeGo"/> <othermeta name="platform" content="Symbian"/> <othermeta name="platform" content="OS X 10.6"/> <othermeta name="technology" content="User Interface"/> </metadata> </prolog> In the example output, several values have been set using defualt values obtained from the QDoc configuration file. See Generating DITA XML Output for details. \omitThe \omit command and the correspondning \endomit command delimit parts of the documentation that you want QDoc to skip. For example: / *! \table \row \li Basic Widgets \li Basic GUI widgets such as buttons, comboboxes and scrollbars. \omit \row \li Component Model \li Interfaces and helper classes for the Qt Component Model. \endomit \row \li Database Classes \li Database related classes, e.g. for SQL databases. \endtable * / QDoc renders this as:
\raw (avoid)The \raw command and the corresponding \endraw command delimit a block of raw mark-up language code. 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 \span and \div commands in your \table or \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. / *! Qt has some predefined QColor objects. \raw HTML <style type="text/css" id="colorstyles"> #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="color-blue">Blue(#0000ff)</tt>, <tt id="color-darkBlue">dark blue(#000080)</tt> and <tt id="color-cyan">cyan(#00ffff)</tt>. </p> \endraw * / QDoc renders this as:
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: \tt {\span {id="color-blue"} {Blue(#0000ff)}},
\tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and
\tt {\span {id="color-cyan"} {cyan(#00ffff)}}.
...which is rendered again as: Blue(#0000ff), dark blue(#000080) and cyan(#00ffff). \unicodeThe \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: O G\unicode{0xEA}nio e as Rosas
\unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour
\unicode 0x3A3 \e{a}\sub{\e{i}}
QDoc renders this as:
|
