From 733e0df1a79ff2856395d343c7dd46061b00faef Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Tue, 22 Feb 2011 10:17:15 +0100 Subject: qdoc: More updating command descriptions. --- doc/src/overviews.qdoc | 2 +- tools/qdoc3/doc/qdoc-manual.qdoc | 346 +++++++++++++++++++-------------------- 2 files changed, 170 insertions(+), 178 deletions(-) diff --git a/doc/src/overviews.qdoc b/doc/src/overviews.qdoc index b9bd3b4..e5d2aac 100644 --- a/doc/src/overviews.qdoc +++ b/doc/src/overviews.qdoc @@ -62,7 +62,7 @@ /*! \group qt-graphics - \ingroup qt-basic-concepts + \ingroup qt-basic-concepts \title Qt Graphics and Printing \brief The Qt components for doing graphics. diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc index a81d15a..69151ca 100644 --- a/tools/qdoc3/doc/qdoc-manual.qdoc +++ b/tools/qdoc3/doc/qdoc-manual.qdoc @@ -4184,225 +4184,220 @@ \target class-command \section1 \\class - The \\class command tells QDoc that a class is - part of the public API, and lets you enter a detailed + 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 {topic argument} {the general - topic 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 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. - The generated HTML documentation for the specified class is - put in \c classname.html. For example, the - documentation for the \c PreviewWindow class is located in - \c previewwindow.html. + \target framework - \target framework + 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. - 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. + 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: - The command is typically accompanied with a \l - {brief-command} {\\brief} command, a \l {mainclass-command} {\\mainclass} - command, an \l {ingroup-command} {\\ingroup} command and a \l - {sa-command} {\\sa} command. For 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. + \ingroup miscellaneous - \mainclass - \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 + ... - QDoc renders this as: + \sa QWidget + * / + \endcode - \quotation - \raw HTML -

PreviewWindow Class Reference

- \endraw + 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: - 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 +

PreviewWindow Class Reference

+ \endraw - \raw HTML -

Properties

- \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 +

Properties

+ \endraw - \raw HTML -

Public Functions

- \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 +

Public Functions

+ \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 -

Public Slots

- \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 +

Public Slots

+ \endraw - \raw HTML -

Additional Inherited Members

- \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 +

Additional Inherited Members

+ \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 -
-

Detailed Description

- \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 +
+

Detailed Description

+ \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 -
-

Member Function Documentation

- \endraw + See also QWidget. - \target constructor - \raw HTML -

PreviewWindow(QWidget *parent = 0)

- \endraw + \raw HTML +
+

Member Function Documentation

+ \endraw - Constructs a preview window widget with \e parent. + \target constructor + \raw HTML +

PreviewWindow(QWidget *parent = 0)

+ \endraw - \target function - \raw HTML -

setWindowFlags(Qt::WindowFlags flags)

- \endraw + Constructs a preview window widget with \e parent. - Sets the widgets flags using the - QWidget::setWindowFlags() function. + \target function + \raw HTML +

setWindowFlags(Qt::WindowFlags flags)

+ \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. + 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 \target enum-command \section1 \\enum - The \\enum command allows you to document a C++ enum. - - The command follows \l {topic argument} {the general - topic command convention} for the argument. - - The enum items are documented using the \l {value-command} {\\value} - command. If an item isn't documented, QDoc will emit a - warning. This can be avoided using the \l - {omitvalue-command} {\\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 QDoc renders this as: + QDoc renders this enum type in \c {qt.html} something like this: \quotation \raw HTML @@ -4445,10 +4440,7 @@ \endraw \endquotation - in qt.html. - - See also \l {value-command} {\\value} and \l {omitvalue-command} {\\omitvalue}. - + See also \l {value-command} {\\value} and \l {omitvalue-command} {\\omitvalue}. \target example-command \section1 \\example -- cgit v0.12