qdoc: Fix links for access functions associated with multiple properties

FunctionNode::hasOneAssociatedProperty() was used for resolving where to
link to for undocumented property access functions. If a function is
undocumented, it should link to the property where QDoc auto-generates
the list of access functions.

This broke down if there are multiple properties associated with, for
example, an undocumented notifier signal. There, QDoc gave up and just
generated a non-existent anchor for the signal, resulting in broken
intra-page links.

To fix, replace hasOneAssociatedProperty() with a function that returns
a `primary` associated property to get consistent linking. A property is
considered a primary for an access function if the function name appears
at the start of the property name.

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

Author: toreinio

src/qdoc/qdoc/src/qdoc/functionnode.cpp

@@ -319,6 +319,33 @@ void FunctionNode::addAssociatedProperty(PropertyNode *p)
     m_associatedProperties.append(p);
 }
 
+/*!
+  Returns the \e primary associated property, if this is an
+  access function for one or more properties.
+
+  An associated property is considered a primary if this
+  function's name starts with the property name. If there's
+  no such property, return the first one available as a
+  fallback.
+
+  If no associated properties exist, returns \nullptr.
+ */
+const PropertyNode *FunctionNode::primaryAssociatedProperty() const
+{
+    if (m_associatedProperties.isEmpty())
+        return nullptr;
+    if (m_associatedProperties.size() == 1)
+        return m_associatedProperties[0];
+
+    auto it = std::find_if(
+            m_associatedProperties.cbegin(), m_associatedProperties.cend(),
+                    [this](const PropertyNode *p) {
+                        return name().startsWith(p->name());
+                    });
+
+    return it != m_associatedProperties.cend() ? *it : m_associatedProperties[0];
+}
+
 /*!
     \reimp
 

src/qdoc/qdoc/src/qdoc/functionnode.h

@@ -119,10 +119,7 @@ class FunctionNode : public Node
     [[nodiscard]] const QString &overridesThis() const { return m_overridesThis; }
     [[nodiscard]] const QList<PropertyNode *> &associatedProperties() const { return m_associatedProperties; }
     [[nodiscard]] bool hasAssociatedProperties() const { return !m_associatedProperties.isEmpty(); }
-    [[nodiscard]] bool hasOneAssociatedProperty() const
-    {
-        return (m_associatedProperties.size() == 1);
-    }
+    [[nodiscard]] const PropertyNode *primaryAssociatedProperty() const;
     [[nodiscard]] QString element() const override { return parent()->name(); }
     [[nodiscard]] bool isAttached() const override { return m_attached; }
     [[nodiscard]] QString qmlTypeName() const override { return parent()->qmlTypeName(); }

src/qdoc/qdoc/src/qdoc/generator.cpp

@@ -495,8 +495,8 @@ QString Generator::fullDocumentLocation(const Node *node)
         default:
             if (fn->isDtor())
                 anchorRef = "#dtor." + fn->name().mid(1);
-            else if (fn->hasOneAssociatedProperty() && fn->doc().isEmpty())
-                return fullDocumentLocation(fn->associatedProperties()[0]);
+            else if (const auto *p = fn->primaryAssociatedProperty(); p && fn->doc().isEmpty())
+                return fullDocumentLocation(p);
             else if (fn->overloadNumber() > 0)
                 anchorRef = QLatin1Char('#') + cleanRef(fn->name()) + QLatin1Char('-')
                         + QString::number(fn->overloadNumber());

src/qdoc/qdoc/src/qdoc/xmlgenerator.cpp

@@ -280,8 +280,8 @@ QString XmlGenerator::refForNode(const Node *node)
                 ref += QLatin1Char('-') + QString::number(fn->overloadNumber());
             break;
         default:
-            if (fn->hasOneAssociatedProperty() && fn->doc().isEmpty()) {
-                return refForNode(fn->associatedProperties()[0]);
+            if (const auto *p = fn->primaryAssociatedProperty(); p && fn->doc().isEmpty()) {
+                return refForNode(p);
             } else {
                 ref = fn->name();
                 if (fn->overloadNumber() != 0)

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/comprehensiveproject/expected/docbook/testqdoc-testderived.xml

@@ -185,6 +185,38 @@
 </db:listitem>
 </db:itemizedlist>
 </db:section>
+<db:section xml:id="secondBoolProp-prop">
+<db:title its:translate="no">[read-only] secondBoolProp : const bool</db:title>
+<db:fieldsynopsis>
+<db:modifier>(Qt property)</db:modifier>
+<db:type>bool</db:type>
+<db:varname>secondBoolProp</db:varname>
+<db:synopsisinfo role="access">public</db:synopsisinfo>
+<db:synopsisinfo role="status">active</db:synopsisinfo>
+<db:synopsisinfo role="threadsafeness">unspecified</db:synopsisinfo>
+<db:synopsisinfo role="getter">secondBoolProp</db:synopsisinfo>
+<db:synopsisinfo role="notifier">boolPropChanged</db:synopsisinfo>
+</db:fieldsynopsis>
+<db:para>A property sharing a notifier signal with <db:link xlink:href="testqdoc-testderived.xml#boolProp-prop">boolProp</db:link>.</db:para>
+<db:para>
+<db:emphasis role="bold">Access functions:
+</db:emphasis>
+</db:para>
+<db:itemizedlist its:translate="no">
+<db:listitem>
+<db:para><db:type>bool</db:type> <db:emphasis role="bold"><db:link xlink:href="">secondBoolProp</db:link></db:emphasis>()</db:para>
+</db:listitem>
+</db:itemizedlist>
+<db:para>
+<db:emphasis role="bold">Notifier signal:
+</db:emphasis>
+</db:para>
+<db:itemizedlist its:translate="no">
+<db:listitem>
+<db:para><db:type>void</db:type> <db:emphasis role="bold"><db:link xlink:href="testqdoc-testderived.xml#boolProp-prop">boolPropChanged</db:link></db:emphasis>()</db:para>
+</db:listitem>
+</db:itemizedlist>
+</db:section>
 <db:section xml:id="someProp-prop">
 <db:title its:translate="no">[bindable read-only] someProp : QString</db:title>
 <db:fieldsynopsis>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/comprehensiveproject/expected/html/test.index

@@ -149,13 +149,14 @@
                 <function name="bindableProp" fullname="TestQDoc::TestDerived::bindableProp" href="testqdoc-testderived.html#bindableProp-prop" status="active" access="public" location="testcpp.h" meta="plain" associated-property="bindableProp" type="QBindable&lt;QString&gt;" signature="QBindable&lt;QString&gt; bindableProp()"/>
                 <function name="bindablePropChanged" fullname="TestQDoc::TestDerived::bindablePropChanged" href="testqdoc-testderived.html#bindableProp-prop" status="active" access="public" location="testcpp.h" meta="signal" associated-property="bindableProp" type="void" signature="void bindablePropChanged()"/>
                 <function name="boolProp" fullname="TestQDoc::TestDerived::boolProp" href="testqdoc-testderived.html#boolProp-prop" status="active" access="public" location="testcpp.h" meta="plain" associated-property="boolProp" type="bool" signature="bool boolProp()"/>
-                <function name="boolPropChanged" fullname="TestQDoc::TestDerived::boolPropChanged" href="testqdoc-testderived.html#boolProp-prop" status="active" access="public" location="testcpp.h" meta="signal" associated-property="boolProp" type="void" signature="void boolPropChanged()"/>
+                <function name="boolPropChanged" fullname="TestQDoc::TestDerived::boolPropChanged" href="testqdoc-testderived.html#boolProp-prop" status="active" access="public" location="testcpp.h" meta="signal" associated-property="boolProp,secondBoolProp" type="void" signature="void boolPropChanged()"/>
                 <function name="emitSomething" fullname="TestQDoc::TestDerived::emitSomething" href="testqdoc-testderived.html#emitSomething" status="active" access="public" location="testcpp.h" documented="true" meta="signal" type="void" signature="void emitSomething()"/>
                 <function name="getInt" fullname="TestQDoc::TestDerived::getInt" href="testqdoc-testderived.html#intProp-prop" status="active" access="public" location="testcpp.h" meta="plain" associated-property="intProp" type="int *" signature="int * getInt()"/>
                 <function name="id" fullname="TestQDoc::TestDerived::id" href="testqdoc-testderived.html#id" status="active" access="public" location="testcpp.h" documented="true" meta="plain" virtual="virtual" override="true" type="int" signature="int id() override"/>
                 <function name="invokeMe" fullname="TestQDoc::TestDerived::invokeMe" href="testqdoc-testderived.html#invokeMe" status="active" access="public" location="testcpp.h" documented="true" meta="plain" const="true" type="void" brief="Something invokable" signature="void invokeMe() const"/>
                 <function name="name" fullname="TestQDoc::TestDerived::name" href="testqdoc-testderived.html#name-prop" status="active" access="public" location="testcpp.h" meta="plain" const="true" associated-property="name" type="const QString *" signature="const QString * name() const"/>
                 <function name="resetBoolProp" fullname="TestQDoc::TestDerived::resetBoolProp" href="testqdoc-testderived.html#boolProp-prop" status="active" access="public" location="testcpp.h" meta="slot" associated-property="boolProp" type="void" signature="void resetBoolProp()"/>
+                <function name="secondBoolProp" fullname="TestQDoc::TestDerived::secondBoolProp" href="testqdoc-testderived.html#secondBoolProp-prop" status="active" access="public" location="testcpp.h" meta="plain" associated-property="secondBoolProp" type="bool" signature="bool secondBoolProp()"/>
                 <function name="setBindableProp" fullname="TestQDoc::TestDerived::setBindableProp" href="testqdoc-testderived.html#bindableProp-prop" status="active" access="public" location="testcpp.h" meta="slot" associated-property="bindableProp" type="void" signature="void setBindableProp(const QString &amp;s)">
                     <parameter type="const QString &amp;" name="s" default=""/>
                 </function>
@@ -185,6 +186,10 @@
                 <property name="name" fullname="TestQDoc::TestDerived::name" href="testqdoc-testderived.html#name-prop" status="active" access="public" location="testcpp.h" documented="true" writable="false" brief="This property holds a name">
                     <getter name="name"/>
                 </property>
+                <property name="secondBoolProp" fullname="TestQDoc::TestDerived::secondBoolProp" href="testqdoc-testderived.html#secondBoolProp-prop" status="active" access="public" location="testcpp.h" documented="true" writable="false">
+                    <getter name="secondBoolProp"/>
+                    <notifier name="boolPropChanged"/>
+                </property>
                 <property name="someProp" fullname="TestQDoc::TestDerived::someProp" href="testqdoc-testderived.html#someProp-prop" status="active" access="public" location="testcpp.h" documented="true" bindable="true" writable="false">
                     <getter name="someProp"/>
                 </property>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/comprehensiveproject/expected/html/test.qhp

@@ -179,6 +179,8 @@
             <keyword name="rear" id="AbstractParent::rear" ref="qml-qdoc-test-abstractparent.html#rear-method"/>
             <keyword name="resetBoolProp" id="TestDerived::resetBoolProp" ref="testqdoc-testderived.html#boolProp-prop"/>
             <keyword name="sampleReadOnlyProperty" id="TabWidget::sampleReadOnlyProperty" ref="qml-uicomponents-tabwidget.html#sampleReadOnlyProperty-prop"/>
+            <keyword name="secondBoolProp" id="TestDerived::secondBoolProp" ref="testqdoc-testderived.html#secondBoolProp-prop"/>
+            <keyword name="secondBoolProp" id="TestDerived::secondBoolProp" ref="testqdoc-testderived.html#secondBoolProp-prop"/>
             <keyword name="secondColor" id="ProgressBar::secondColor" ref="qml-uicomponents-progressbar.html#secondColor-prop"/>
             <keyword name="setBindableProp" id="TestDerived::setBindableProp" ref="testqdoc-testderived.html#bindableProp-prop"/>
             <keyword name="setBoolProp" id="TestDerived::setBoolProp" ref="testqdoc-testderived.html#boolProp-prop"/>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/comprehensiveproject/expected/html/testqdoc-testderived-members.html

@@ -28,12 +28,13 @@ <h1 class="title" translate="no">List of All Members for TestDerived</h1>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#inlineFunction" translate="no">inlineFunction</a></b></span>()</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-testderived.html#invokeMe" translate="no">invokeMe</a></b></span>() const</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#methodWithEmDashInItsDocs" translate="no">methodWithEmDashInItsDocs</a></b></span>()</li>
-</ul></td><td class="topAlign"><ul>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#methodWithEnDashInItsDocs" translate="no">methodWithEnDashInItsDocs</a></b></span>()</li>
+</ul></td><td class="topAlign"><ul>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-testderived.html#name-prop" translate="no">name</a></b></span>() const : const QString *</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#overload" translate="no">overload</a></b></span>()</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#overload-1" translate="no">overload</a></b></span>(bool)</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-testderived.html#boolProp-prop" translate="no">resetBoolProp</a></b></span>()</li>
+<li class="fn" translate="no"><span class="name"><b><a href="testqdoc-testderived.html#secondBoolProp-prop" translate="no">secondBoolProp</a></b></span>() : bool</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-testderived.html#bindableProp-prop" translate="no">setBindableProp</a></b></span>(const QString &amp;)</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-testderived.html#boolProp-prop" translate="no">setBoolProp</a></b></span>(bool)</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#someFunction" translate="no">someFunction</a></b></span>(int, int) : int</li>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/comprehensiveproject/expected/html/testqdoc-testderived.html

@@ -54,6 +54,7 @@ <h2 id="properties">Properties</h2>
 <li class="fn" translate="no"><b><a href="testqdoc-testderived.html#intProp-prop" translate="no">intProp</a></b> : int* const</li>
 </ul></td><td class="topAlign"><ul>
 <li class="fn" translate="no"><b><a href="testqdoc-testderived.html#name-prop" translate="no">name</a></b> : const QString*</li>
+<li class="fn" translate="no"><b><a href="testqdoc-testderived.html#secondBoolProp-prop" translate="no">secondBoolProp</a></b> : const bool</li>
 <li class="fn" translate="no"><b><a href="testqdoc-testderived.html#someProp-prop" translate="no">someProp</a></b> : QString</li>
 </ul>
 </td></tr>
@@ -65,6 +66,7 @@ <h2 id="public-functions">Public Functions</h2>
 <tr><td class="memItemLeft rightAlign topAlign"> int *</td><td class="memItemRight bottomAlign"><b><a href="testqdoc-testderived.html#intProp-prop" translate="no">getInt</a></b>()</td></tr>
 <tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="testqdoc-testderived.html#invokeMe" translate="no">invokeMe</a></b>() const</td></tr>
 <tr><td class="memItemLeft rightAlign topAlign"> const QString *</td><td class="memItemRight bottomAlign"><b><a href="testqdoc-testderived.html#name-prop" translate="no">name</a></b>() const</td></tr>
+<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="testqdoc-testderived.html#secondBoolProp-prop" translate="no">secondBoolProp</a></b>()</td></tr>
 <tr><td class="memItemLeft rightAlign topAlign"> const QString &amp;</td><td class="memItemRight bottomAlign"><b><a href="testqdoc-testderived.html#someProp-prop" translate="no">someProp</a></b>()</td></tr>
 <tr><td class="memItemLeft rightAlign topAlign"> TestQDoc::TestDerived::NotTypedef </td><td class="memItemRight bottomAlign"><b><a href="testqdoc-testderived.html#someValue" translate="no">someValue</a></b>()</td></tr>
 </table></div>
@@ -139,6 +141,18 @@ <h3 class="fn" translate="no" id="name-prop"><code class="details extra" transla
 <tr><td class="memItemLeft topAlign rightAlign"> const QString *</td><td class="memItemRight bottomAlign"><span class="name"><b>name</b></span>() const</td></tr>
 </table></div>
 <!-- @@@name -->
+<!-- $$$secondBoolProp-prop$$$secondBoolProp$$$boolPropChanged -->
+<h3 class="fn" translate="no" id="secondBoolProp-prop"><code class="details extra" translate="no">[read-only]</code> <span class="name">secondBoolProp</span> : const <span class="type">bool</span></h3>
+<p>A property sharing a notifier signal with <a href="testqdoc-testderived.html#boolProp-prop" translate="no">boolProp</a>.</p>
+<p><b>Access functions:</b></p>
+<div class="table"><table class="alignedsummary" translate="no">
+<tr><td class="memItemLeft topAlign rightAlign"> bool </td><td class="memItemRight bottomAlign"><span class="name"><b>secondBoolProp</b></span>()</td></tr>
+</table></div>
+<p><b>Notifier signal:</b></p>
+<div class="table"><table class="alignedsummary" translate="no">
+<tr><td class="memItemLeft topAlign rightAlign"> void </td><td class="memItemRight bottomAlign"><span class="name"><b><a href="testqdoc-testderived.html#boolProp-prop" translate="no">boolPropChanged</a></b></span>()</td></tr>
+</table></div>
+<!-- @@@secondBoolProp -->
 <!-- $$$someProp-prop$$$someProp -->
 <h3 class="fn" translate="no" id="someProp-prop"><code class="details extra" translate="no">[bindable read-only]</code> <span class="name">someProp</span> : <span class="type">QString</span></h3>
 <div class="admonition note"><p><b>Note: </b>This property supports <a href="https://wiki.qt.io/QProperty">QProperty</a> bindings.</p>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/comprehensiveproject/expected/html/testtagfile.tags

@@ -291,6 +291,13 @@
             <anchor>boolProp-prop</anchor>
             <arglist>()</arglist>
         </member>
+        <member kind="function" protection="public" virtualness="non" static="no">
+            <type>bool</type>
+            <name>secondBoolProp</name>
+            <anchorfile>testqdoc-testderived.html</anchorfile>
+            <anchor>secondBoolProp-prop</anchor>
+            <arglist>()</arglist>
+        </member>
         <member kind="function" protection="public" virtualness="non" static="no">
             <type>const QString &amp;</type>
             <name>someProp</name>
@@ -418,6 +425,12 @@
             <anchor>name-prop</anchor>
             <arglist></arglist>
         </member>
+        <member kind="property" type="bool">
+            <name>secondBoolProp</name>
+            <anchorfile>testqdoc-testderived.html</anchorfile>
+            <anchor>secondBoolProp-prop</anchor>
+            <arglist></arglist>
+        </member>
         <member kind="property" type="QString">
             <name>someProp</name>
             <anchorfile>testqdoc-testderived.html</anchorfile>