From 500ee5b8888eed68f3d237c498c56ef0ebb9795e Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Fri, 21 Aug 2009 13:07:45 +0200 Subject: qdoc: Redesigned the Class and Function Documentation page. --- doc/src/classes.qdoc | 123 +++++++++++++---------- doc/src/classes/exportedfunctions.qdoc | 6 +- doc/src/index.qdoc | 2 +- doc/src/legal/commercialeditions.qdoc | 12 ++- doc/src/modules.qdoc | 52 +++++----- doc/src/platforms/winsystem.qdoc | 4 +- src/3rdparty/webkit/WebKit/qt/docs/qtwebkit.qdoc | 2 +- src/corelib/global/qendian.qdoc | 2 +- src/corelib/global/qglobal.cpp | 10 +- src/corelib/tools/qalgorithms.qdoc | 4 +- tools/qdoc3/htmlgenerator.cpp | 7 +- tools/qdoc3/node.h | 2 + 12 files changed, 129 insertions(+), 97 deletions(-) diff --git a/doc/src/classes.qdoc b/doc/src/classes.qdoc index 864445f..24acce1 100644 --- a/doc/src/classes.qdoc +++ b/doc/src/classes.qdoc @@ -41,58 +41,85 @@ /*! \group classlists - \title Class and Function Indexes - \brief Collections of classes and functions grouped together into lists. + \title Class and Function Documentation + \brief Lists and Indexes of classes, functions, and types. - The following documents contain collections of classes, grouped by - subject area or related to particular functionality, or comprehensive - lists of classes and functions. + Links to indexes and lists for finding class and function + reference documentation. + + \section2 Class Lists + + \annotatedlist classlists + + \section2 Function Lists + + \annotatedlist funclists - \generatelist{related} */ /*! - \group groups - \title Grouped Classes + \page classes.html + \title All Qt Classes (main index) \ingroup classlists - This page provides a way of navigating Qt's classes by grouping - related classes together. Some classes may appear in more than one group. + \brief If you know the name of the class you want, find it here. - \generatelist{related} + 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 + \sa {Qt3 Support Classes}, {All Qt Modules}, {Obsolete Classes} */ /*! - \page classes.html - \title Qt's Classes + \page annotated.html + \title Annotated Class List \ingroup classlists - This is a list of all Qt classes. For a list of the classes provided - for compatibility with Qt3, see \l{Qt 3 compatibility classes}. For - classes that have been deprecated, see the \l{Obsolete Classes} list. + \brief If you don't know the name of the class you want, but you + know what the class should do, you might try looking here. - \generatelist classes + Qt classes with brief descriptions: - \sa {Qt 3 Compatibility Classes}, {Qt's Modules}, {Obsolete Classes} + \generatelist annotatedclasses */ /*! - \page namespaces.html - \title Qt's Namespaces + \group groups + \title Groups Of Related Classes \ingroup classlists - This is a list of the main namespaces in Qt. For a list of classes in - Qt, see \l{Qt's Classes}. + \brief If you know what kind of class you want (GUI, painting, + I.O, etc), look here. - \generatelist{namespaces} + This is a list of functional groups of Qt classes. A class can + appear in more than one functional group. + + \generatelist{related} + +*/ + +/*! + \page hierarchy.html + + \title Inheritance Hierarchy + \ingroup classlists + + \brief The C++ class inheritance hierarchy for all classes in the + Qt API. + + \generatelist classhierarchy */ /*! \page obsoleteclasses.html \title Obsolete Classes \ingroup classlists - + + \brief These classes are obsolete and should not be used in new code. This is a list of Qt classes that are obsolete (deprecated). These classes are provided to keep old source code working but they are @@ -101,52 +128,46 @@ \generatelist obsoleteclasses - \sa {Qt's Classes}, {Qt's Modules} */ /*! - \page annotated.html - \title Annotated Class Index + \page compatclasses.html + \title Qt3 Support Classes \ingroup classlists - Qt's classes with brief descriptions: + \brief These classes ease the porting of code from Qt 3 to Qt 4. - \generatelist annotatedclasses -*/ - -/*! - \page functions.html - \title Member Function Index - \ingroup classlists + These are the classes that Qt provides for compatibility with Qt + 3. Most of these are provided by the Qt3Support module. - Here is the list of all the documented member functions in the Qt - API with links to the class documentation for each function. + \generatelist compatclasses - \generatelist functionindex */ /*! - \page hierarchy.html + \page functions.html + \title All Functions (main index) + \ingroup funclists - \title Class Inheritance Hierarchy - \ingroup classlists + \brief All documented Qt functions listed alphabetically with a + link to where each one is declared. - This list shows the C++ class inheritance relations between the - classes in the Qt API. + 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 classhierarchy + \generatelist functionindex */ + /*! - \page compatclasses.html - \title Qt 3 Compatibility Classes + \page namespaces.html + \title All Qt Namespaces \ingroup classlists - This is a list of the classes that Qt provides for compatibility - with Qt 3. The vast majority of these are provided by the - Qt3Support module. + \brief A Qt namespace contains enum types, functions, and sometimes classes. - \generatelist compatclasses + This is a list of the main namespaces in Qt. - \sa {Qt's Classes}, {Qt's Modules} + \generatelist{namespaces} */ diff --git a/doc/src/classes/exportedfunctions.qdoc b/doc/src/classes/exportedfunctions.qdoc index c51ace4..a0e3904 100644 --- a/doc/src/classes/exportedfunctions.qdoc +++ b/doc/src/classes/exportedfunctions.qdoc @@ -41,8 +41,10 @@ /*! \page exportedfunctions.html - \title Special-Purpose Global Functions Exported by Qt - \ingroup classlists + \title Platform-Specific Functions + \ingroup funclists + + \brief Exported functions for fine tuning Qt applications. Qt provides a few low-level global functions for fine-tuning applications. Most of these perform very specific tasks and are diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc index b0695b8..4d92157 100644 --- a/doc/src/index.qdoc +++ b/doc/src/index.qdoc @@ -81,7 +81,7 @@ diff --git a/doc/src/legal/commercialeditions.qdoc b/doc/src/legal/commercialeditions.qdoc index 761a53b..93dc194 100644 --- a/doc/src/legal/commercialeditions.qdoc +++ b/doc/src/legal/commercialeditions.qdoc @@ -91,8 +91,8 @@ following pages: \list - \o \l{Qt GUI Framework Edition Classes} - \o \l{Qt Full Framework Edition Classes} + \o \l{Qt GUI Framework Edition} + \o \l{Qt Full Framework Edition} \endlist Please see the \l{Supported Platforms}{list of supported @@ -119,16 +119,20 @@ /*! \page full-framework-edition-classes.html - \title Qt Full Framework Edition Classes + \title Qt Full Framework Edition \ingroup classlists + \brief The list of Qt classes included in the Full Framework Edition. + \generatelist{classesbyedition Desktop} */ /*! \page gui-framework-edition-classes.html - \title Qt GUI Framework Edition Classes + \title Qt GUI Framework Edition \ingroup classlists + \brief The list of Qt classes included in the GUI Framework Edition. + \generatelist{classesbyedition DesktopLight} */ diff --git a/doc/src/modules.qdoc b/doc/src/modules.qdoc index 2fc6eaf..786122e 100644 --- a/doc/src/modules.qdoc +++ b/doc/src/modules.qdoc @@ -41,14 +41,14 @@ /*! \group modules - \title Qt's Modules + \title All Qt Modules \startpage index.html Qt Reference Documentation \nextpage QtCore \ingroup classlists - Qt 4 consists of several modules, each of which lives in a - separate library. + \brief Qt 4 comprises several modules. Each module is a separate + library. \table 80% \header \o {2,1} \bold{Modules for general software development} @@ -89,14 +89,14 @@ or other build tools such as CMake, you also need to link against the \c qtmain library. - \sa {Qt's Classes} + \sa {Class and Function Documentation} */ /*! \module QtCore \title QtCore Module - \contentspage Qt's Modules - \previouspage Qt's Modules + \contentspage All Qt Modules + \previouspage All Qt Modules \nextpage QtGui \ingroup modules @@ -116,7 +116,7 @@ /*! \module QtGui \title QtGui Module - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtCore \nextpage QtNetwork \ingroup modules @@ -135,7 +135,7 @@ /*! \module QtMultimedia \title QtMultimedia Module - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtCore \nextpage QtNetwork \ingroup modules @@ -159,7 +159,7 @@ /*! \module QtNetwork \title QtNetwork Module - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtMultimedia \nextpage QtOpenGL \ingroup modules @@ -184,7 +184,7 @@ /*! \module QtOpenGL \title QtOpenGL Module - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtNetwork \nextpage QtOpenVG \ingroup modules @@ -236,7 +236,7 @@ \module QtOpenVG \title QtOpenVG Module \since 4.6 - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtOpenGL \nextpage QtScript \ingroup modules @@ -291,7 +291,7 @@ \module QtScript \title QtScript Module \since 4.3 - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtOpenVG \nextpage QtScriptTools \ingroup modules @@ -321,7 +321,7 @@ \module QtScriptTools \title QtScriptTools Module \since 4.5 - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtScript \nextpage QtSql \ingroup modules @@ -350,7 +350,7 @@ /*! \module QtSql \title QtSql Module - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtScript \nextpage QtSvg \ingroup modules @@ -373,7 +373,7 @@ \module QtSvg \title QtSvg Module \since 4.1 - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtSql \nextpage QtWebKit \ingroup modules @@ -428,7 +428,7 @@ /*! \module QtXml \title QtXml Module - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtSvg \nextpage QtXmlPatterns \ingroup modules @@ -458,7 +458,7 @@ \module QtXmlPatterns \title QtXmlPatterns Module \since 4.4 - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtXml \nextpage Phonon Module \ingroup modules @@ -533,7 +533,7 @@ \page phonon-module.html \module Phonon \title Phonon Module - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtXmlPatterns \nextpage Qt3Support \ingroup modules @@ -604,7 +604,7 @@ /*! \module Qt3Support \title Qt3Support Module - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage Phonon Module \nextpage QtDesigner \ingroup modules @@ -645,7 +645,7 @@ /*! \module QtDesigner \title QtDesigner Module - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage Qt3Support \nextpage QtUiTools \ingroup modules @@ -676,7 +676,7 @@ \module QtUiTools \title QtUiTools Module \since 4.1 - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtDesigner \nextpage QtHelp \ingroup modules @@ -716,7 +716,7 @@ /*! \module QtHelp \title QtHelp Module - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtUiTools \nextpage QtTest \ingroup modules @@ -779,7 +779,7 @@ /*! \module QtTest \title QtTest Module - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtHelp \nextpage QAxContainer \ingroup modules @@ -809,7 +809,7 @@ /*! \module QAxContainer \title QAxContainer Module - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtTest \nextpage QAxServer \ingroup modules @@ -859,7 +859,7 @@ /*! \module QAxServer \title QAxServer Module - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QAxContainer \nextpage QtDBus module \ingroup modules @@ -909,7 +909,7 @@ /*! \module QtDBus \title QtDBus module - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QAxServer \ingroup modules diff --git a/doc/src/platforms/winsystem.qdoc b/doc/src/platforms/winsystem.qdoc index 5afa1f7..c20973b 100644 --- a/doc/src/platforms/winsystem.qdoc +++ b/doc/src/platforms/winsystem.qdoc @@ -51,8 +51,8 @@ appropriate \c{#ifdef} directives (see below). Qt provides a few low-level global functions for fine-tuning - applications on specific platforms. See \l{Special-Purpose Global - Functions Exported by Qt} for details. + applications on specific platforms. See \l{Platform-Specific + Functions} for details. \tableofcontents diff --git a/src/3rdparty/webkit/WebKit/qt/docs/qtwebkit.qdoc b/src/3rdparty/webkit/WebKit/qt/docs/qtwebkit.qdoc index 144feb5..e3c904b 100644 --- a/src/3rdparty/webkit/WebKit/qt/docs/qtwebkit.qdoc +++ b/src/3rdparty/webkit/WebKit/qt/docs/qtwebkit.qdoc @@ -1,7 +1,7 @@ /*! \module QtWebKit \title QtWebKit Module - \contentspage Qt's Modules + \contentspage All Qt Modules \previouspage QtSvg \nextpage QtXml \ingroup modules diff --git a/src/corelib/global/qendian.qdoc b/src/corelib/global/qendian.qdoc index e0ef662..949f7b8 100644 --- a/src/corelib/global/qendian.qdoc +++ b/src/corelib/global/qendian.qdoc @@ -42,7 +42,7 @@ /*! \headerfile \title Endian Conversion Functions - \ingroup classlists + \ingroup funclists \brief The header provides functions to convert between little and big endian representations of numbers. */ diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp index 81a5ae5..5fe2b2f 100644 --- a/src/corelib/global/qglobal.cpp +++ b/src/corelib/global/qglobal.cpp @@ -401,13 +401,13 @@ QT_BEGIN_NAMESPACE /*! \headerfile \title Global Qt Declarations - \ingroup classlists + \ingroup funclists - \brief The header provides basic declarations and - is included by all other Qt headers. + \brief The header file includes the fundamental global + declarations. It is included by most other Qt header files. - The declarations include \l {types}, \l functions and - \l macros. + The global declarations include \l{types}, \l{functions} and + \l{macros}. The type definitions are partly convenience definitions for basic types (some of which guarantee certain bit-sizes on all platforms diff --git a/src/corelib/tools/qalgorithms.qdoc b/src/corelib/tools/qalgorithms.qdoc index f7b7798..771c544 100644 --- a/src/corelib/tools/qalgorithms.qdoc +++ b/src/corelib/tools/qalgorithms.qdoc @@ -42,9 +42,9 @@ /*! \headerfile \title Generic Algorithms - \ingroup classlists + \ingroup funclists - \brief The header provides generic template-based algorithms. + \brief The header includes the generic, template-based algorithms. Qt provides a number of global template functions in \c that work on containers and perform well-know diff --git a/tools/qdoc3/htmlgenerator.cpp b/tools/qdoc3/htmlgenerator.cpp index 84e330f..3d62d7c 100644 --- a/tools/qdoc3/htmlgenerator.cpp +++ b/tools/qdoc3/htmlgenerator.cpp @@ -539,12 +539,15 @@ int HtmlGenerator::generateAtom(const Atom *atom, break; case Atom::AnnotatedList: { + //qDebug() << "ANNOTATED LIS:"; QList values = tre->groups().values(atom->string()); QMap nodeMap; for (int i = 0; i < values.size(); ++i) { const Node* n = values.at(i); - if ((n->status() != Node::Internal) && (n->access() != Node::Private)) - nodeMap.insert(n->name(),n); + if ((n->status() != Node::Internal) && (n->access() != Node::Private)) { + nodeMap.insert(n->nameForLists(),n); + //qDebug() << " " << n->nameForLists(); + } } generateAnnotatedList(relative, marker, nodeMap); } diff --git a/tools/qdoc3/node.h b/tools/qdoc3/node.h index 0cddf51..e956fed 100644 --- a/tools/qdoc3/node.h +++ b/tools/qdoc3/node.h @@ -157,6 +157,7 @@ class Node QMap > links() const { return linkMap; } QString moduleName() const; QString url() const; + virtual QString nameForLists() const { return nam; } Access access() const { return acc; } const Location& location() const { return loc; } @@ -337,6 +338,7 @@ class FakeNode : public InnerNode QString fullTitle() const; QString subTitle() const; const NodeList &groupMembers() const { return gr; } + virtual QString nameForLists() const { return title(); } private: SubType sub; -- cgit v0.12