qdoc: Ensure a group is listed as part of the navigation bar

QDoc adds a link to a documented \group as part of the navigation bar
if a page uses an \ingroup command. However, this happened only if
there was exactly one \ingroup command used.

Pages can belong to multiple groups. Often, the \ingroup command is
used for grouping pages for use with \generatelist or \annotatedlist
commands, without any associated \group page.

Adjust the logic for resolving the group page link on the navigation
bar; select the first one that references a documented (and titled)
\group.

Document the automated link generation for \ingroup, and touch up
the related documentation.

Fixes: QTBUG-116441
Change-Id: Ie773ac4f52733ca2a9ade04c96101e05ef05c0cb
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 2b2ac8e4aacadb4461697600f95b33815b519bef)
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

6 files changed, 57 insertions, 69 deletions

diff --git a/src/qdoc/doc/qdoc-manual-contextcmds.qdoc b/src/qdoc/doc/qdoc-manual-contextcmds.qdoc
index 821c6b0fa..c21e26d93 100644
--- a/src/qdoc/doc/qdoc-manual-contextcmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-contextcmds.qdoc
@@ -924,10 +924,10 @@
     \section2 \\ingroup
 
     The \\ingroup command indicates that the given
-    overview or documented class belongs to a certain group of
+    class, page, or other entity belongs to a certain group of
     related documentation.
 
-    A class or overview may belong to many groups.
+    An entity may belong to multiple groups.
 
     The \\ingroup command's argument is a group name, but note
     that the command considers the rest of the line as part of
@@ -945,13 +945,36 @@
     \1/
     \endcode
 
-    This will include the QDir class in the \c io group, which means,
-    for example, that QDir will appear on the list created by calling
-    the \l {group-command} {\\group} command with the \c io argument.
+    This adds the QDir class to the \c io group. An entry for QDir
+    will then appear on the list created with, for example,
+    the \l {annotatedlist-command} {\\annotatedlist} command with
+    an argument \c io.
 
-    To list overviews that are related to a certain group, you must
-    generate the list explicitly using the \l {generatelist-command}
-    {\\generatelist} command with the \c related argument.
+    QDoc automatically generates links to associated groups on a
+    C++ class, namespace, or header reference page. For example,
+    given the above documentation for class \QDir and the following
+    \l {group-command}{\\group} page:
+
+    \badcode *
+    /\1
+        \group io
+        \title Input/Output and Networking
+        ...
+    \1/
+    \endcode
+
+    QDoc then outputs a statement on the QDir reference page:
+
+    \quotation
+    \list
+        \li \QDir is part of \l {Input/Output and Networking}.
+    \endlist
+    \endquotation
+
+    For HTML output, QDoc also generates a link to the group
+    page as part of the navigation bar (breadcrumbs). If multiple
+    \\ingroup commands are used, the first one that references
+    a documented \\group is selected.
 
     See also \l {group-command} {\\group}.
 
diff --git a/src/qdoc/doc/qdoc-manual-topiccmds.qdoc b/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
index 8b043f55d..3e747a7fb 100644
--- a/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
@@ -581,8 +581,9 @@
     \target group-command
     \section1 \\group
 
-    The \\group command creates a separate page that lists the classes
-    belonging to the group. The argument is the group name.
+    The \\group command creates a separate page that lists the classes,
+    pages, or other entities belonging to a named group. The argument
+    is the group name.
 
     A class is included in a group by using the \l {ingroup-command}
     {\\ingroup} command. Overview pages can also be related to a group
@@ -595,64 +596,20 @@
     HTML page for the group is written to an \c {.html} file named
     <lower-case-group-name>.html.
 
-    Each class name is listed as a link to the class reference page
-    followed by the text from the class's \l {brief-command} {\\brief}
-    texts.
+    Each entity in the group is listed as a link (using page title
+    or class name), followed by a decription from the \l {brief-command}
+    {\\brief} command in the entity's documentation.
 
     \badcode *
     /\1!
         \group io
-
         \title Input/Output and Networking
-
-        These classes are used to handle input and output to
-        and from external devices, processes, files etc., as
-        well as manipulating files and directories.
     \1/
     \endcode
 
-    QDoc generates a group page in \c{io.html} that will look
-    like this:
-
-    \quotation
-         \raw HTML
-
-         <h1>Input/Output and Networking</h1>
-
-         <p>These classes are used to handle input and output
-         to and from external devices, processes, files etc., as
-         well as manipulating files and directories.</p>
-
-         <p>
-         <table width="100%">
-             <tr valign="top" bgcolor="#e0e0e0">
-             <td><b>
-             <a href="http://doc.qt.io/qt-5/qabstractsocket.html">QAbstractSocket</a>
-             </b></td>
-             <td>
-             The base functionality common to all socket types
-             </td></tr>
-
-             <tr valign="top" bgcolor="#e0e0e0">
-             <td><b>
-             <a href="http://doc.qt.io/qt-5/qbuffer.html">QBuffer</a>
-             </b></td>
-             <td>
-             QIODevice interface for a QByteArray
-             </td></tr>
-
-             <tr valign="top" bgcolor="#e0e0e0">
-             <td><b>
-             <a href="http://doc.qt.io/qt-5/qclipboard.html">QClipboard</a>
-             </b></td>
-             <td>
-             Access to the window system clipboard
-             </td></tr>
-         </table>
-         \endraw
-    \endquotation
+    QDoc generates a group page \c{io.html}.
 
