From cb7aaec6e914b8fd30520aa02645aae9e2dd1e91 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Wed, 23 Feb 2011 12:19:57 +0100 Subject: qdoc: More updating command descriptions. --- tools/qdoc3/doc/qdoc-manual.qdoc | 478 ++++++++++++++++++--------------------- 1 file changed, 221 insertions(+), 257 deletions(-) diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc index 5945aea..ddce165 100644 --- a/tools/qdoc3/doc/qdoc-manual.qdoc +++ b/tools/qdoc3/doc/qdoc-manual.qdoc @@ -4398,7 +4398,7 @@ \endcode Note the inclusion of the namespace qualifier. QDoc will render - this enum type in \c {qt.html} something like this: + this enum type in \c {qt.html} like this: \quotation \raw HTML @@ -4569,7 +4569,7 @@ \endcode QDoc generates a group page in \c{io.html} that will look - something like this: + like this: \quotation \raw HTML @@ -4663,7 +4663,7 @@ \endcode QDoc generates a header file page \c{qtalgorithms.html} that looks - something like this: + like this: \quotation \raw HTML @@ -4831,7 +4831,7 @@ * / \endcode - QDoc renders this in \c {qtnetwork.html} something like this: + QDoc renders this in \c {qtnetwork.html} like this: \quotation \raw HTML @@ -4913,7 +4913,7 @@ * / \endcode - QDoc renders this in \c{qt.html} something like this: + QDoc renders this in \c{qt.html} like this: \quotation \raw HTML @@ -5035,336 +5035,300 @@ \target property-command \section1 \\property - The \\property command allows you to document a Qt property. - - The command follows \l {topic argument} {the general - topic command convention} for the argument. + The \\property command is for documenting a Qt property. The + argument is the full property name. - A property is defined using the Q_PROPERTY() macro. The - macro takes as arguments the property's name and its set, - reset and get functions. For example: - - \code - Q_PROPERTY(QString state READ state WRITE setState) - \endcode + A property is defined using the Q_PROPERTY() macro. The macro + takes as arguments the property's name and its set, reset and get + functions. For example: - The set, reset and get functions don't need to be - documented, documenting the property is sufficient. QDoc - will generate a list of the access function that will - appear in the property documentation which in turn will be - located in the documentation of the class that defines the - property. - - The \\property command is typically accompanied with a \l - {brief-command} {\\brief} command. In the case of a - property, the \l {brief-command} {\\brief} command's - argument is a sentence fragment that will be included in a - one-sentence description of the property generated by - QDoc. The command follows the same rules for the \l - {brief-property} {description} as the \l {variable-command} - {\\variable} command. + \code + Q_PROPERTY(QString state READ state WRITE setState) + \endcode - For example: + The set, reset and get functions don't need to be documented, + documenting the property is sufficient. QDoc will generate a list + of the access function that will appear in the property + documentation which in turn will be located in the documentation + of the class that defines the property. - \code - / *! - \property QPushButton::flat - \brief whether the border is disabled + The \\property command comment typically includes a \l + {brief-command} {\\brief} command. Forproperties the \l + {brief-command} {\\brief} command's argument is a sentence + fragment that will be included in a one line description of the + property. The command follows the same rules for the \l + {brief-property} {description} as the \l {variable-command} + {\\variable} command. For example: - This property's default is false. - * / - \endcode + \code + / *! + \property QPushButton::flat + \brief whether the border is disabled - QDoc renders this as: + This property's default is false. + * / + \endcode - \quotation - \raw HTML -

flat : bool

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

flat : bool

+ \endraw - This property's default is false. + This property holds whether the border is disabled. - Access functions: + This property's default is false. - \list - \o \bold { bool isFlat () const} - \o \bold { void setFlat ( bool )} - \endlist + Access functions: - \endquotation + \list + \o \bold { bool isFlat () const} + \o \bold { void setFlat ( bool )} + \endlist - in qpushbutton.html. And + \endquotation - \code - / *! - \property QWidget::width - \brief the width of the widget excluding any window frame + \code + / *! + \property QWidget::width + \brief the width of the widget excluding any window frame - See the \l {Window Geometry} documentation for an - overview of window geometry. + See the \l {Window Geometry} documentation for an + overview of window geometry. - \sa geometry, height, size - * / - \endcode + \sa geometry, height, size + * / + \endcode - QDoc renders this as: + QDoc includes this in \c {qwidget.html} like this: - \quotation - \raw HTML -

