QDoc: Remove Section::m_memberMap

QDoc uses a pair of classes `Sections`/`Section` that destruct and
categorize the members of an `Aggregate`, an internal representation for
documentable elements that are composed of multiple documentable
elements, to generate a series of ordered lists in the output
documentation.

For example, the list of members of a C++ class in the reference page of
that same class.

Internally, a `Section` categorizes the "children" of an `Aggregate` by
using a series of maps, to provide an ordering, that are later
"flattened" into ordered, sequential, monodimensional-structures,
generally vectors, that are presented to the consumer of a `Section`,
mostly the `Generator`s that actually produce the output documentation,
to iterate over the categorized elements.

The keys of the internal maps are never used by consumers of a
`Section`, such that their only purpose is to internally provide an
ordering before they are "flattened".

Hence, the maps can be removed, with the intermediate flattening step,
in favor of directly constructing the same monodimensional-structures,
which can be sorted directly, before being presented to a consumer, to
produce the same result.

`Section::m_memberMap`, is one such map that is used to hold all the
elements of a destructured `Aggregate`, without categorization and is
now removed as it is unnecessary.

Further to removing the member variable, all insertion into the map were
converted to insertion into `Section::m_members`, the flattened version
of the map.
`Section::insert/2`, which inserted an element with a certain key into
the `Section::m_memberMap` was removed as it lost its purpose.

`Section`s are statically allocated in `Sections`, which act as a
container of `Section`, and are reused between instances of `Sections`.
To support this structure, `Section` provides a `clear` method, which
cleans the internal state, such as the internal maps, to prepare the
`Section` instance for reuse.
The clearance of `m_memberMap` was removed from `Section::clear`, as the
member variable is not part of the internal state anymore.

As `Section` destructures an `Aggregate` into categories, not all of
which might be used depending on the structure of the specific
`Aggregate`, it provides a custom `isEmpty` method that specifies that
the `Section` is empty only if all of the internal containers for each
category is empty.
This method was changed to use `m_members` instead of `m_memberMap` to
check the emptiness of the "all members" category, as `m_memberMap` is
now removed in favor of `m_members`.

Each internal map is "flattened" in `Section::reduce`, which is called
after the `Aggregate` that a `Section` is destructuring is fully
categorized.
The code flattening `m_memberMap` was removed in favor of sorting
`m_members` at this step, after it is fully populated.

`Section` uses a free function in "sections.cpp", `sortName`, which
produces a series of orderable strings based on a `Node`'s, the base
class for a documentable element, name, that are generally used as keys
for the map, providing the specific ordering that QDoc currently uses.

To provide the same ordering, some temporary code was included as a
comparator that uses `sortName` as its base.
As `sortName` is relatively heavy, as it has to allocate a series of
strings so that they can be used as keys to the maps, the temporary
code, together with `sortName`, are later expected to be removed in
favor of a direct comparator that does not use intermediate strings,
when all internal maps are removed in favor of their flattened version.

It should be noted that, while the ordering uses the same methodology,
it will not be equivalent to the one provided by the map-based
implementation.
As `sortName` is not antisymmetric, certain elements are considered
equal, albeit they are not the same documentable element.
The ordering for such colliding elements is implementation dependent and
is inverted between the map-based version, which orders colliding
elements in reversed insertion order, and the "flattened" version, which
orders colliding elements in insertion order.

This affects many files in the output documentation, generally the
"members" file that QDoc produces for a C++ class, that lists all
elements of the class, inherited or not.

Furthermore, certain non-members file are affected.
QDoc identifies C++ methods or functions with the same name under the
same namespace as overloads.
It later marks them with an "overload number", a simple increasing
integer that is used to differentiate the various equally named elements.
`sortName` takes this overload number into account, so that different
overloads of the same element do not collide.

Nonetheless, there seems to be a bug where certain elements are not
correctly identified as overloads, producing the same `sortName` and
thus colliding.
C++ classes that have those colliding elements will see a difference in
their ordering.

Such an example are some of the "drawText" members in "qpainter.html".

