qdoc: Fix double entries for shared comment node in detailed description

If multiple API functions are documented directly under a namespace and
the functions share a QDoc comment block, duplicate entries for them
were generated in the detailed description - once with the correct
documentation, and a second time with empty docs.

This happened because Sections::stdRefPageSwitch() was indiscriminantly
called for both `Summary` and `Details` sections, and that function did
not check whether the node being distributed is sharing a comment (for
`Details`).

Extract the recurring piece of code that tests for shared comment nodes
as a static helper method, and use it in all call sites doing node
distribution to various sections. This makes the output for namespace
reference pages more uniform with ones for classes and QML types.

Add a validatedqdocoutputfiles test case with expected output.

Pick-to: 6.8
Fixes: QTBUG-120186
Change-Id: If9f2d4c006c19958a4948cd3dfd395d215b6c97f
Reviewed-by: Paul Wicking <[email protected]>

Author: toreinio

src/qdoc/qdoc/src/qdoc/sections.cpp

@@ -517,16 +517,30 @@ void Sections::reduce(QList<Section> &v)
         section.reduce();
 }
 
+/*!
+  \internal
+
+  Returns the node to test when distributing \a node based on
+  Node::nodeType().
+
+  It returns either \a node itself, or if \a node is a shared comment
+  node, the first node in its collective.
+*/
+static Node *nodeToTestForDistribution(Node *node)
+{
+    if (node && node->isSharedCommentNode() && node->hasDoc()) {
+        if (auto *scn = static_cast<SharedCommentNode *>(node); scn->collective().size())
+            return scn->collective().first(); // TODO: warn about mixed node types in collective?
+    }
+    return node;
+}
+
 /*!
   This is a private helper function for buildStdRefPageSections().
  */
-void Sections::stdRefPageSwitch(SectionVector &v, Node *n, Node *t)
+void Sections::stdRefPageSwitch(SectionVector &v, Node *n)
 {
-    // t is the reference node to be tested, n is the node to be distributed.
-    // t differs from n only for shared comment nodes.
-    if (!t)
-        t = n;
-
+    auto *t = nodeToTestForDistribution(n);
     switch (t->nodeType()) {
     case Node::Namespace:
         v[StdNamespaces].insert(n);
@@ -559,14 +573,6 @@ void Sections::stdRefPageSwitch(SectionVector &v, Node *n, Node *t)
         }
     }
         return;
-    case Node::SharedComment: {
-        auto *scn = static_cast<SharedCommentNode *>(t);
-        if (!scn->doc().isEmpty() && scn->collective().size())
-            stdRefPageSwitch(
-                    v, scn,
-                    scn->collective().first()); // TODO: warn about mixed node types in collective?
-    }
-        return;
     default:
         return;
     }