width : const int

- \endraw + \quotation + \raw HTML +

width : const int

+ \endraw - This property holds the width of the widget excluding - any window frame. + This property holds the width of the widget excluding + any window frame. - See the \l {Window Geometry} documentation for an - overview of window geometry. + See the \l {Window Geometry} documentation for an + overview of window geometry. - Access functions: + Access functions: - \list - \o \bold { int width () const} - \endlist - - See also \l{QWidget::geometry} {geometry}, - \l{QWidget::height} {height}, and \l{QWidget::size} {size}. - \endquotation - - in qwidget.html. + \list + \o \bold { int width () const} + \endlist + See also \l{QWidget::geometry} {geometry}, + \l{QWidget::height} {height}, and \l{QWidget::size} {size}. + \endquotation \target service-command \section1 \\service - The \\service command tells QDoc that a class is a - service class and specifies its alias, i.e. the associated - service's name. - - The command takes two arguments, the service class's name - and the associated alias. For example: - - \code - / *! - \service TimeService Time - ... - * / - class TimeService : public QCopObjectService - { - ... - } - \endcode - - See also \l {class-command} {\\class} and \l - {generatelist-command} {\\generatelist}. - + The \\service command tells QDoc that a class is a service class + and names the service. The command takes two arguments, the name + of the class and the name of the service. Currently, this command + is not used in the Qt documentation. + + \code + / *! + \service TimeService Time + ... + * / + class TimeService : public QCopObjectService + { + ... + } + \endcode + + See also \l {class-command} {\\class} and \l + {generatelist-command} {\\generatelist}. \target typedef-command \section1 \\typedef - The \\typedef command allows you to document a C++ type definition. - - The command follows \l {topic argument} {the general - topic command convention} for the argument. - - The documentation will be located in the associated class, - header file or namespace documentation. When documenting a - global type definition, the \\typedef command must be - accompanied with a \l {relates-command} {\\relates} command. For - example: - - \code - / *! - \typedef QObjectList - \relates QObject - - Synonym for QList. - * / - \endcode - - QDoc renders this as: + The \\typedef command is for documenting a C++ typedef. The + argument is the name of the typedef. The documentation for + the typedef will be included in the refernece documentation + for the class, namespace, or header file in which the typedef + is declared. To relat the \\typedef to a class, namespace, or + header file, the \\typedef comment must contain a + \l {relates-command} {\\relates} command. For example: - \quotation - \raw HTML -

typedef QObjectList

- \endraw + \code + / *! + \typedef QObjectList + \relates QObject - Synonym for QList. - \endquotation + Synonym for QList. + * / + \endcode - in qobject.html. Another, although more rare, example is + QDoc includes this in \c {qobject.html} as: - \code - / *! - \typedef QMsgHandler - \relates QtGlobal + \quotation + \raw HTML +

typedef QObjectList

+ \endraw - This is a typedef for a pointer to a function with the - following signature: + Synonym for QList. + \endquotation - \code - void myMsgHandler(QtMsgType, const char *); - \ endcode + Another, although more rare, example: - \sa QtMsgType, qInstallMsgHandler() - * / - \endcode + \code + / *! + \typedef QMsgHandler + \relates QtGlobal - QDoc renders this as: + This is a typedef for a pointer to a function with the + following signature: - \quotation - \raw HTML -

typedef QtMsgHandler

- \endraw + \code + void myMsgHandler(QtMsgType, const char *); + \ endcode - This is a typedef for a pointer to a function with the - following signature: + \sa QtMsgType, qInstallMsgHandler() + * / + \endcode - \raw HTML - - 
    void myMsgHandler(QtMsgType, const char *);
- - \endraw + QDoc includes this in \c {qtglobal.html} as: - See also QtMsgType and qInstallMsgHandler(). + \quotation + \raw HTML +

typedef QtMsgHandler

