QDoc: Remove the prefix parameter of `HtmlGenerator::generateSynopsis`

`HtmlGenerator::generateSynopsis` is used to generate summarized, such
as a list containing all elements, and detailed, such as the actual
documentation for an element, sections for the elements of an
`Aggregate`, an internal structure representing documentable elements
that are composed of multiple documentable elements, for example the
methods of a C++ class.

Generally, `HtmlGenerator::generateSynopsis` will work with members of a
`Section`, an internal class that is used to dispatch the members of an
`Aggregate` into a series of categories.

Internally, a `Section` uses a map to store those categorized members,
later exposing the keys of the map, a special sortable `QString`
generated by the `sortName` free function in "sections.cpp", and the
values of the map, the actual `Node`s under the aggregate, to the
consumer.

`generateSynopsis` takes a series of parameter such as the `Node`
that should be documented, the style of the documentation to be
generated (summarized or detailed) and some formatting-related
parameters.

One of those parameters, "prefix", is a `const QString` (unnecessarily a
pointer), that is prepended to the output documentation if passed in.

The "prefix" parameter is used only in
`HtmlGenerator::generateSectionList`, a method that produces an output
documentation from certain categories of documentable elements as
generated by `Section`.

In the context of `generateSectionList`, the "prefix" argument is taken
from the keys of the internal map that the generated `Section` uses.

The key representing the currently documented element, the one that will
be passed to `generateSynopsis`, is obtained and slightly modified
before being passed on.

In particular, the first character of the key is removed. The keys are
generated from `sortName` which prepends a letter to the name of the
`Node` to generate a specific sorting order. Removing the first letter
removes this additional character, restoring, almost as certain
categories of elements append certain suffixes to the name, the original
name of the node.

Then, everything, that does not precede a "::" is discarded from the
prefix.
Generally, the name of a `Node` will not be qualified, meaning that
everything is discarded and the prefix is an empty string, such that it
has no meaningful impact of the result of `generateSynopsis`.

Supposedly, based on the transformations that are performed on the
original key, the "prefix" was intended to represent the qualified part
of a qualified path to the documentable element.

Nonetheless, this is already taken care off in `generateSynopsis`, where
the actual naming of the documentable elements depend on the type of
element and the styling specification, removing, for example, the
qualified part of a method in a summary listing and adding it in
detailing listing.

Indeed, for those, extremely rare, cases where the "prefix" was not
empty, `generateSynopsis` would produce an incorrectly named
documentation with repeating elements.

5 counts of this behavior were identified in the current documentation:

In the all member listing of `QCborError`, the conversion operator
`Code` incorrectly duplicated the "operator QCborError::" string,
resulting in the mangled name "operator QCborError::operator
QCborError::Code".

This same kind of duplication happened for `QFlags`'s `int` conversion,
`QGlobalStatic`'s `QGlobalStatic::Type` conversion,
`QDBusPendingReply`'s `Select<0>::Type` conversion and `QDBusReply`'s
`QDBusReply::Type` conversion.

Hence, the "prefix" parameter was removed from
`HtmlGenerator::generateSynopsis` as bug-producing and unnecessary.

The declaration of `generateSynopsis` in the header file was modified to
take into account the removal.

The parameter was removed from the definition in the implementation
file and the code that branched on "prefix" was removed.

The single call site in `HtmlGenerator::generateSectionList` was
modified to neither produce nor pass a prefix to the `generateSynopsis`
call.

The two `keys` overloaded method in `Section` were removed.
The methods were used to retrieve the keys of the internal `Section`
maps in `HtmlGenerator::generateSectionList`, to produce the prefix, and
are consequently dead code due to the removal of their call site.

The `m_keys` and `m_obsoleteKeys` members of `Section`, that were
caching a vector of keys for the internal maps of `Section`, later
exposed by the `Section::keys` overloads, were removed as they lost
their usage.

`Section::clear`, which resets the state of a `Section`, due to the
static nature of the `Section`/`Sections` class pair that reuses a
single `Section` instance multiple times, was modified so that it would
not invalidate the `m_keys` and `m_obsoleteKeys` cache, as the members
are now non-existing.

Similarly, `Section::reduce`, a method that is used to populate a series
of caches and simplified representation for the internal members of
`Section`, was modified to avoid caching the keys of the internal maps
in `m_keys` and `m_obsoleteKeys` as the member are now non-existing.

Due to the now non-exposure of keys, the internal structure of a
`Section` can be simplified by flattening the maps into a vector.
Nonetheless, the maps have a further use in ordering the dispatched
`Node`s, for which an alternative must be produced.
Temporarily, the internal maps structure will be kept and any possible
simplification will be explored separately.

Due to the removal of the "prefix" argument, the 5 incorrectly behaving
cases of documentation are now resolved, avoiding the duplication.
The exact reason for the misplaced behavior is unknown, albeit it is
expected to depend on the special handling of operators' name that QDoc
performs in various parts of the codebase.

Albeit not currently representing a bug anymore, the exact flow of the
data producing the bug is expected to be addressed separately.

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

0 files changed, 0 insertions, 0 deletions