qdoc: Delay processing of \relates meta-command arguments

The \relates command is used for C++ entities in the global scope to
associate them with a page-generating Aggregate (class, namespace, or
a header file).

The \relates command is a meta-command, processed after all the
topic commands (in the same source file) are handled. However, if the
\relates command referred an aggregate that does not exist (because
its documentation is in another file, yet to be processed), we ran into
problems: QDoc created a new ProxyNode to serve as the location to
generate the the related node's documentation to. After the proxy node
had been created, all subsequent associations were tied to that proxy,
even after the real aggregate's node had been created and added to the
tree. An output page was generated for the proxy, but it often ended
up being orphaned.

In practice this was only a problem for header file aggregates, as
they are the only 'relatable' node type not constructed by
ClangCodeParser during pre-compiled header generation, but later
during the processing of documentation comments (\headerfile topic).

Recent changes to the order of processing topic and meta-commands
unmasked this issue with the current documentation sources, but the
implementation was always fragile.

To fix, add a new post-processing step that handles \relates arguments
after all sources have been parsed. This must be done before calling
Aggregate::normalizeOverloads() as the related non-member functions
have an effect on overload ordering.

Remove remnants of the undocumented ability to allow multiple \relates
commands in the same topic - it was defunct and can be re-introduced
with a proper implementation.

Fixes: QTBUG-123622
Change-Id: I9b85d9c9447825d17d4a4dd345c811dfecfb2411
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

0 files changed, 0 insertions, 0 deletions