+ \endraw - \endquotation + This is a typedef for a pointer to a function with the + following signature: - in qtglobal.html. Other type definitions are located in the - documentation of the class that defines it, for example: + \raw HTML + + 
    void myMsgHandler(QtMsgType, const char *);
+ + \endraw - \code - / *! - \typedef QLinkedList::Iterator + See also QtMsgType and qInstallMsgHandler(). + \endquotation - Qt-style synonym for QList::iterator. - * / - \endcode + Other typedefs are located on the reference page for the class + that defines them. For example: - QDoc renders this as: + \code + / *! + \typedef QLinkedList::Iterator - \quotation - \raw HTML -

typedef QLinkedList::Iterator

- \endraw + Qt-style synonym for QList::iterator. + * / + \endcode - Qt-style synonym for QList::iterator. - \endquotation + QDoc includes this one on the reference page for class QLinkedList as: - in qlinkedlist.html. + \quotation + \raw HTML +

typedef QLinkedList::Iterator

+ \endraw + Qt-style synonym for QList::iterator. + \endquotation \target variable-command \section1 \\variable - The \\variable command allows you to document a - member variable or a constant. - - The command follows \l {topic argument} {the general - topic command convention} for the argument. - - The \\variable command is typically followed by a - \l {brief-command} {\\brief} command; QDoc will generate the - documentation for the variable based on the brief command - description. The command follows the same rules for the - \l {brief-property} {description} as the \l {property-command} - {\\property} command. - - The documentation will be located in the in the associated - class, header file or namespace documentation. - - In case of a member variable: - - \code - / *! - \variable QStyleOption::palette - \brief the palette that should be used when painting - the control - * / - \endcode + The \\variable command is for documenting a class member variable + or a constant. The argument is the variable or constant name. The + \\variable command comment includes a \l {brief-command} {\\brief} + command. QDoc generates the documentation based on the text from + \\brief command. - QDoc renders this as: + The documentation will be located in the in the associated class, + header file or namespace documentation. - \quotation - \raw HTML -

- - QPalette - - QStyleOption::palette -

- \endraw + In case of a member variable: - This variable holds the palette that should be used - when painting the control. - \endquotation - - in qstyleoption.html. - - But you can also use the \\variable command to document - constants like for example the \c Type and \c UserType - constants in the QTreeWidgetItem class: + \code + / *! + \variable QStyleOption::palette + \brief the palette that should be used when painting + the control + * / + \endcode - \code - enum { Type = 0, UserType = 1000 }; - \endcode + QDoc includes this in qstyleoption.html as: - Then + \quotation + \raw HTML +

+ + QPalette + + QStyleOption::palette +

+ \endraw - \code - / *! - \variable QTreeWidgetItem::Type + This variable holds the palette that should be used + when painting the control. + \endquotation - The default type for tree widget items. + You can also document constants with the \\variable command. For + example, suppose you have the \c Type and \c UserType constants in + the QTreeWidgetItem class: - \sa UserType, type() - * / - \endcode + \code + enum { Type = 0, UserType = 1000 }; + \endcode - and + For these, the \\vaqriable command can be used this way: - \code - / *! - \variable QTreeWidgetItem::UserType + \code + / *! + \variable QTreeWidgetItem::Type - The minimum value for custom types. Values below - UserType are reserved by Qt. + The default type for tree widget items. - \sa Type, type() - * / - \endcode + \sa UserType, type() + * / + \endcode + \code + / *! + \variable QTreeWidgetItem::UserType - QDoc renders this as: + The minimum value for custom types. Values below + UserType are reserved by Qt. - \quotation - \raw HTML -

- const int QTreeWidgetItem::Type -

- \endraw + \sa Type, type() + * / + \endcode - The default type for tree widget items. + QDoc includes these in qtreewidget.html as: - See also \l {QTreeWidgetItem::UserType} {UserType} and - \l {QTreeWidgetItem::type()} {type()}. + \quotation + \raw HTML +

+ const int QTreeWidgetItem::Type +

+ \endraw - \raw HTML -

- const int QTreeWidgetItem::UserType -

