QDoc: Remove Node::PageType

QDoc uses a series of internal structure, based on an inheritance tree
with base `Node`, to represent elements that are documentable and their
properties.

For documentable elements that generate a documentation page in the
output, such as a documented C++ class, a subtree of the hierarchy,
starting at `PageNode`, is used.

A `PageNode`, and more generally a `Node`, can have a "Page Type",
representing the type of element that the output documentation should
represent.

This is implemented in terms of an enumeration and an internal memeber
of that enumeration.

Supposedly, originally there was almost no hierarchy of types for
`PageNode`s, and the enumeration was used as a form of tagged union to
discern the the type of page that the `PageNode` would produce to
determine the valid operations on it and the required computations that
should have been performed during a generation.

At some point in QDoc lifetime, some of the types implied by `PageType`
were promoted to actual types under a `PageNode` hierarchy, for example
`ExampleNode`, such that the use of `PageType` was reduced.

Today, `PageType` is used only when parsing a "\page" command, which
generates a `PageNode`.

The "\page" command, which declares that a comment-block should generate
a standalone documentation page in the output that doesn't document any
specific or code-level element, takes an argument representing the name
of the generated file and, optionally, a second argument.

The optional second argument is a bare string that, if of a specific
form, is used to define the type of the generated `PageNode` that
represents the page.

For example, a second argument of form "api" would mark the `PageNode`
with as being of type `PageType::ApiPage`.

Generally, this information is not used at all during the rest of a QDoc
execution, as none of the remaining `PageType` nodes that don't have an
actual type require special handling.

There is, albeit, one exception to this. When the second argument of a
"\page" command is "attribution", the `PageNode` has type
`PageType::AttributionPage`.

This type is meaningful as it is later used to collect "Attribution
Pages" for a certain module so that QDoc can generate a list of them in
Qt's documentation.

"Attribution pages" are a special type of page that are used in Qt's
documentation to "attribute" usages of third-party libraries, so as to
comply with their licensing.

Those pages are only expected to be generated by "qattributionscanner",
which takes care of parsing json-defined attribution metadata for
third-party libraries to generate the required attribution page.

Thus, while `PageType` is generally not required, this specific behavior
has to be supported.

Hence, we remove `PageType`, replacing it with an equivalent behavior
that only handles attributions.

The `PageType` enum in `Node` is now removed.

`Node::pageType`, the getter for the current `PageType` of `PageNode`,
the two `Node::setPageType` overloads, the setter for the `PageType` of
a `PageNode` and `Node::getPageType`, a converter from
`Node::NodeType` to `Node::PageType`, were removed as they have no
meaning anymore.

The member `m_pageType` of `Node`, that contained the current "Page
Type" of a `Node` instance, was removed as it lost its use.

The constructor for `Node` is now modified to not set a `PageType`.

The constructor for `PageNode` that took a `PageType` to set was
removed, as it lost its use.
As a consequence, the code that handles the "\page" command in
`CppCodeParser::processTopicCommand`, was removed call the constructor
for `PageNode` that does not require a `PageType`.

Furthermore, the same code was modified to not process the second
argument of a "\page" command anymore.
The parsing and retrieval of the second argument is tied to the current
model used by `DocParser`, which is general for topic commands, and
cannot be easily removed, such that it will still be valid to pass a
second argument albeit it will be completely ignored.

The documentation in QDoc's manual that explains the usage of "\page"'s
second argument was removed as a consequence.

The code in `QDocIndexFiles` that writes and reads a `PageNode` was
modified to ignore the type, where possible, while keeping a similar
structure for the produced format.

To preserve the "Attribution Pages" behavior, a new member,
`is_attribution`, was introduced in `PageNode`, acting as a flag,
defaulting to false, that is set when a `PageNode` is an "Attribution
Page".
A setter that turns on the flag, `markAttribution`, and a getter that
reads the flag, `isAttribution`, were added to `PageNode`.

Albeit in a more contained scope than the previous `Node` scope, the new
members are too broadly scoped compared to their actual usages. For
example, a `ClassNode` is allowed to be an "Attribution Page" albeit we
don't expect that to make sense.
Due to the low granularity of QDoc's internal representation, fixing
this would either require a bigger refactoring or the introduction of
new idioms, both of which are not an amount of work that is intended to
be undertaken as of this patch.

The code in `Aggregate::findAllAttribution`, that is used to build the
list of "Attribution Pages" in a module, was modified to use the new
methods to discern whether a child node is an "Attribution Page".

A new command, "\attribution", was added to allow a user to mark a
"\page" as an attribution.

The command is not intended to take any arguments and will simply mark
the documented page as being an "Attribution Page".

No user-facing documentation for the command is provided as the command
is intended only to support the internal "qattributionscanner" behavior
in Qt's documentation and should not be used manually or in other places
at the current time.

The necessary code to handle the command was added to `CppCodeParser`,
turning on the relevant flag when the command is found and producing a
warning if the command is not in a "\page" comment-block.

Due to the limited granularity of QDoc's datatypes, the command will
incorrectly pass for non "\page", non `Aggregate` comment-block, such as
"\example", where it could produce seemingly incorrect documentation.
This is something that should be addressed separately in a general look
at QDoc's internal structures.

The code in `QDocIndexFiles::readIndexSection` that reads back a
`PageNode` was modified to call `PageNode::markAttribution` when reading
back a `PageNode` that is an attribution.

The generator of QDoc's "Attribution Pages" for "qattributionscanner"
was modified to output an "\attribution" command on the line following
the "\page" command produced for an "Attribution Page" instead of
generating an "attribution" argument for the "\page" command itself, to
be compliant with the new interface.

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

1 files changed, 2 insertions, 1 deletions

diff --git a/src/qtattributionsscanner/qdocgenerator.cpp b/src/qtattributionsscanner/qdocgenerator.cpp
index ef6e0ba8b..fbe1df06a 100644
--- a/src/qtattributionsscanner/qdocgenerator.cpp
+++ b/src/qtattributionsscanner/qdocgenerator.cpp
@@ -64,7 +64,8 @@ static void generate(QTextStream &out, const Package &package, const QDir &baseD
         out << "\\ingroup attributions-" << package.qdocModule << "\n";
         // include in '\generatelist annotatedattributions'
         out << "\\page " << package.qdocModule << "-attribution-" << package.id
-            << ".html attribution\n";
+            << ".html\n";
+        out << "\\attribution\n";
     } else {
         out << "\\page " << package.qdocModule << "-attribution-" << package.id
             << ".html \n";