-    Note that overview pages related to the group, must be listed
+    Note that overview pages related to the group must be listed
     explicitly using the \l {generatelist-command} {\\generatelist}
     command with the \c related argument.
 
@@ -670,8 +627,9 @@
     \1/
     \endcode
 
-    See also \l {ingroup-command} {\\ingroup} and \l
-    {generatelist-command} {\\generatelist}.
+    See also \l {ingroup-command} {\\ingroup}, \l {annotatedlist-command}
+    {\\annotatedlist}, \l {generatelist-command} {\\generatelist}, and
+    \l {noautolist-command}{\\noautolist}.
 
     \target headerfile-command
     \section1 \\headerfile
diff --git a/src/qdoc/htmlgenerator.cpp b/src/qdoc/htmlgenerator.cpp
index 050f6c795..b8b413abd 100644
--- a/src/qdoc/htmlgenerator.cpp
+++ b/src/qdoc/htmlgenerator.cpp
@@ -1663,14 +1663,16 @@ void HtmlGenerator::generateNavigationBar(const QString &title, const Node *node
                     navNodes.push_front(currentNode->navigationParent());
                 currentNode = currentNode->navigationParent();
             }
-            // If no nav. parent was found but the page is in a single group, use that
+            // If no nav. parent was found but the page is a \group member, add a link to the
+            // (first) group page.
             if (navNodes.empty()) {
-                QStringList groups = static_cast<const PageNode *>(node)->groupNames();
-                if (groups.size() == 1) {
-                    const Node *groupNode =
-                            m_qdb->findNodeByNameAndType(QStringList(groups[0]), &Node::isGroup);
-                    if (groupNode && !groupNode->title().isEmpty())
+                const QStringList groups = static_cast<const PageNode *>(node)->groupNames();
+                for (const auto &groupName : groups) {
+                    const auto *groupNode = m_qdb->findNodeByNameAndType(QStringList{groupName}, &Node::isGroup);
+                    if (groupNode && !groupNode->title().isEmpty()) {
                         navNodes.push_front(groupNode);
+                        break;
+                    }
                 }
             }
             while (!navNodes.empty()) {
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/headerfile-docbook/testheader.xml b/tests/auto/qdoc/generatedoutput/expected_output/headerfile-docbook/testheader.xml
index bfedd98d6..a31b27bf3 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/headerfile-docbook/testheader.xml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/headerfile-docbook/testheader.xml
@@ -18,7 +18,7 @@
 <db:varlistentry>
 <db:term>Group</db:term>
 <db:listitem>
-<db:para><db:para>&lt;TestHeader&gt; is part of <db:simplelist><db:member><db:link xlink:href="headers.xml">Headers</db:link></db:member></db:simplelist></db:para>
+<db:para><db:para>&lt;TestHeader&gt; is part of <db:simplelist><db:member><db:link xlink:href="headers.xml">Headers</db:link></db:member><db:member><db:link xlink:href="tests.xml">Tests</db:link></db:member></db:simplelist></db:para>
 </db:para>
 </db:listitem>
 </db:varlistentry>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/headerfile/testheader.html b/tests/auto/qdoc/generatedoutput/expected_output/headerfile/testheader.html
index ebc565d99..9952a0fb3 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/headerfile/testheader.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/headerfile/testheader.html
@@ -22,7 +22,7 @@
 <tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include &lt;TestHeader&gt;</span></td></tr>
 </table></div>
 <ul>
-<li><TestHeader> is part of <a href="headers.html">Headers</a>.</li>
+<li><TestHeader> is part of <a href="headers.html">Headers</a> and <a href="tests.html">Tests</a>.</li>
 </ul>
 <h2 id="types">Types</h2>
 <div class="table"><table class="alignedsummary" translate="no">
diff --git a/tests/auto/qdoc/generatedoutput/testdata/headerfile/testheader.cpp b/tests/auto/qdoc/generatedoutput/testdata/headerfile/testheader.cpp
index f86a1582e..6f3939345 100644
--- a/tests/auto/qdoc/generatedoutput/testdata/headerfile/testheader.cpp
+++ b/tests/auto/qdoc/generatedoutput/testdata/headerfile/testheader.cpp
@@ -9,6 +9,7 @@
     \inmodule TestCPP
     \brief A header file.
     \ingroup headers
+    \ingroup tests
 */
 
 /*!
@@ -16,6 +17,10 @@
     \title Headers
 */
 
+/*! \group tests
+    \title Tests
+*/
+
 /*!
     \fn void globalFunc()
     \brief Global function.