@@ -601,7 +607,8 @@ void Sections::buildStdRefPageSections()
         Node *n = *it;
         if (documentAll || n->hasDoc()) {
             stdRefPageSwitch(stdSummarySections(), n);
-            stdRefPageSwitch(stdDetailsSections(), n);
+            if (!n->isSharingComment())
+                stdRefPageSwitch(stdDetailsSections(), n);
         }
     }
     if (!m_aggregate->relatedByProxy().isEmpty()) {
@@ -720,16 +727,7 @@ void Sections::distributeNodeInDetailsVector(SectionVector &dv, Node *n)
     if (n->isSharingComment())
         return;
 
-    // t is the reference node to be tested - typically it's this node (n), but for
-    // shared comment nodes we need to distribute based on the nodes in its collective.
-    Node *t = n;
-
-    if (n->isSharedCommentNode() && n->hasDoc()) {
-        auto *scn = static_cast<SharedCommentNode *>(n);
-        if (scn->collective().size())
-            t = scn->collective().first(); // TODO: warn about mixed node types in collective?
-    }
-
+    auto *t = nodeToTestForDistribution(n);
     if (t->isFunction()) {
         auto *fn = static_cast<FunctionNode *>(t);
         if (fn->isRelatedNonmember()) {
@@ -765,18 +763,10 @@ void Sections::distributeQmlNodeInDetailsVector(SectionVector &dv, Node *n)
     if (n->isSharingComment())
         return;
 
-    // t is the reference node to be tested - typically it's this node (n), but for
-    // shared comment nodes we need to distribute based on the nodes in its collective.
-    Node *t = n;
-
-    if (n->isSharedCommentNode() && n->hasDoc()) {
-        if (n->isPropertyGroup()) {
-            dv[QmlProperties].insert(n);
-            return;
-        }
-        auto *scn = static_cast<SharedCommentNode *>(n);
-        if (scn->collective().size())
-            t = scn->collective().first(); // TODO: warn about mixed node types in collective?
+    auto *t = nodeToTestForDistribution(n);
+    if (t != n && n->isPropertyGroup()) {
+        dv[QmlProperties].insert(n);
+        return;
     }
 
     if (t->isQmlProperty()) {

src/qdoc/qdoc/src/qdoc/sections.h

@@ -181,7 +181,7 @@ class Sections
     [[nodiscard]] Aggregate *aggregate() const { return m_aggregate; }
 
 private:
-    void stdRefPageSwitch(SectionVector &v, Node *n, Node *t = nullptr);
+    void stdRefPageSwitch(SectionVector &v, Node *n);
     void distributeNodeInSummaryVector(SectionVector &sv, Node *n);
     void distributeNodeInDetailsVector(SectionVector &dv, Node *n);
     void distributeQmlNodeInDetailsVector(SectionVector &dv, Node *n);

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/sharedcommentsinnamespace/expected/mod-module.html

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+<!-- test.cpp -->
+  <title>SharedCommentsInNamespace</title>
+</head>
+<body>
+<div class="sidebar">
+<div class="toc">
+<h3 id="toc">Contents</h3>
+<ul>
+<li class="level1"><a href="#details">Detailed Description</a></li>
+</ul>
+</div>
+<div class="sidebar-content" id="sidebar-content"></div></div>
+<h2 id="namespaces">Namespaces</h2>
+<div class="table"><table class="annotated">
+<tr class="odd topAlign"><td class="tblName" translate="no"><p><a href="test.html">Test</a></p></td></tr>
+</table></div>
+<!-- $$$Mod-description -->
+<div class="descr" id="details">
+</div>
+<!-- @@@Mod -->
+</body>
+</html>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/sharedcommentsinnamespace/expected/sharedcommentsinnamespace.index

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE QDOCINDEX>
+<INDEX url="" title="SharedCommentsInNamespace Reference Documentation" version="" project="SharedCommentsInNamespace">
+    <namespace name="" status="active" access="public" module="sharedcommentsinnamespace">
+        <namespace name="Test" href="test.html" status="active" access="public" location="test.h" documented="true" module="Mod">
+            <function name="bar" fullname="Test::bar" href="test.html#bar" status="active" access="public" location="test.h" documented="true" meta="plain" type="void" signature="void bar()"/>
+            <function name="foo" fullname="Test::foo" href="test.html#foo" status="active" access="public" location="test.h" documented="true" meta="plain" type="void" signature="void foo()"/>
+        </namespace>
+        <module name="Mod" href="mod-module.html" status="active" documented="true" seen="true" title=""/>
+    </namespace>
+</INDEX>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/sharedcommentsinnamespace/expected/test.html

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+<!-- test.cpp -->
+  <title>Test Namespace | SharedCommentsInNamespace</title>
+</head>
+<body>
+<div class="sidebar">
+<div class="toc">
+<h3 id="toc">Contents</h3>
+<ul>
+<li class="level1"><a href="#functions">Functions</a></li>
+<li class="level1"><a href="#details">Detailed Description</a></li>
+</ul>
+</div>
+<div class="sidebar-content" id="sidebar-content"></div></div>
+<h1 class="title" translate="no">Test Namespace</h1>
+<div class="table"><table class="alignedsummary requisites" translate="no">
+<tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <code translate="no">#include &lt;Test&gt;</code></td></tr>
+</table></div>
+<h2 id="functions">Functions</h2>
+<div class="table"><table class="alignedsummary" translate="no">
+<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b></b></td></tr>
+<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="test.html#bar" translate="no">bar</a></b>()</td></tr>
+<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="test.html#foo" translate="no">foo</a></b>()</td></tr>
+</table></div>
+<!-- $$$Test-description -->
+<div class="descr">
+<h2 id="details">Detailed Description</h2>
+</div>
+<!-- @@@Test -->
+<div class="func">
+<h2>Function Documentation</h2>
+<!-- $$$ -->
+<div class="fngroup">
+<h3 class="fn fngroupitem" translate="no" id="bar"><span class="type">void</span> Test::<span class="name">bar</span>()</h3><h3 class="fn fngroupitem" translate="no" id="foo"><span class="type">void</span> Test::<span class="name">foo</span>()</h3></div>
+<p>Two functions sharing a doc comment.</p>
+<!-- @@@ -->
+</div>
+</body>
+</html>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/sharedcommentsinnamespace/sharedcommentsinnamespace.qdocconf

@@ -0,0 +1,7 @@
+project = SharedCommentsInNamespace
+
+{sourcedirs,headerdirs} = ./src
+
+locationinfo         = false
+warninglimit         = 0
+warninglimit.enabled = true

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/sharedcommentsinnamespace/src/test.cpp

@@ -0,0 +1,17 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0
+
+#include "test.h"
+
+/*! \module Mod */
+/*! \namespace Test
+    \inmodule Mod
+*/
+namespace Test {
+/*!
+    \fn void foo()
+    \fn void bar()
+
+    Two functions sharing a doc comment.
+*/
+}

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/sharedcommentsinnamespace/src/test.h

@@ -0,0 +1,8 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0
+#pragma once
+
+namespace Test {
+    void foo(){}
+    void bar(){}
+}