QDoc: Fix ordering of overloads for QML Types

When QDoc generates a page for a QML type, as a result of the "\qmltype"
topic command, it generates, similarly to C++, a summary list of
members, a detailed list of members and a separate page listing a
summary of all members of the type.

Internally, QDoc uses two coupled classes, `Section` and `Sections`, to
destructure an `Aggregate`, the internal representation of documentable
element that are composed of multiple documentable elements, such as a
QML Type, into a series of ordered categories of child elements.

Those categories are later used to generate the various "sections" of
the `Aggregate` documentation, such as the various list, as described
above, for a QML Type.

The ordering of all those "sections" is given based on the results of
the free-function `sortName` in "sections.cpp".
`sortName` produces ordered strings based on a `Node`'s name.

When QDoc parses QML methods that are overloads, as it does for C++, it
assigns an "overload number" to each of them, to discern the various
equally named elements.

One of the elements is considered the "primary overload", to which no
number is assigned, and all other elements are considered "non-primary
overloads", to which an increasing positive integer "overload number" is
assigned.

Due to the current implementation of `sortName`, the "overload number"
is not considered when sorting the methods of a QML Type, contrary to
the behavior reserved for C++ overloads.

As a consequence, the various overloads in a section are ordered based
on the implementation details of their storing mechanism and sorting
algorithm.

In particular, in our specific case where a red-black tree map is used,
they are ordered in descending order of their overload number.

For example, given some method named X and a few of its overload X-1,
X-2 and X-3, the "sections" listing the overloads will order them as
x-3, X-2, X-1, X.

While the assignment of the "overload number", currently, generally only
follows the order in which QDoc encounters the various overloads, such
that it may not be consistent between source files or versions of the
code, it generally follows, in the Qt codebase, a "better looking"
order, where overloads with a "more complex" signature appear after
their peers with a "simpler" signature.

Furthermore, we enforce an ascending order for C++ overloads based on
the overload number, contrary to the current behavior for QML overloads.

Hence, to increase the consistency between the ordering of overloads in
C++ and QML documentation and possibly provide a "better looking"
output, `sortName` was modified to take into account the "overload
number" for QML overloads.

The regression files for `tst_generatedOutput` were regenerated to take
into account the ordering change.

Change-Id: I904ec35e428e8b0b1740826eb6ad9726a261938a
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

4 files changed, 26 insertions, 26 deletions

diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-qdoc-test-abstractparent.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-qdoc-test-abstractparent.xml
index 647b6e6ed..154b70b0f 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-qdoc-test-abstractparent.xml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-qdoc-test-abstractparent.xml
@@ -63,14 +63,14 @@
 </db:section>
 <db:section xml:id="method-documentation">
 <db:title>Method Documentation</db:title>
-<db:section xml:id="name-method-1">
-<db:title>void name()</db:title>
-<db:para>Name all children with random names.</db:para>
-</db:section>
 <db:section xml:id="name-method">
 <db:title>void name(Child <db:emphasis>child</db:emphasis>, <db:emphasis>name</db:emphasis>)</db:title>
 <db:para>Name a <db:code role="parameter">child</db:code> using <db:code role="parameter">name</db:code>.</db:para>
 </db:section>
+<db:section xml:id="name-method-1">
+<db:title>void name()</db:title>
+<db:para>Name all children with random names.</db:para>
+</db:section>
 <db:section xml:id="rear-method">
 <db:title>void rear(Child <db:emphasis>child</db:emphasis>, var <db:emphasis>method</db:emphasis> = Strict)</db:title>
 <db:para>Do some abstract parenting on <db:code role="parameter">child</db:code> using a specific <db:code role="parameter">method</db:code>.</db:para>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-qdoc-test-child.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-qdoc-test-child.xml
index 0537a3ffc..76df460b7 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-qdoc-test-child.xml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-qdoc-test-child.xml
@@ -63,14 +63,14 @@
 </db:section>
 <db:section xml:id="method-documentation">
 <db:title>Method Documentation</db:title>
-<db:section xml:id="name-method-1">
-<db:title>void name()</db:title>
-<db:para>Name all children with random names.</db:para>
-</db:section>
 <db:section xml:id="name-method">
 <db:title>void name(Child <db:emphasis>child</db:emphasis>, <db:emphasis>name</db:emphasis>)</db:title>
 <db:para>Name a <db:code role="parameter">child</db:code> of this child using <db:code role="parameter">name</db:code>.</db:para>
 </db:section>
+<db:section xml:id="name-method-1">
+<db:title>void name()</db:title>
+<db:para>Name all children with random names.</db:para>
+</db:section>
 <db:section xml:id="rear-method">
 <db:title>void rear(Child <db:emphasis>child</db:emphasis>, var <db:emphasis>method</db:emphasis> = Strict)</db:title>
 <db:para>Do some abstract parenting on <db:code role="parameter">child</db:code> using a specific <db:code role="parameter">method</db:code>.</db:para>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/qml-qdoc-test-abstractparent.html b/tests/auto/qdoc/generatedoutput/expected_output/qml-qdoc-test-abstractparent.html
index ac27f326b..b16778260 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/qml-qdoc-test-abstractparent.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/qml-qdoc-test-abstractparent.html
@@ -34,8 +34,8 @@
 </ul>
 <h2 id="methods">Methods</h2>
 <ul>
