summaryrefslogtreecommitdiff
path: root/src/qdoc/cppcodeparser.cpp
diff options
context:
space:
mode:
authorLuca Di Sera <luca.disera@qt.io>2022-09-02 14:39:44 +0200
committerLuca Di Sera <luca.disera@qt.io>2022-09-05 10:05:54 +0200
commit2bed575c936cfb5e882538dc1c7c01222462dd81 (patch)
tree6e2fa26a054e11e13344c81d9122adb716885f23 /src/qdoc/cppcodeparser.cpp
parentcc00255e0176d4344ad5606c7081f32e81a232f7 (diff)
downloadqttools-2bed575c936cfb5e882538dc1c7c01222462dd81.tar.gz
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>
Diffstat (limited to 'src/qdoc/cppcodeparser.cpp')
-rw-r--r--src/qdoc/cppcodeparser.cpp9
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);
+ }
}
}