QDoc: Move `Node::setNoAutoList` to `PageNode`

QDoc generates automatic lists of elements for some of its pages that
represents a collection of certain elements.

In particular, it does so for pages generated through the "\module",
"\qmlmodule", "\group" and "\example" topics.

The user can avoid this behavior by using the "\noautolist" command
anywhere in a comment-block that has one of those topics, inhibiting the
generation of the automated list, generally to replace it with a
manually chosen list by the author.

Internally, QDoc uses a simple boolean flag that is turned on by the
presence of a "\noautolist" command in a comment block.

This flag is available to any `PageNode`, the internal representation
for documentation elements that generate a page in the output, and
subclasses instances, under the `m_noAutoList` member, together with a
getter method `noAutoList` and a setter method `setNoAutoList`.

Contrary to the getter method, the setter method `setNoAutoList` is not
a direct member of `PageNode`, and is instead overridden from the virtual
method `setNoAutoList` under `Node`, the base class for internal
representation of documentation elements in QDoc.

`Node::setNoAutoList` has no meaningful implementation or usage of
`setNoAutoList`.

Indeed, only `PageNode`s would be able to give a meaning to "not
generating an automatic list in the produced output page" as they are
the only element producing a page in the output in the first place.

To limit the scope of the method to where it has meaning, remove the
virtual call overhead and generally provide a cleaner interface,
`Node::setNoAutoList` was removed and the implementation in `PageNode`
was made a direct implementation.

The documentation for `Node::setNoAutoList` in `node.cpp` was further
removed as a consequence of the change.

To support the change, the code in `CppCodeParser` that handles the
"\noautolist" command, setting the boolean flag through a call to
`setNoAutoList`, was modified to check that the command is applicable
and cast to appropriate node type to access the required method if such
is the case.

When the command is not applicable, a new warning will now be emitted
admonishing the user of the unnecessary use of the command.

Do note that, with the current codebase, the "\noautolist" command is
not meaningful for all page nodes and is indeed only meaningful for
`CollectionNode`s (module, qmlmodule, group) and `ExampleNode`s.

While this restriction was taken into account with regards to the
generation of the new warning, this puts the current getter and setter
method at too broad a scope, as they could incorrectly be used for other
page nodes, such as aggregates.

Currently, `ExampleNode`s and `CollectionNode`s do not share a more
restricted inherited type than `PageNode`, and the concession for the
broader scope was thus made with this limitation in mind and with
regards for the current structure of the codebase.

Nonetheless, it could be in the future considered to revise the current
location and implementation of the methods to restrict such a scope.

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

1 files changed, 8 insertions, 1 deletions

diff --git a/src/qdoc/cppcodeparser.cpp b/src/qdoc/cppcodeparser.cpp
index a4a6c53fd..196efd527 100644
--- a/src/qdoc/cppcodeparser.cpp
+++ b/src/qdoc/cppcodeparser.cpp
@@ -682,7 +682,14 @@ void CppCodeParser::processMetaCommand(const Doc &doc, const QString &command,
             static_cast<CollectionNode*>(node)->setState(arg);
         }
     } else if (command == COMMAND_NOAUTOLIST) {
-        node->setNoAutoList(true);
+        if (!node->isCollectionNode() && !node->isExample()) {
+            doc.location().warning(
+                    QStringLiteral(
+                            "Command '\\%1' is only meaningful in '\\module', '\\qmlmodule', `\\group` and `\\example`.")
+                            .arg(COMMAND_NOAUTOLIST));
+        } else {
+            static_cast<PageNode*>(node)->setNoAutoList(true);
+        }
     }
 }