-<li class="fn">void <b><a href="qml-qdoc-test-abstractparent.html#name-method-1">name</a></b>()</li>
 <li class="fn">void <b><a href="qml-qdoc-test-abstractparent.html#name-method">name</a></b>(Child <i>child</i>, <i>name</i>)</li>
+<li class="fn">void <b><a href="qml-qdoc-test-abstractparent.html#name-method-1">name</a></b>()</li>
 <li class="fn">void <b><a href="qml-qdoc-test-abstractparent.html#rear-method">rear</a></b>(Child <i>child</i>, var <i>method</i>)</li>
 </ul>
 <!-- $$$AbstractParent-description -->
@@ -63,24 +63,24 @@
 </div></div><!-- @@@name -->
 <br/>
 <h2>Method Documentation</h2>
-<!-- $$$name$$$name -->
+<!-- $$$name[overload1]$$$nameChild -->
 <div class="qmlitem"><div class="qmlproto">
 <div class="table"><table class="qmlname">
-<tr valign="top" class="odd" id="name-method-1">
+<tr valign="top" class="odd" id="name-method">
 <td class="tblQmlFuncNode"><p>
-<span class="type">void</span> <span class="name">name</span>()</p></td></tr>
+<span class="type">void</span> <span class="name">name</span>(<span class="type"><a href="qml-qdoc-test-child.html">Child</a></span> <i>child</i>, <i>name</i>)</p></td></tr>
 </table></div></div>
-<div class="qmldoc"><p>Name all children with random names.</p>
+<div class="qmldoc"><p>Name a <i>child</i> using <i>name</i>.</p>
 </div></div><!-- @@@name -->
 <br/>
-<!-- $$$name[overload1]$$$nameChild -->
+<!-- $$$name$$$name -->
 <div class="qmlitem"><div class="qmlproto">
 <div class="table"><table class="qmlname">
-<tr valign="top" class="odd" id="name-method">
+<tr valign="top" class="odd" id="name-method-1">
 <td class="tblQmlFuncNode"><p>
-<span class="type">void</span> <span class="name">name</span>(<span class="type"><a href="qml-qdoc-test-child.html">Child</a></span> <i>child</i>, <i>name</i>)</p></td></tr>
+<span class="type">void</span> <span class="name">name</span>()</p></td></tr>
 </table></div></div>
-<div class="qmldoc"><p>Name a <i>child</i> using <i>name</i>.</p>
+<div class="qmldoc"><p>Name all children with random names.</p>
 </div></div><!-- @@@name -->
 <br/>
 <!-- $$$rear[overload1]$$$rearChildvar -->
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/qml-qdoc-test-child.html b/tests/auto/qdoc/generatedoutput/expected_output/qml-qdoc-test-child.html
index 7981d597b..37da7b5d7 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/qml-qdoc-test-child.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/qml-qdoc-test-child.html
@@ -34,8 +34,8 @@
 </ul>
 <h2 id="methods">Methods</h2>
 <ul>
-<li class="fn">void <b><a href="qml-qdoc-test-child.html#name-method-1">name</a></b>()</li>
 <li class="fn">void <b><a href="qml-qdoc-test-child.html#name-method">name</a></b>(Child <i>child</i>, <i>name</i>)</li>
+<li class="fn">void <b><a href="qml-qdoc-test-child.html#name-method-1">name</a></b>()</li>
 <li class="fn">void <b><a href="qml-qdoc-test-child.html#rear-method">rear</a></b>(Child <i>child</i>, var <i>method</i>)</li>
 </ul>
 <!-- $$$Child-description -->
@@ -63,24 +63,24 @@
 </div></div><!-- @@@name -->
 <br/>
 <h2>Method Documentation</h2>
-<!-- $$$name$$$name -->
+<!-- $$$name[overload1]$$$nameChild -->
 <div class="qmlitem"><div class="qmlproto">
 <div class="table"><table class="qmlname">
-<tr valign="top" class="odd" id="name-method-1">
+<tr valign="top" class="odd" id="name-method">
 <td class="tblQmlFuncNode"><p>
-<span class="type">void</span> <span class="name">name</span>()</p></td></tr>
+<span class="type">void</span> <span class="name">name</span>(<span class="type"><a href="qml-qdoc-test-child.html">Child</a></span> <i>child</i>, <i>name</i>)</p></td></tr>
 </table></div></div>
-<div class="qmldoc"><p>Name all children with random names.</p>
+<div class="qmldoc"><p>Name a <i>child</i> of this child using <i>name</i>.</p>
 </div></div><!-- @@@name -->
 <br/>
-<!-- $$$name[overload1]$$$nameChild -->
+<!-- $$$name$$$name -->
 <div class="qmlitem"><div class="qmlproto">
 <div class="table"><table class="qmlname">
-<tr valign="top" class="odd" id="name-method">
+<tr valign="top" class="odd" id="name-method-1">
 <td class="tblQmlFuncNode"><p>
-<span class="type">void</span> <span class="name">name</span>(<span class="type"><a href="qml-qdoc-test-child.html">Child</a></span> <i>child</i>, <i>name</i>)</p></td></tr>
+<span class="type">void</span> <span class="name">name</span>()</p></td></tr>
 </table></div></div>
-<div class="qmldoc"><p>Name a <i>child</i> of this child using <i>name</i>.</p>
+<div class="qmldoc"><p>Name all children with random names.</p>
 </div></div><!-- @@@name -->
 <br/>
 <!-- $$$rear[overload1]$$$rearChildvar -->