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
Change-Id: I30e4976cef3b6aa5414aac457844ae5bc0762f3d
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 2ba87cd00e6527dbd64f5884f29081bd535605bb)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

8 files changed, 90 insertions, 21 deletions

diff --git a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
index 6cb21ebae..68f533eeb 100644
--- a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
@@ -3357,8 +3357,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!
@@ -3375,6 +3376,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 2a2b9e1bb..902f851b5 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();
 }
 
@@ -5261,7 +5265,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 9bbbb84c5..018b5c36a 100644
--- a/src/qdoc/htmlgenerator.cpp
+++ b/src/qdoc/htmlgenerator.cpp
@@ -2908,10 +2908,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)
 {
@@ -2919,11 +2918,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;
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/cpptypes.html b/tests/auto/qdoc/generatedoutput/expected_output/cpptypes.html
new file mode 100644
index 000000000..633ca939b
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/cpptypes.html
@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+<!-- classlists.qdoc -->
+  <title>Test C++ Types | TestCPP</title>
+</head>
+<body>
+<div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div>
+<h1 class="title">Test C++ Types</h1>
+<!-- $$$cpptypes-description -->
+<div class="descr" id="details">
+<ul>
+<li translate="no"><a href="testqdoc-test.html">TestQDoc::Test</a></li>
+<li translate="no"><a href="testqdoc-test.html#QDOCTEST_MACRO2">TestQDoc::Test::QDOCTEST_MACRO2</a></li>
+<li translate="no"><a href="testqdoc-test.html#someFunctionDefaultArg">TestQDoc::Test::someFunctionDefaultArg()</a></li>
+</ul>
+</div>
+<!-- @@@cpptypes -->
+<div class="table"><table class="annotated">
+<tr class="odd topAlign"><td class="tblName" translate="no"><p><a href="testqdoc-test.html">TestQDoc::Test</a></p></td><td class="tblDescr"><p>A class in a namespace</p></td></tr>
+</table></div>
+</body>
+</html>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbook/cpptypes.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbook/cpptypes.xml
new file mode 100644
index 000000000..9dcabf364
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/docbook/cpptypes.xml
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<db:article xmlns:db="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.2" xml:lang="en">
+<db:info>
+<db:title>Test C++ Types</db:title>
+<db:productname>TestCPP</db:productname>
+<db:titleabbrev>TestCPP Reference Documentation</db:titleabbrev>
+<db:abstract>
+<db:para>TestCPP Reference Documentation.</db:para></db:abstract>
+</db:info>
+<db:anchor xml:id="details"/>
+<db:variablelist role="testgroup">
+<db:listitem>
+<db:para><db:link xlink:href="testqdoc-test.xml" xlink:role="class">TestQDoc::Test</db:link></db:para>
+</db:listitem>
+<db:listitem>
+<db:para><db:link xlink:href="testqdoc-test.xml#QDOCTEST_MACRO2" xlink:role="function">TestQDoc::Test::QDOCTEST_MACRO2</db:link></db:para>
+</db:listitem>
+<db:listitem>
+<db:para><db:link xlink:href="testqdoc-test.xml#someFunctionDefaultArg" xlink:role="function">TestQDoc::Test::someFunctionDefaultArg()</db:link></db:para>
+</db:listitem>
+</db:variablelist>
+<db:variablelist role="members">
+<db:varlistentry>
+<db:term><db:link xlink:href="testqdoc-test.xml" xlink:role="class">TestQDoc::Test</db:link></db:term>
+<db:listitem>
+<db:para>A class in a namespace.</db:para>
+</db:listitem>
+</db:varlistentry>
+</db:variablelist>
+</db:article>
diff --git a/tests/auto/qdoc/generatedoutput/testdata/testcpp/classlists.qdoc b/tests/auto/qdoc/generatedoutput/testdata/testcpp/classlists.qdoc
index 0a40e9b3e..8f6e9b6b7 100644
--- a/tests/auto/qdoc/generatedoutput/testdata/testcpp/classlists.qdoc
+++ b/tests/auto/qdoc/generatedoutput/testdata/testcpp/classlists.qdoc
@@ -38,4 +38,6 @@
 /*!
     \group cpptypes
     \title Test C++ Types
+
+    \generatelist testgroup
 */
diff --git a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
index 041b90cb1..195cf78ea 100644
--- a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
+++ b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
@@ -222,6 +222,7 @@ void tst_generatedOutput::htmlFromCpp()
                    "testqdoc-testderived-obsolete.html "
                    "obsolete-classes.html "
                    "autolinking.html "
+                   "cpptypes.html "
                    "testqdoc.html");
 }
 
@@ -315,6 +316,7 @@ void tst_generatedOutput::docBookFromCpp()
                    "docbook/testcpp-module.xml "
                    "docbook/testqdoc-test.xml "
                    "docbook/testqdoc-testderived.xml "
+                   "docbook/cpptypes.xml "
                    "docbook/testqdoc.xml");
 }