From 19751d368a5cb1de0487015c6a3ebf7677894181 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Mon, 6 Jul 2015 15:31:45 +0200 Subject: qdoc: Add the noautolist command to qdoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This update adds the \noautolist command to qdoc. This command can be used in the qdoc comment for a \module or \qmlmodule to tell qdoc not to write the automatic annotated list of C++ classes or QML types to the HTML page because the documenter has listed them manually. The qdoc manual is also updated to include the \noautolist command. Change-Id: I2eac5ceebfcd83a41bca7384b3da038fffbe6e66 Task-number: QTBUG-46821 Reviewed-by: Topi Reiniö --- src/tools/qdoc/codeparser.cpp | 9 +++++++-- src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc | 1 + src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc | 2 -- src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc | 23 +++++++++++++++++++++++ src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc | 6 ++++++ src/tools/qdoc/htmlgenerator.cpp | 10 ++++++---- src/tools/qdoc/node.h | 7 ++++++- src/tools/qdoc/qmlcodeparser.cpp | 4 +++- src/tools/qdoc/qmlvisitor.cpp | 1 + 9 files changed, 53 insertions(+), 10 deletions(-) diff --git a/src/tools/qdoc/codeparser.cpp b/src/tools/qdoc/codeparser.cpp index 4f80ec80d9..92a0d52129 100644 --- a/src/tools/qdoc/codeparser.cpp +++ b/src/tools/qdoc/codeparser.cpp @@ -65,6 +65,7 @@ QT_BEGIN_NAMESPACE #define COMMAND_THREADSAFE Doc::alias(QLatin1String("threadsafe")) #define COMMAND_TITLE Doc::alias(QLatin1String("title")) #define COMMAND_WRAPPER Doc::alias(QLatin1String("wrapper")) +#define COMMAND_NOAUTOLIST Doc::alias(QLatin1String("noautolist")) QList CodeParser::parsers; bool CodeParser::showInternal_ = false; @@ -219,8 +220,9 @@ const QSet& CodeParser::commonMetaCommands() << COMMAND_THREADSAFE << COMMAND_TITLE << COMMAND_WRAPPER - << COMMAND_INJSMODULE; - } + << COMMAND_INJSMODULE + << COMMAND_NOAUTOLIST; + } return commonMetaCommands_; } @@ -317,6 +319,9 @@ void CodeParser::processCommonMetaCommand(const Location& location, location.warning(tr("Command '\\%1' is only meanigfule in '\\module' and '\\qmlmodule'.") .arg(COMMAND_QTVARIABLE)); } + else if (command == COMMAND_NOAUTOLIST) { + node->setNoAutoList(true); + } } /*! diff --git a/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc b/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc index 63fcee6469..d3f188c265 100644 --- a/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc +++ b/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc @@ -89,6 +89,7 @@ \li \l {namespace-command} {\\namespace} \li \l {nextpage-command} {\\nextpage} \li \l {newcode-command} {\\newcode} + \li \l {noautolist-command} {\\noautolist} \li \l {nonreentrant-command} {\\nonreentrant} \li \l {note-command} {\\note} \li \l {li-command} {\\o} \span {class="newStuff"} {(deprecated, use \\li)} diff --git a/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc index 3bf63214ad..50e85676f8 100644 --- a/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc +++ b/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc @@ -700,8 +700,6 @@ \l{threadsafe-command} {\\threadsafe}. */ - / *! - /*! \page 18-qdoc-commands-relating.html \previouspage Thread Support diff --git a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc index fc576157f7..01eee0486c 100644 --- a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc +++ b/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc @@ -67,6 +67,7 @@ \li \l {li-command} {\\li} \span {class="newStuff"} \li \l {list-command} {\\list} \li \l {meta-command} {\\meta} + \li \l {noautolist-command} {\\noautolist} \li \l {newcode-command} {\\newcode} \li \l {li-command} {\\o} \span {class="newStuff"} {(deprecated, use \\li)} \li \l {note-command} {\\note} @@ -3881,6 +3882,28 @@ values obtained from the QDoc configuration file. See \l {Generating DITA XML Output} for details. + \target noautolist-command + \section1 \\noautolist + + The \\noautolist command indicates that the annotated list of C++ + classes or QML types, which is automatically generated at the + bottom of the C++ or QML module page should be omitted, because + the classes or types have been listed manually. This command can + also be used with the \l {group-command}{\\group} command to omit + the list of group members, when they are listed manually. + + The command must stand on its own line. See \l {Qt Sensors QML Types} for + an example. The page is generated from \c {qtsensors5.qdoc}. There you will + find a qdoc comment containing the \c{\qmlmodule} command for the QtSensors + module. The same qdoc comment contains two \c {\annotated-list} commands to + list the QML types in two separate groups. The QML types have been divided + into these two groups because it makes more sense to list them this way than + it does to list them in a single alphabetical list. At the bottom of the + comment, \c {\noautolist} has been used to tell qdoc not to generate the + automatic annotated list. + + This command was introduced in QDoc 5.6. + \target omit-command \section1 \\omit diff --git a/src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc index f5351b851c..306fc40cb8 100644 --- a/src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc +++ b/src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc @@ -851,6 +851,9 @@ \endquotation + The \l {noautolist-command} {\\noautolist} command can be used here + to omit the automatically generated list of classes at the end. + See also \l {inmodule-command} {\\inmodule} \target namespace-command @@ -1372,6 +1375,9 @@ The \l{componentset}{UIComponents} example demonstrates proper usage of QDoc commands to document QML types and QML modules. + The \l {noautolist-command} {\\noautolist} command can be used here + to omit the automatically generated list of types at the end. + \target instantiates-command \section1 \\instantiates diff --git a/src/tools/qdoc/htmlgenerator.cpp b/src/tools/qdoc/htmlgenerator.cpp index 6b92ea12a4..f9fc534c70 100644 --- a/src/tools/qdoc/htmlgenerator.cpp +++ b/src/tools/qdoc/htmlgenerator.cpp @@ -1796,10 +1796,12 @@ void HtmlGenerator::generateCollectionNode(CollectionNode* cn, CodeMarker* marke generateAlsoList(cn, marker); generateExtractionMark(cn, EndMark); - if (cn->isGroup()) - generateAnnotatedList(cn, marker, cn->members()); - else if (cn->isQmlModule() || cn->isJsModule()) - generateAnnotatedList(cn, marker, cn->members()); + if (!cn->noAutoList()) { + if (cn->isGroup()) + generateAnnotatedList(cn, marker, cn->members()); + else if (cn->isQmlModule() || cn->isJsModule()) + generateAnnotatedList(cn, marker, cn->members()); + } sections = marker->sections(cn, CodeMarker::Detailed, CodeMarker::Okay); s = sections.constBegin(); diff --git a/src/tools/qdoc/node.h b/src/tools/qdoc/node.h index f852e480a6..27edfd1156 100644 --- a/src/tools/qdoc/node.h +++ b/src/tools/qdoc/node.h @@ -255,6 +255,7 @@ public: virtual QString element() const { return QString(); } virtual Tree* tree() const; virtual void findChildren(const QString& , NodeList& nodes) const { nodes.clear(); } + virtual void setNoAutoList(bool ) { } bool isIndexNode() const { return indexNodeFlag_; } NodeType type() const { return (NodeType) nodeType_; } virtual DocSubtype docSubtype() const { return NoSubtype; } @@ -1096,7 +1097,8 @@ class CollectionNode : public Aggregate CollectionNode(NodeType type, Aggregate* parent, const QString& name, - Genus genus) : Aggregate(type, parent, name), seen_(false) + Genus genus) + : Aggregate(type, parent, name), seen_(false), noAutoList_(false) { setPageType(Node::OverviewPage); setGenus(genus); @@ -1139,9 +1141,12 @@ class CollectionNode : public Aggregate void markSeen() { seen_ = true; } void markNotSeen() { seen_ = false; } + bool noAutoList() const { return noAutoList_; } + virtual void setNoAutoList(bool b) Q_DECL_OVERRIDE { noAutoList_ = b; } private: bool seen_; + bool noAutoList_; QString title_; QString subtitle_; NodeList members_; diff --git a/src/tools/qdoc/qmlcodeparser.cpp b/src/tools/qdoc/qmlcodeparser.cpp index f485255b8e..bcc0fedc9a 100644 --- a/src/tools/qdoc/qmlcodeparser.cpp +++ b/src/tools/qdoc/qmlcodeparser.cpp @@ -56,6 +56,7 @@ QT_BEGIN_NAMESPACE #define COMMAND_PRELIMINARY Doc::alias("preliminary") #define COMMAND_SINCE Doc::alias("since") #define COMMAND_WRAPPER Doc::alias("wrapper") +#define COMMAND_NOAUTOLIST Doc::alias("noautolist") #define COMMAND_ABSTRACT Doc::alias("abstract") #define COMMAND_QMLABSTRACT Doc::alias("qmlabstract") @@ -256,7 +257,8 @@ const QSet& QmlCodeParser::otherMetaCommands() << COMMAND_QMLABSTRACT << COMMAND_INQMLMODULE << COMMAND_INJSMODULE - << COMMAND_WRAPPER; + << COMMAND_WRAPPER + << COMMAND_NOAUTOLIST; } return otherMetaCommands_; } diff --git a/src/tools/qdoc/qmlvisitor.cpp b/src/tools/qdoc/qmlvisitor.cpp index d2aa1595ef..6f63624bf0 100644 --- a/src/tools/qdoc/qmlvisitor.cpp +++ b/src/tools/qdoc/qmlvisitor.cpp @@ -54,6 +54,7 @@ QT_BEGIN_NAMESPACE #define COMMAND_PRELIMINARY Doc::alias(QLatin1String("preliminary")) #define COMMAND_SINCE Doc::alias(QLatin1String("since")) #define COMMAND_WRAPPER Doc::alias(QLatin1String("wrapper")) +#define COMMAND_NOAUTOLIST Doc::alias(QLatin1String("noautolist")) #define COMMAND_ABSTRACT Doc::alias(QLatin1String("abstract")) #define COMMAND_QMLABSTRACT Doc::alias(QLatin1String("qmlabstract")) -- cgit v1.2.3