qdoc: Improve example file listing

At the end of \example documentation page, qdoc lists all the files
that are part of the example project. This commit does the
following improvements:

  - Sort the example files based on path name
  - Introduce '\generatelist examplefiles [regexp]', which
    lists the files (optionally, only those that match regexp)
    at the specified location.
  - Enable \noautolist for example pages, to skip generating the
    the file list at the end.

Change-Id: Ic9ae70f9f7de166d314ae489a7bab9a935949fc3
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

6 files changed, 76 insertions, 14 deletions

diff --git a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
index 24dc7158a..4e4641ecb 100644
--- a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
@@ -3544,6 +3544,30 @@
     A support class is identified in the \\class comment with the \l
     {compat-command} {\\compat} command.
 
+    \section2 \c {examplefiles [regular_expression]}
+
+    The \c examplefiles argument lists the files that are part of
+    an example project. The optional second argument is a regular
+    expression; if provided, only the files whose path matches with
+    the regular expression are listed.
+
+    The \c examplefiles argument can be only used within example
+    documentation (see \l {example-command}{\\example}), and is
+    typically used together with the \l {noautolist-command}{\\noautolist}
+    command.
+
+    \section2 \c {exampleimages [regular_expression]}
+
+    The \c exampleimages argument lists the images that are part of
+    an example project. The optional second argument is a regular
+    expression; if provided, only the image files whose path matches
+    with the regular expression are listed.
+
+    The \c exampleimages argument can be only used within example
+    documentation (see \l {example-command}{\\example}), and is
+    typically used together with the \l {noautolist-command}{\\noautolist}
+    command.
+
     \section2 \c functionindex
 
     The \c functionindex argument provides a complete alphabetical
@@ -3953,6 +3977,10 @@
 
     This command was introduced in QDoc 5.6.
 
+    Since Qt 5.10, this command can be applied also to \l{example-command}
+    {\\example} documentation, where it causes the automatically generated
+    list of files and images belonging to an example project to be omitted.
+
     \target omit-command
     \section1 \\omit
 
