qdoc: Add the noautolist command to qdoc

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ö <topi.reinio@digia.com>

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 *> CodeParser::parsers;
 bool CodeParser::showInternal_ = false;
@@ -219,8 +220,9 @@ const QSet<QString>& 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<QString>& 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"))