- \endraw + The default type for tree widget items. - The minimum value for custom types. Values below - UserType are reserved by Qt. + See also \l {QTreeWidgetItem::UserType} {UserType} and \l + {QTreeWidgetItem::type()} {type()}. - See also \l {QTreeWidgetItem::Type} {Type} and - \l{QTreeWidgetItem::type()} {type()}. + \raw HTML +

+ const int QTreeWidgetItem::UserType +

+ \endraw - \endquotation + The minimum value for custom types. Values below + UserType are reserved by Qt. - in qtreewidget.html. + See also \l {QTreeWidgetItem::Type} {Type} and + \l{QTreeWidgetItem::type()} {type()}. + \endquotation */ /*! -- cgit v0.12 From eadd122e5b713047e3e7896603da1c579e4da205 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Wed, 23 Feb 2011 12:53:21 +0100 Subject: qdoc: More updating command descriptions. --- tools/qdoc3/doc/qdoc-manual.qdoc | 45 ++++++++++------------------------------ 1 file changed, 11 insertions(+), 34 deletions(-) diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc index ddce165..24c5972 100644 --- a/tools/qdoc3/doc/qdoc-manual.qdoc +++ b/tools/qdoc3/doc/qdoc-manual.qdoc @@ -38,7 +38,7 @@ \o \l {Topic Commands} \o \l {Context Commands} \list - \o \l {Navigating} + \o \l {Document Navigation} \o \l {Reporting Status} \o \l {Thread Support} \o \l {Relating Things} @@ -5335,49 +5335,26 @@ \page 14-qdoc-commands-contextcommands.html \previouspage Topic Commands \contentspage Table of Contents - \nextpage Navigating + \nextpage Document Navigation \title Context Commands - The context 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. + 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 we put them at the top of the comment, right below the \l + {Topic Commands} {topic} command. \section1 Categories \list - \o \l {Navigating} + \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 - - \section1 Command List - - \list - \o \l {16-qdoc-commands-status.html#compat-command} {\\compat} - \o \l {15-qdoc-commands-navigation.html#contentspage-command} {\\contentspage} - \o \l {15-qdoc-commands-navigation.html#indexpage-command} {\\indexpage} - \o \l {19-qdoc-commands-grouping.html#ingroup-command} {\\ingroup} - \o \l {19-qdoc-commands-grouping.html#inmodule-command} {\\inmodule} - \o \l {16-qdoc-commands-status.html#internal-command} {\\internal} - \o \l {19-qdoc-commands-grouping.html#mainclass-command} {\\mainclass} - \o \l {15-qdoc-commands-navigation.html#nextpage-command} {\\nextpage} - \o \l {17-qdoc-commands-thread.html#nonreentrant-command} {\\nonreentrant} - \o \l {16-qdoc-commands-status.html#obsolete-command} {\\obsolete} - \o \l {18-qdoc-commands-relating.html#overload-command} {\\overload} - \o \l {16-qdoc-commands-status.html#preliminary-command} {\\preliminary} - \o \l {15-qdoc-commands-navigation.html#previouspage-command} {\\previouspage} - \o \l {17-qdoc-commands-thread.html#reentrant-command} {\\reentrant} - \o \l {18-qdoc-commands-relating.html#reimp-command} {\\reimp} - \o \l {18-qdoc-commands-relating.html#relates-command} {\\relates} - \o \l {15-qdoc-commands-navigation.html#startpage-command} {\\startpage} - \o \l {17-qdoc-commands-thread.html#threadsafe-command} {\\threadsafe} - \o \l {20-qdoc-commands-namingthings.html#title-command} {\\title} - \endlist */ /*! @@ -5386,7 +5363,7 @@ \contentspage Table of Contents \nextpage Reporting Status - \title Navigating + \title Document Navigation The navigation commands allow you to link the pages of a multipage document together. They provide the components of a navigation bar @@ -5609,7 +5586,7 @@ /*! \page 16-qdoc-commands-status.html - \previouspage Navigating + \previouspage Document Navigation \contentspage Table of Contents \nextpage Thread Support -- cgit v0.12 From 309c48a70b46678ef92da441fcc2dc96ceb8fcf3 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Wed, 23 Feb 2011 14:46:20 +0100 Subject: qdoc: More updating command descriptions. --- tools/qdoc3/doc/qdoc-manual.qdoc | 99 ++++++++++++++++++++++++++++++---------- 1 file changed, 74 insertions(+), 25 deletions(-) diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc index 24c5972..7a08916 100644 --- a/tools/qdoc3/doc/qdoc-manual.qdoc +++ b/tools/qdoc3/doc/qdoc-manual.qdoc @@ -81,26 +81,75 @@ \title Introduction to QDoc - QDoc is a tool used by Qt Developers to extract \e {qdoc comments} - from a set of source files and format them for output as HTML - pages or as DITA XML files.. This manual explains how to use the - QDoc commands and how to create a QDoc configuration file. + QDoc is a tool used by Qt Developers to generate documentation of + software projects by extracting the documentation from the project + source files and then formatting it as HTML pages or DITA XML + documents, etc. The documentation is embedded in the source files + in \e {qdoc comments}. A qdoc comment 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 + + From this snippet, QDoc generates the now famous HTML page \l + {http://doc.trolltech.com/4.7/qobject.html} {QObject Class Reference}. + + This manual explains how to use the QDoc commands to write useful + qdoc comments in your source files. It also explains how to create + a \l {The QDoc Configuration File} {QDoc configuration file}, + which you must pass to QDoc on the command line when you run it. \section1 Running QDoc - QDoc is currently called \c {qdoc3}. To run qdoc3, use the command - line: + 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: \quotation - \bold {/currentdirectory$ qdoc3 config.qdocconf} + \c {/current/dir$ ../../bin/qdoc3 ./config.qdocconf} \endquotation - ...where config.qdocconf is your \l{The QDoc Configuration File} - {QDoc configuration file}. The main purpose of the configuration - file is to tell qdoc3 where to find the source files from which to - extract qdoc comments, what kind of output to generate (HTML, DITA - XML,...}, and where to put the output. The configuration file also - contains other information for qdoc3. + \c{config.qdocconf} is your \l{The QDoc Configuration File} {QDoc + configuration file}. The configuration file is where tell QDoc + where to find the source files from which it will extract the QDoc + comments it will use to generate the documentation. It is also + where you tell QDoc what kind of output to generate (HTML, DITA + XML,...), and where to put the generated output. The configuration + file also contains other information for QDoc. \section1 Command Types @@ -112,20 +161,20 @@ \o \l {Markup Commands} \endlist - Topic commands identify the entity you are documenting, e.g. a C++ + 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 any C++ entity. + that doesn't map to an underlying C++ elememnt. - Context commands tell QDoc how the entity being documented relates - to other documented entities, e.g. next and previous page links or - inclusion in page groups or library modules. They can also provide - information about the documented entity that QDoc can't get from - the source files, e.g. whether the entitity is thread-safe, an - overloaded or reimplemented function, or that it has been - deprecated. + 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 + document should be rendered, or about the document's outline structure. */ @@ -5372,8 +5421,8 @@ \section1 General Description - The QDoc comments below shows a typical example using the - navigation commands. + The QDoc comments below show a typical way of using the navigation + commands. \code / *! -- cgit v0.12 From 8afd2d145e608d9d86860c6400844fe4c39edbb4 Mon Sep 17 00:00:00 2001 From: Geir Vattekar Date: Thu, 24 Feb 2011 11:17:47 +0100 Subject: Doc: Added more info on calling C++ functions from Qt Script Task-number: QTBUG-14959 Reviewed-by: Kent Hansen --- doc/src/scripting/scripting.qdoc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/src/scripting/scripting.qdoc b/doc/src/scripting/scripting.qdoc index 112af5c..f882da0 100644 --- a/doc/src/scripting/scripting.qdoc +++ b/doc/src/scripting/scripting.qdoc @@ -657,6 +657,12 @@ call to \c{connect()} in script code; \c{connect()} accepts both native and non-native functions as targets. + As discussed in \l{Default Conversion from Qt Script to C++}, Qt + Script handles conversion for many C++ types. If your function takes + arguments for which Qt Script does not handle conversion, you need + to supply conversion functions. This is done using the + qScriptRegisterMetaType() function. + \section2 Making C++ Class Properties Available in QtScript In the previous example, if we wanted to get or set a property using -- cgit v0.12