qdoc: Fix links in \generatelist <groupname> output

The \generatelist command already supported listing members of a group
as a simple unordered list of titles/links, but the links were broken
as they always referred to the current document.

In DocBook generator, reuse generateAnnotatedList() for this purpose
as it already has support for outputting simple itemized/unordered lists.
Create a new private enum GeneratedListType to select the list 'subtype'
and clean up the API.

Add simple test case and documentation of the new argument.

Fixes: QTBUG-111575
Pick-to: 6.5
Change-Id: I30e4976cef3b6aa5414aac457844ae5bc0762f3d
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

4 files changed, 32 insertions, 21 deletions

diff --git a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
index 67dc123e7..04d9f7cc3 100644
--- a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
@@ -3356,8 +3356,9 @@
     \section1 \\generatelist
 
     The \\generatelist command expands to a list of links to the
-    documentation entities in a group. Below is an example from the Qt
-    Reference Documentation:
+    documentation entities grouped with an \l {ingroup-command}
+    {\\ingroup} command or entities that match one of the arguments
+    listed below. An example from the Qt Reference Documentation:
 
     \badcode *
     /\1!
@@ -3374,6 +3375,11 @@
     This generates the \e {All Classes} page. The command accepts the
     following arguments:
 
+    \section2 \c {<group-name>}
+
+    With a group name as the only argument, QDoc lists all entities that
+    use the \c {\ingroup <group-name>} command.
+
     \target table example
     \section2 \c annotatedclasses
 
diff --git a/src/qdoc/docbookgenerator.cpp b/src/qdoc/docbookgenerator.cpp
index 5f370c954..ceb2fa301 100644
--- a/src/qdoc/docbookgenerator.cpp
+++ b/src/qdoc/docbookgenerator.cpp
@@ -501,7 +501,10 @@ qsizetype DocBookGenerator::generateAtom(const Atom *atom, const Node *relative)
                    || atom->string() == QLatin1String("related")) {
             generateList(relative, atom->string());
             hasGeneratedSomething = true; // Approximation, because there is
-            // some nontrivial logic in generateList.
+                                          // some nontrivial logic in generateList.
+        } else if (const auto *cn = m_qdb->getCollectionNode(atom->string(), Node::Group); cn) {
+            generateAnnotatedList(cn, cn->members(), atom->string(), ItemizedList);
+            hasGeneratedSomething = true; // Approximation
         }
 
         // There must still be some content generated for the DocBook document
@@ -1920,7 +1923,7 @@ void DocBookGenerator::generateList(const Node *relative, const QString &selecto
   A two-column table is output.
  */
 void DocBookGenerator::generateAnnotatedList(const Node *relative, const NodeList &nodeList,
-                                             const QString &selector, bool withSectionIfNeeded)
+                                             const QString &selector, GeneratedListType type)
 {
     if (nodeList.isEmpty())
         return;
@@ -1933,13 +1936,14 @@ void DocBookGenerator::generateAnnotatedList(const Node *relative, const NodeLis
 
     // Detect if there is a need for a variablelist (i.e. titles mapped to
     // descriptions) or a regular itemizedlist (only titles).
-    bool noItemsHaveTitle = std::all_of(nodeList.begin(), nodeList.end(),
-                                        [](const Node* node) {
-                                            return node->doc().briefText().toString().isEmpty();
-                                        });
+    bool noItemsHaveTitle =
+            type == ItemizedList || std::all_of(nodeList.begin(), nodeList.end(),
+                    [](const Node* node) {
+                        return node->doc().briefText().toString().isEmpty();
+                    });
 
     // Wrap the list in a section if needed.
-    if (withSectionIfNeeded && m_hasSection)
+    if (type == AutoSection && m_hasSection)
         startSection("", "Contents");
 
     // From WebXMLGenerator::generateAnnotatedList.
@@ -1986,7 +1990,7 @@ void DocBookGenerator::generateAnnotatedList(const Node *relative, const NodeLis
         newLine();
     }
 
-    if (withSectionIfNeeded && m_hasSection)
+    if (type == AutoSection && m_hasSection)
         endSection();
 }
 
@@ -5259,7 +5263,7 @@ void DocBookGenerator::generateCollectionNode(CollectionNode *cn)
     generateAlsoList(cn);
 
     if (!cn->noAutoList() && (cn->isGroup() || cn->isQmlModule()))
-        generateAnnotatedList(cn, cn->members(), "members", true);
+        generateAnnotatedList(cn, cn->members(), "members", AutoSection);
 
     if (generatedTitle)
         endSection();
diff --git a/src/qdoc/docbookgenerator.h b/src/qdoc/docbookgenerator.h
index dce074c03..dfcbcc62c 100644
--- a/src/qdoc/docbookgenerator.h
+++ b/src/qdoc/docbookgenerator.h
@@ -67,13 +67,16 @@ protected:
     qsizetype generateAtom(const Atom *atom, const Node *relative) override;
 
 private:
+
+    enum GeneratedListType { Auto, AutoSection, ItemizedList };
+
     QXmlStreamWriter *startDocument(const Node *node);
     QXmlStreamWriter *startDocument(const ExampleNode *en, const QString &file);
     QXmlStreamWriter *startGenericDocument(const Node *node, const QString &fileName);
     void endDocument();
 
     void generateAnnotatedList(const Node *relative, const NodeList &nodeList,
-                               const QString &selector, bool withSectionIfNeeded = false);
+                               const QString &selector, GeneratedListType type = Auto);
     void generateAnnotatedLists(const Node *relative, const NodeMultiMap &nmm,
                                 const QString &selector);
     void generateCompactList(const Node *relative, const NodeMultiMap &nmm, bool includeAlphabet,
diff --git a/src/qdoc/htmlgenerator.cpp b/src/qdoc/htmlgenerator.cpp
index 829950615..e3b91955c 100644
--- a/src/qdoc/htmlgenerator.cpp
+++ b/src/qdoc/htmlgenerator.cpp
@@ -2916,10 +2916,9 @@ void HtmlGenerator::generateQmlItem(const Node *node, const Node *relative, Code
 }
 
 /*!
-  This function generates a simple bullet list for the members
-  of collection node \a {cn}. The collection node must be a group
-  and must not be empty. If it is empty, nothing is output, and
-  false is returned. Otherewise, the list is generated and true is returned.
+  This function generates a simple unordered list for the members
+  of collection node \a {cn}. Returns \c true if the list was
+  generated (collection has members), \c false otherwise.
  */
 bool HtmlGenerator::generateGroupList(CollectionNode *cn)
 {
@@ -2927,11 +2926,10 @@ bool HtmlGenerator::generateGroupList(CollectionNode *cn)
     if (cn->members().isEmpty())
         return false;
     out() << "<ul>\n";
-    const auto members = cn->members();
-    for (const auto *node : members) {
-        out() << "<li>"
-              << "<a href=\"#" << Doc::canonicalTitle(node->title()) << "\">" << node->title()
-              << "</a></li>\n";
+    for (const auto *node : cn->members()) {
+        out() << "<li translate=\"no\">";
+        generateFullName(node, nullptr);
+        out() << "</li>\n";
     }
     out() << "</ul>\n";
     return true;