In `Section`, not all elements would first pass by the internal map
before it was "flattened", instead having them directly inserted in the
"flattened" version, such that they would receive no sorting.

For example, elements of a `SharedCommentNode`, an internal
representation for elements that share a documentation block, would
behave this way.
As the sorting now happens directly on the "flattened"
`Section::m_members`, the groups of elements that are produced from
those `SharedCommentNode` will now provide an order.

Lastly, certain spurious changes are in effect due to this change.
Certain C++ classes' reference pages seems to not have any sorting.

For example, "qhashiterator.html", which is produced as the reference
page for `QHashIterator`, show such a behavior.

Such a bug would be caused by the elements of the `Aggregate`
representing the class being inserted directly into the "flattened"
version without passing for any internal map.

It is currently unknown why certain elements would follow this behavior
and the bug should be later addressed separately.

In the meantime, the ordering for those pages is now fixed, as the
sorting is provided directly on the flattened version.

The regression files for `tst_generated_output` were regenerated as they
were affected by the "all members" reordering.

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

3 files changed, 3 insertions, 3 deletions

diff --git a/tests/auto/qdoc/generatedoutput/expected_output/crossmodule/testtype-members.html b/tests/auto/qdoc/generatedoutput/expected_output/crossmodule/testtype-members.html
index 1bfd9fef5..974819e53 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/crossmodule/testtype-members.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/crossmodule/testtype-members.html
@@ -23,8 +23,8 @@
 <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-test.html#someFunction" translate="no">someFunction</a></b></span>(int, int) : int</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#someFunctionDefaultArg" translate="no">someFunctionDefaultArg</a></b></span>(int, bool)</li>
-<li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#virtualFun" translate="no">virtualFun</a></b></span>()</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-testderived.html#virtualFun" translate="no">virtualFun</a></b></span>()</li>
+<li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#virtualFun" translate="no">virtualFun</a></b></span>()</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#operator-eq" translate="no">operator=</a></b></span>(TestQDoc::Test &amp;&amp;) : TestQDoc::Test &amp;</li>
 </ul>
 </body>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/properties/testqdoc-testderived-members.html b/tests/auto/qdoc/generatedoutput/expected_output/properties/testqdoc-testderived-members.html
index c1bc22f3d..4d3461360 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/properties/testqdoc-testderived-members.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/properties/testqdoc-testderived-members.html
@@ -38,8 +38,8 @@
 <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>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#someFunctionDefaultArg" translate="no">someFunctionDefaultArg</a></b></span>(int, bool)</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-testderived.html#someProp-prop" translate="no">someProp</a></b></span>() : const QString &amp;</li>
-<li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#virtualFun" translate="no">virtualFun</a></b></span>()</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-testderived.html#virtualFun" translate="no">virtualFun</a></b></span>()</li>
+<li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#virtualFun" translate="no">virtualFun</a></b></span>()</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#operator-eq" translate="no">operator=</a></b></span>(TestQDoc::Test &amp;&amp;) : TestQDoc::Test &amp;</li>
 </ul>
 </td></tr>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/testqdoc-testderived-members.html b/tests/auto/qdoc/generatedoutput/expected_output/testqdoc-testderived-members.html
index 2873c37be..21fdd803d 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/testqdoc-testderived-members.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/testqdoc-testderived-members.html
@@ -23,8 +23,8 @@
 <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-test.html#someFunction" translate="no">someFunction</a></b></span>(int, int) : int</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#someFunctionDefaultArg" translate="no">someFunctionDefaultArg</a></b></span>(int, bool)</li>
-<li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#virtualFun" translate="no">virtualFun</a></b></span>()</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-testderived.html#virtualFun" translate="no">virtualFun</a></b></span>()</li>
+<li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#virtualFun" translate="no">virtualFun</a></b></span>()</li>
 <li class="fn" translate="no"><span class="name"><b><a href="testqdoc-test.html#operator-eq" translate="no">operator=</a></b></span>(TestQDoc::Test &amp;&amp;) : TestQDoc::Test &amp;</li>
 </ul>
 </body>