diff options
author | Topi Reinio <topi.reinio@qt.io> | 2021-06-15 10:58:14 +0200 |
---|---|---|
committer | Topi Reinio <topi.reinio@qt.io> | 2021-06-17 11:55:08 +0200 |
commit | b0d6055daa7e52ff85af7c326f54aecf84c2c554 (patch) | |
tree | 4bb191549213cb1ceeea91d98e4258859005e07e | |
parent | 41fcd64f704948b2fc9bb054c055ed66aac3f8df (diff) |
qdoc: Stop documenting ignored nodes
There were multiple locations in the code where QDoc still generated
links to nodes that were marked with \internal or \dontdocument, or
generated lists that included entries (with links to non-existing
files) representing these nodes.
* Set an empty (but non-null) url for ignored nodes. This
also speeds up searching for link targets as nodes can
be dismissed early based on their url().
* Use Node::isDontDocument() as a conditional in Node::isInAPI(),
and filter CollectionNode's members based on the latter - this
removes ignored classes/functions from module pages and group
listings.
* Fix TagFileWriter to drop ignored nodes.
Fixes: QTBUG-94555
Change-Id: Icab05f7aa78e455c15ce097b9f99f5fce7267d3f
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 1246e064caaa6243c941d795eb877c519bce69ad)
Reviewed-by: Topi Reiniƶ <topi.reinio@qt.io>
18 files changed, 98 insertions, 81 deletions
diff --git a/src/qdoc/collectionnode.cpp b/src/qdoc/collectionnode.cpp index bbc154e13..ecf18915a 100644 --- a/src/qdoc/collectionnode.cpp +++ b/src/qdoc/collectionnode.cpp @@ -63,13 +63,9 @@ void CollectionNode::addMember(Node *node) */ bool CollectionNode::hasNamespaces() const { - if (!m_members.isEmpty()) { - for (const auto &member : qAsConst(m_members)) { - if (member->isNamespace()) - return true; - } - } - return false; + return std::any_of(m_members.cbegin(), m_members.cend(), [](const Node *member) { + return member->isClassNode() && member->isInAPI(); + }); } /*! @@ -78,13 +74,9 @@ bool CollectionNode::hasNamespaces() const */ bool CollectionNode::hasClasses() const { - if (!m_members.isEmpty()) { - for (const auto &member : qAsConst(m_members)) { - if (member->isClassNode()) - return true; - } - } - return false; + return std::any_of(m_members.cbegin(), m_members.cend(), [](const Node *member) { + return member->isClassNode() && member->isInAPI(); + }); } /*! @@ -95,7 +87,7 @@ void CollectionNode::getMemberNamespaces(NodeMap &out) { out.clear(); for (const auto &member : qAsConst(m_members)) { - if (member->isNamespace()) + if (member->isNamespace() && member->isInAPI()) out.insert(member->name(), member); } } @@ -107,9 +99,9 @@ void CollectionNode::getMemberNamespaces(NodeMap &out) void CollectionNode::getMemberClasses(NodeMap &out) const { out.clear(); - for (const auto &i : qAsConst(m_members)) { - if (i->isClassNode()) - out.insert(i->name(), i); + for (const auto &member : qAsConst(m_members)) { + if (member->isClassNode() && member->isInAPI()) + out.insert(member->name(), member); } } diff --git a/src/qdoc/node.cpp b/src/qdoc/node.cpp index c9aae40c0..154e16170 100644 --- a/src/qdoc/node.cpp +++ b/src/qdoc/node.cpp @@ -690,6 +690,35 @@ void Node::setDoc(const Doc &doc, bool replace) } /*! + Sets the node's status to \a t, except that once + the node's status has been set to \c Obsolete or + \c Deprecated, it can't be reset. + + \sa Status +*/ +void Node::setStatus(Status t) +{ + if (m_status == Obsolete && t == Deprecated) + return; + + m_status = t; + + // Set non-null, empty URL to nodes that are ignored as + // link targets + switch (t) { + case Internal: + if (Config::instance().showInternal()) + break; + Q_FALLTHROUGH(); + case DontDocument: + m_url = QStringLiteral(""); + break; + default: + break; + } +} + +/*! Construct a node with the given \a type and having the given \a parent and \a name. The new node is added to the parent's child list. @@ -1414,14 +1443,6 @@ QString Node::physicalModuleName() const \sa Access */ -/*! \fn void Node::setStatus(Status t) - Sets the node's status to \a t, except that once - the node's status has been set to \c Obsolete, it - can't be reset to \c Deprecated. - - \sa Status -*/ - /*! \fn void Node::setThreadSafeness(ThreadSafeness t) Sets the node's thread safeness to \a t. diff --git a/src/qdoc/node.h b/src/qdoc/node.h index d5e241812..f751dc90d 100644 --- a/src/qdoc/node.h +++ b/src/qdoc/node.h @@ -248,12 +248,7 @@ public: void setAccess(Access t) { m_access = t; } void setLocation(const Location &t); void setDoc(const Doc &doc, bool replace = false); - void setStatus(Status t) - { - if (m_status == Obsolete && t == Deprecated) - return; - m_status = t; - } + void setStatus(Status t); void setThreadSafeness(ThreadSafeness t) { m_safeness = t; } void setSince(const QString &since); void setPhysicalModuleName(const QString &name) { m_physicalModuleName = name; } @@ -321,7 +316,10 @@ public: return (m_defLocation.isEmpty() ? m_declLocation : m_defLocation); } const Doc &doc() const { return m_doc; } - bool isInAPI() const { return !isPrivate() && !isInternal() && hasDoc(); } + bool isInAPI() const + { + return !isPrivate() && !isInternal() && !isDontDocument() && hasDoc(); + } bool hasDoc() const { return (m_hadDoc || !m_doc.isEmpty()); } bool hadDoc() const { return m_hadDoc; } Status status() const { return m_status; } diff --git a/src/qdoc/parameters.cpp b/src/qdoc/parameters.cpp index 2a5443100..87cc72320 100644 --- a/src/qdoc/parameters.cpp +++ b/src/qdoc/parameters.cpp @@ -61,7 +61,8 @@ QRegularExpression Parameters::varComment_("^/\\*\\s*([a-zA-Z_0-9]+)\\s*\\*/$"); QString Parameter::signature(bool includeValue) const { QString p = type_; - if (!p.endsWith(QChar('*')) && + if (!p.isEmpty() && + !p.endsWith(QChar('*')) && !p.endsWith(QChar('&')) && !p.endsWith(QChar(' ')) && !name_.isEmpty()) { diff --git a/src/qdoc/qdocindexfiles.cpp b/src/qdoc/qdocindexfiles.cpp index 2b0d01040..f83c6a8b9 100644 --- a/src/qdoc/qdocindexfiles.cpp +++ b/src/qdoc/qdocindexfiles.cpp @@ -571,6 +571,13 @@ void QDocIndexFiles::readIndexSection(QXmlStreamReader &reader, Node *current, } { + if (!href.isEmpty()) { + node->setUrl(href); + // Include the index URL if it exists + if (!node->isExternalPage() && !indexUrl.isEmpty()) + node->setUrl(indexUrl + QLatin1Char('/') + href); + } + const QString access = attributes.value(QLatin1String("access")).toString(); if (access == "protected") node->setAccess(Access::Protected); @@ -612,12 +619,6 @@ void QDocIndexFiles::readIndexSection(QXmlStreamReader &reader, Node *current, QString physicalModuleName = attributes.value(QLatin1String("module")).toString(); if (!physicalModuleName.isEmpty()) qdb_->addToModule(physicalModuleName, node); - if (!href.isEmpty()) { - node->setUrl(href); - // Include the index URL if it exists - if (!node->isExternalPage() && !indexUrl.isEmpty()) - node->setUrl(indexUrl + QLatin1Char('/') + href); - } QString since = attributes.value(QLatin1String("since")).toString(); if (!since.isEmpty()) { diff --git a/src/qdoc/tagfilewriter.cpp b/src/qdoc/tagfilewriter.cpp index 2685db50f..25535bc9c 100644 --- a/src/qdoc/tagfilewriter.cpp +++ b/src/qdoc/tagfilewriter.cpp @@ -63,7 +63,7 @@ void TagFileWriter::generateTagFileCompounds(QXmlStreamWriter &writer, const Agg { const auto &nonFunctionList = const_cast<Aggregate *>(parent)->nonfunctionList(); for (const auto *node : nonFunctionList) { - if (!node->url().isEmpty() || node->isPrivate()) + if (!node->url().isNull() || node->isPrivate()) continue; QString kind; @@ -138,7 +138,7 @@ void TagFileWriter::generateTagFileMembers(QXmlStreamWriter &writer, const Aggre { const auto &childNodes = parent->childNodes(); for (const auto *node : childNodes) { - if (!node->url().isEmpty()) + if (!node->url().isNull()) continue; QString nodeName; diff --git a/src/qdoc/xmlgenerator.cpp b/src/qdoc/xmlgenerator.cpp index e5d879e5e..9332d3c7a 100644 --- a/src/qdoc/xmlgenerator.cpp +++ b/src/qdoc/xmlgenerator.cpp @@ -313,7 +313,7 @@ QString XmlGenerator::linkForNode(const Node *node, const Node *relative) { if (node == nullptr) return QString(); - if (!node->url().isEmpty()) + if (!node->url().isNull()) return node->url(); if (fileBase(node).isEmpty()) return QString(); @@ -396,8 +396,7 @@ QString XmlGenerator::getLink(const Atom *atom, const Node *relative, const Node /*! This function is called for autolinks, i.e. for words that are not marked with the qdoc link command that qdoc has - reason to believe should be links. For links marked with - the qdoc link command, the getLink() function is called. + reason to believe should be links. It returns the string for a link found by using the data in the \a atom to search the database. It also sets \a node @@ -415,8 +414,11 @@ QString XmlGenerator::getAutoLink(const Atom *atom, const Node *relative, const return QString(); QString link = (*node)->url(); - if (link.isEmpty()) + if (link.isNull()) { link = linkForNode(*node, relative); + } else if (link.isEmpty()) { + return link; // Explicit empty url (node is ignored as a link target) + } if (!ref.isEmpty()) { int hashtag = link.lastIndexOf(QChar('#')); if (hashtag != -1) diff --git a/tests/auto/qdoc/generatedoutput/expected_output/crossmodule/testtype.html b/tests/auto/qdoc/generatedoutput/expected_output/crossmodule/testtype.html index aeed04895..19e7ce125 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/crossmodule/testtype.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/crossmodule/testtype.html @@ -43,6 +43,7 @@ <li><a href="testqdoc-testderived.html">TestQDoc::TestDerived</a></li> <li><a href="testqdoc-test.html">Test</a> class <a href="testqdoc.html#usage">Usage</a>.</li> <li><a href="testqdoc.html#QDOCTEST_MACRO">QDOCTEST_MACRO</a></li> +<li>DontLinkToMe</li> </ul> <a name="generated-lists"></a> <h3 id="generated-lists">Generated Lists</h3> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/first.html b/tests/auto/qdoc/generatedoutput/expected_output/first.html index 1e92e7067..566374eff 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/first.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/first.html @@ -3,7 +3,7 @@ <head> <meta charset="utf-8"> <!-- main.cpp --> - <title>First Class | TestModule</title> + <title>First Struct | TestModule</title> </head> <body> <li>First</li> @@ -11,15 +11,22 @@ <div class="toc"> <h3><a name="toc">Contents</a></h3> <ul> +<li class="level1"><a href="#public-types">Public Types</a></li> <li class="level1"><a href="#details">Detailed Description</a></li> </ul> </div> <div class="sidebar-content" id="sidebar-content"></div></div> -<h1 class="title">First Class</h1> +<h1 class="title">First Struct</h1> <div class="table"><table class="alignedsummary"> <tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include <First></span> </td></tr></table></div><ul> +<li><a href="first-members.html">List of all members, including inherited members</a></li> </ul> +<a name="public-types"></a> +<h2 id="public-types">Public Types</h2> +<div class="table"><table class="alignedsummary"> +<tr><td class="memItemLeft rightAlign topAlign"> class </td><td class="memItemRight bottomAlign"><b><a href="first-nested.html">Nested</a></b></td></tr> +</table></div> <a name="details"></a> <!-- $$$First-description --> <div class="descr"> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/html/first.webxml b/tests/auto/qdoc/generatedoutput/expected_output/html/first.webxml index b3dc9dffa..526bbbe73 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/html/first.webxml +++ b/tests/auto/qdoc/generatedoutput/expected_output/html/first.webxml @@ -1,15 +1,15 @@ <?xml version="1.0" encoding="UTF-8"?> <WebXML> <document> - <class name="First" href="first.html" status="active" access="public" location="bbb.h" documented="true" module="TestModule"> + <struct name="First" href="first.html" status="active" access="public" location="bbb.h" documented="true" module="TestModule"> <description> <para>This is a first class</para> </description> - <class name="Nested" fullname="First::Nested" href="first-nested.html" status="active" access="private" location="bbb.h" documented="true" module="TestModule"> + <class name="Nested" fullname="First::Nested" href="first-nested.html" status="active" access="public" location="bbb.h" documented="true" module="TestModule"> <description> <para>This is a nested class</para> </description> </class> - </class> + </struct> </document> </WebXML> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/index.html b/tests/auto/qdoc/generatedoutput/expected_output/index.html index cb5b7b6db..435f3d557 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/index.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/index.html @@ -12,7 +12,7 @@ <div class="descr"> <a name="details"></a> <div class="table"><table class="annotated"> <tr class="odd topAlign"><td class="tblName"><p><a href="first.html">First</a></p></td></tr> -<tr class="even topAlign"><td class="tblName"><p><a href="">First::Nested</a></p></td></tr> +<tr class="even topAlign"><td class="tblName"><p><a href="first-nested.html">First::Nested</a></p></td></tr> <tr class="odd topAlign"><td class="tblName"><p><a href="second.html">Second</a></p></td></tr> <tr class="even topAlign"><td class="tblName"><p><a href="third.html">Third</a></p></td></tr> </table></div> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/properties/testcpp.index b/tests/auto/qdoc/generatedoutput/expected_output/properties/testcpp.index index 853085e49..9f2bfacde 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/properties/testcpp.index +++ b/tests/auto/qdoc/generatedoutput/expected_output/properties/testcpp.index @@ -9,6 +9,7 @@ <page name="autolinking.html" href="autolinking.html" status="active" location="classlists.qdoc" documented="true" subtype="page" title="Autolinking" fulltitle="Autolinking" subtitle="" module="TestCPP"> <contents name="testqdoc" title="TestQDoc" level="1"/> </page> + <class name="DontLinkToMe" href="dontlinktome.html" status="ignored" access="public" location="testcpp.h" documented="true" module="TestCPP" brief="Class that does not generate documentation"/> <page name="obsolete-classes.html" href="obsolete-classes.html" status="active" location="classlists.qdoc" documented="true" subtype="page" title="Obsolete Classes" fulltitle="Obsolete Classes" subtitle="" module="TestCPP"> <contents name="classes-with-obsolete-members" title="Classes with obsolete members" level="1"/> <contents name="testqdoc" title="TestQDoc" level="2"/> @@ -96,6 +97,6 @@ </class> </namespace> <group name="testgroup" href="testgroup.html" status="internal" seen="false" title="" members="Test,QDOCTEST_MACRO2,someFunctionDefaultArg"/> - <module name="TestCPP" href="testcpp-module.html" status="active" documented="true" seen="true" title="QDoc Test C++ Classes" module="TestCPP" members="TestQDoc,Test,TestDerived" brief="A test module page"/> + <module name="TestCPP" href="testcpp-module.html" status="active" documented="true" seen="true" title="QDoc Test C++ Classes" module="TestCPP" members="TestQDoc,Test,TestDerived,DontLinkToMe" brief="A test module page"/> </namespace> </INDEX> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/testcpp.index b/tests/auto/qdoc/generatedoutput/expected_output/testcpp.index index 9f17e95d0..f81a3fc09 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/testcpp.index +++ b/tests/auto/qdoc/generatedoutput/expected_output/testcpp.index @@ -9,6 +9,7 @@ <page name="autolinking.html" href="autolinking.html" status="active" location="classlists.qdoc" documented="true" subtype="page" title="Autolinking" fulltitle="Autolinking" subtitle="" module="TestCPP"> <contents name="testqdoc" title="TestQDoc" level="1"/> </page> + <class name="DontLinkToMe" href="dontlinktome.html" status="ignored" access="public" location="testcpp.h" documented="true" module="TestCPP" brief="Class that does not generate documentation"/> <page name="obsolete-classes.html" href="obsolete-classes.html" status="active" location="classlists.qdoc" documented="true" subtype="page" title="Obsolete Classes" fulltitle="Obsolete Classes" subtitle="" module="TestCPP"> <contents name="classes-with-obsolete-members" title="Classes with obsolete members" level="1"/> <contents name="testqdoc" title="TestQDoc" level="2"/> @@ -59,6 +60,6 @@ </class> </namespace> <group name="testgroup" href="testgroup.html" status="internal" seen="false" title="" members="Test,QDOCTEST_MACRO2,someFunctionDefaultArg"/> - <module name="TestCPP" href="testcpp-module.html" status="active" documented="true" seen="true" title="QDoc Test C++ Classes" module="TestCPP" members="TestQDoc,Test,TestDerived" brief="A test module page"/> + <module name="TestCPP" href="testcpp-module.html" status="active" documented="true" seen="true" title="QDoc Test C++ Classes" module="TestCPP" members="TestQDoc,Test,TestDerived,DontLinkToMe" brief="A test module page"/> </namespace> </INDEX> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/testtagfile.tags b/tests/auto/qdoc/generatedoutput/expected_output/testtagfile.tags index 1e9a28a59..c5912acbe 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/testtagfile.tags +++ b/tests/auto/qdoc/generatedoutput/expected_output/testtagfile.tags @@ -15,7 +15,7 @@ <name>name</name> <anchorfile>qml-qdoc-test-abstractparent.html</anchorfile> <anchor>name-method</anchor> - <arglist>(Child child, name)</arglist> + <arglist>(Child child, name)</arglist> </member> <member kind="function" protection="public" virtualness="non" static="no"> <type>void</type> @@ -33,7 +33,7 @@ <name>name</name> <anchorfile>qml-qdoc-test-child.html</anchorfile> <anchor>name-method</anchor> - <arglist>(Child child, name)</arglist> + <arglist>(Child child, name)</arglist> </member> </compound> <compound kind="class"> @@ -58,21 +58,14 @@ <name>fail</name> <anchorfile>qml-qdoc-test-doctest.html</anchorfile> <anchor>fail-method</anchor> - <arglist>( message)</arglist> - </member> - <member kind="function" protection="public" virtualness="non" static="no"> - <type></type> - <name>doctest_fail</name> - <anchorfile>qml-qdoc-test-doctest.html</anchorfile> - <anchor>doctest_fail-method</anchor> - <arglist>( msg)</arglist> + <arglist>(message)</arglist> </member> <member kind="function" protection="public" virtualness="non" static="no"> <type></type> <name>fail_hard</name> <anchorfile>qml-qdoc-test-doctest.html</anchorfile> <anchor>fail_hard-method</anchor> - <arglist>( msg, option)</arglist> + <arglist>(msg, option)</arglist> </member> </compound> <compound kind="class"> @@ -89,24 +82,10 @@ <anchor>toggle-method</anchor> <arglist>()</arglist> </member> - <member kind="function" protection="public" virtualness="non" static="no"> - <type></type> - <name>releaseSwitch</name> - <anchorfile>qml-uicomponents-switch.html</anchorfile> - <anchor>releaseSwitch-method</anchor> - <arglist>()</arglist> - </member> </compound> <compound kind="class"> <name>UIComponents.TabWidget</name> <filename>qml-uicomponents-tabwidget.html</filename> - <member kind="function" protection="public" virtualness="non" static="no"> - <type></type> - <name>setOpacities</name> - <anchorfile>qml-uicomponents-tabwidget.html</anchorfile> - <anchor>setOpacities-method</anchor> - <arglist>()</arglist> - </member> </compound> <compound kind="namespace"> <name>TestQDoc</name> @@ -275,7 +254,7 @@ <name>copy</name> <anchorfile>qml-qdoc-test-type.html</anchorfile> <anchor>copy-method</anchor> - <arglist>( a)</arglist> + <arglist>(a)</arglist> </member> <member kind="function" protection="public" virtualness="non" static="no"> <type></type> diff --git a/tests/auto/qdoc/generatedoutput/testdata/bug80259/inc/testmodule/bbb.h b/tests/auto/qdoc/generatedoutput/testdata/bug80259/inc/testmodule/bbb.h index 0dc6e52c6..ac3706e55 100644 --- a/tests/auto/qdoc/generatedoutput/testdata/bug80259/inc/testmodule/bbb.h +++ b/tests/auto/qdoc/generatedoutput/testdata/bug80259/inc/testmodule/bbb.h @@ -1,5 +1,5 @@ #pragma once -class First +struct First { class Nested {}; }; diff --git a/tests/auto/qdoc/generatedoutput/testdata/crossmodule/testtype.cpp b/tests/auto/qdoc/generatedoutput/testdata/crossmodule/testtype.cpp index 411d957ab..98d3a1c8e 100644 --- a/tests/auto/qdoc/generatedoutput/testdata/crossmodule/testtype.cpp +++ b/tests/auto/qdoc/generatedoutput/testdata/crossmodule/testtype.cpp @@ -43,6 +43,7 @@ \li \l {TestQDoc::TestDerived} \li \l {TestQDoc::}{Test} class \l Usage. \li QDOCTEST_MACRO + \li DontLinkToMe \endlist \section1 Generated Lists diff --git a/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.cpp b/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.cpp index 51ae743db..0cdbf8f6f 100644 --- a/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.cpp +++ b/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.cpp @@ -288,3 +288,13 @@ void TestDerived::staticObsoleteMember() \endif */ } // namespace TestQDoc + +/*! + \class DontLinkToMe + \inmodule TestCPP + \brief Class that does not generate documentation. +*/ + +/*! + \dontdocument (DontLinkToMe) +*/ diff --git a/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.h b/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.h index 5fb323eed..355696528 100644 --- a/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.h +++ b/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.h @@ -131,3 +131,5 @@ using Vec = BaseVec<T>; #endif } // namespace TestQDoc + +class DontLinkToMe {}; |