diff --git a/src/qdoc/generator.cpp b/src/qdoc/generator.cpp
index eaf1a6133..338f8a9ce 100644
--- a/src/qdoc/generator.cpp
+++ b/src/qdoc/generator.cpp
@@ -960,7 +960,7 @@ void Generator::generateBody(const Node *node, CodeMarker *marker)
 
     if (node->isDocumentNode()) {
         const DocumentNode *dn = static_cast<const DocumentNode *>(node);
-        if (dn->isExample()) {
+        if (dn->isExample() && !dn->noAutoList()) {
             generateExampleFiles(dn, marker);
         }
         else if (dn->docSubtype() == Node::File) {
@@ -983,8 +983,8 @@ void Generator::generateExampleFiles(const DocumentNode *dn, CodeMarker *marker)
 {
     if (dn->childNodes().isEmpty())
         return;
-    generateFileList(dn, marker, Node::File, QString("Files:"));
-    generateFileList(dn, marker, Node::Image, QString("Images:"));
+    generateFileList(dn, marker, Node::File);
+    generateFileList(dn, marker, Node::Image);
 }
 
 void Generator::generateDocumentNode(DocumentNode* /* dn */, CodeMarker* /* marker */)
@@ -1005,16 +1005,39 @@ void Generator::generateCollectionNode(CollectionNode* , CodeMarker* )
 void Generator::generateFileList(const DocumentNode* dn,
                                  CodeMarker* marker,
                                  Node::DocSubtype subtype,
-                                 const QString& tag)
+                                 const QString& regExp)
 {
     int count = 0;
     Text text;
     OpenedList openedList(OpenedList::Bullet);
+    QString tag;
+
+    NodeList children(dn->childNodes());
+    std::sort(children.begin(), children.end(), Generator::compareNodes);
+    if (!regExp.isEmpty()) {
+        QRegExp re(regExp);
+        QMutableListIterator<Node*> i(children);
+        while (i.hasNext()) {
+            if (!re.exactMatch(i.next()->name()))
+                i.remove();
+        }
+    }
+    if (children.size() > 1) {
+        switch (subtype) {
+        default:
+        case Node::File:
+            tag = "Files:";
+            break;
+        case Node::Image:
+            tag = "Images:";
+            break;
+        }
+        text << Atom::ParaLeft << tag << Atom::ParaRight;
+    }
 
-    text << Atom::ParaLeft << tag << Atom::ParaRight
-         << Atom(Atom::ListLeft, openedList.styleString());
+    text << Atom(Atom::ListLeft, openedList.styleString());
 
-    foreach (const Node* child, dn->childNodes()) {
+    foreach (const Node* child, children) {
         if (child->docSubtype() == subtype) {
             ++count;
             QString file = child->name();
diff --git a/src/qdoc/generator.h b/src/qdoc/generator.h
index a3c34eaba..4709ad129 100644
--- a/src/qdoc/generator.h
+++ b/src/qdoc/generator.h
@@ -153,7 +153,7 @@ protected:
     void generateFileList(const DocumentNode* dn,
                           CodeMarker* marker,
                           Node::DocSubtype subtype,
-                          const QString& tag);
+                          const QString& regExp = QString());
     void generateSince(const Node *node, CodeMarker *marker);
     void generateStatus(const Node *node, CodeMarker *marker);
     void generatePrivateSignalNote(const Node* node, CodeMarker* marker);
@@ -230,6 +230,7 @@ private:
     static QmlTypeNode* qmlTypeContext_;
 
     void generateReimplementedFrom(const FunctionNode *func, CodeMarker *marker);
+    static bool compareNodes(Node *a, Node *b) { return (a->name() < b->name()); }
 
  protected:
     const Config* config_;
diff --git a/src/qdoc/htmlgenerator.cpp b/src/qdoc/htmlgenerator.cpp
index be6617501..10199d7df 100644
--- a/src/qdoc/htmlgenerator.cpp
+++ b/src/qdoc/htmlgenerator.cpp
@@ -709,6 +709,16 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
                     generateAnnotatedList(relative, marker, cn->members());
             }
         }
+        else if (atom->string().startsWith("examplefiles") ||
+                 atom->string().startsWith("exampleimages")) {
+            if (relative->isExample()) {
+                Node::DocSubtype subType = (atom->string().mid(7,5) == "image") ? Node::Image : Node::File;
+                generateFileList(static_cast<const DocumentNode*>(relative), marker, subType,
+                                 atom->string().mid(atom->string().indexOf(" ")).trimmed());
+            }
+            else
+                relative->location().warning(QString("'\\generatelist \1' can only be used with '\\example' topic command").arg(atom->string()));
+        }
         else if (atom->string() == QLatin1String("classhierarchy")) {
             generateClassHierarchy(relative, qdb_->getCppClasses());
         }
diff --git a/src/qdoc/node.cpp b/src/qdoc/node.cpp
index 6d83ba631..9919317f2 100644
--- a/src/qdoc/node.cpp
+++ b/src/qdoc/node.cpp
@@ -1213,7 +1213,7 @@ NodeList Aggregate::overloads(const QString &funcName) const
   given \a type and having the given \a parent and \a name.
  */
 Aggregate::Aggregate(NodeType type, Aggregate *parent, const QString& name)
-    : Node(type, parent, name)
+    : Node(type, parent, name), noAutoList_(false)
 {
     switch (type) {
     case Class:
diff --git a/src/qdoc/node.h b/src/qdoc/node.h
index 2de9e2e5b..33cdd3c1a 100644
--- a/src/qdoc/node.h
+++ b/src/qdoc/node.h
@@ -423,7 +423,8 @@ public:
     void setOutputSubdirectory(const QString& t) Q_DECL_OVERRIDE;
     const NodeMap& primaryFunctionMap() { return primaryFunctionMap_; }
     const QMap<QString, NodeList>& secondaryFunctionMap() { return secondaryFunctionMap_; }
-
+    bool noAutoList() const { return noAutoList_; }
+    virtual void setNoAutoList(bool b)  Q_DECL_OVERRIDE { noAutoList_ = b; }
 protected:
     Aggregate(NodeType type, Aggregate* parent, const QString& name);
 
@@ -444,6 +445,7 @@ private:
     NodeMap childMap_;
     NodeMap primaryFunctionMap_;
     QMap<QString, NodeList> secondaryFunctionMap_;
+    bool noAutoList_;
 };
 
 class LeafNode : public Node
@@ -1151,7 +1153,7 @@ class CollectionNode : public Aggregate
                 Aggregate* parent,
                 const QString& name,
                 Genus genus)
-     : Aggregate(type, parent, name), seen_(false), noAutoList_(false)
+     : Aggregate(type, parent, name), seen_(false)
     {
         setPageType(Node::OverviewPage);
         setGenus(genus);
@@ -1194,12 +1196,10 @@ 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_;