qdoc: Make QDoc warn about undocumented public classes

QDoc was marking all undocumented public API elements as
"internal" and "private" because most of these undocumented
elements should not be documented. The standard way to tell
QDoc not to warn about an undocumented elemewnt in the public
API is to give it a QDoc comment with the command "\internl"
in it. But it was decided this would require too much work
to eliminate all the warnings, because there are so many
undocumented elements in the Qt public API that we really
don't want to be documented. So we decided to just mark them
all as both internal and private in QDoc itself, and that
eliminated a great many useless QDoc warnings.

But it also meant that QDoc would no longer warn when a
public element was left undocumented by mistake. This is
most often seen in C++ classes that are in the public API
but are not documented. QFutureInterface is an example of
a class that is not documented but should be documented
because it is useful.

This change lets QDoc warn that a class in the public API
was not documented with a \class comment.

Special cases:
1. If the undocumented class has no members, don't warn that it was
not documented with a \class comment.
2. If the undocumented class's name contains the word "Private" it
is probably not meant to be in the public API, so don't warn that
it has no \class comment.
3. If the undocumented class has no function members, then don't
warn that it has no \class comment.
4. If the undocumented class is marked DontDocument, then don't
warn that it has no \class comment.

The other part of this change relates to item 4 above. To mark a
class or struct as DontDocument required adding a new topic
command to QDoc. The new topic command is \dontdocument. The
argument to this command is a list of class and struct names. The
list is enclosed in parentheses. For example:

\dontdocument (QMacAutoReleasePool QIncompatibleFlag
                ...
               QTextCodec::ConverterState QThreadStorageData)
QDoc looks up each name in the list and marks it DontDocument.
The documentation generator then sees the node is marked
DontDocument and ignores the node. This makes it a lot easier to
tell QDoc which public classes and structs should not generate
the warning about no documentation.

Task-number: QTBUG-57183
Change-Id: I7eee48de03ca7aeb72c63ae90ba373503d41612d
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

1 files changed, 43 insertions, 2 deletions

diff --git a/src/qdoc/tree.cpp b/src/qdoc/tree.cpp
index dff42d095..52ae4ca49 100644
--- a/src/qdoc/tree.cpp
+++ b/src/qdoc/tree.cpp
@@ -144,8 +144,7 @@ Node* Tree::findNodeForInclude(const QStringList& path) const
  */
 Aggregate *Tree::findAggregate(const QString &name)
 {
-    QStringList path;
-    path << name;
+    QStringList path = name.split(QLatin1String("::"));
     return static_cast<Aggregate*>(findNodeRecursive(path, 0, const_cast<NamespaceNode*>(root()), &Node::isFirstClassAggregate));
 }
 
@@ -1423,4 +1422,46 @@ FunctionNode *Tree::findMacroNode(const QString &t, const Aggregate *parent)
     return nullptr;
 }
 
+/*!
+  Add the class and struct names in \a arg to the \e {don't document}
+  map.
+ */
+void Tree::addToDontDocumentMap(QString &arg)
+{
+    arg.remove(QChar('('));
+    arg.remove(QChar(')'));
+    QString t = arg.simplified();
+    QStringList sl = t.split(QChar(' '));
+    if (sl.isEmpty())
+        return;
+    for (const QString& s : sl) {
+        if (!dontDocumentMap_.contains(s))
+            dontDocumentMap_.insert(s, nullptr);
+    }
+}
+
+/*!
+  The \e {don't document} map has been loaded with the names
+  of classes and structs in the current module that are not
+  documented and should not be documented. Now traverse the
+  map, and for each class or struct name, find the class node
+  that represents that class or struct and mark it with the
+  \C DontDocument status.
+
+  This results in a map of the class and struct nodes in the
+  module that are in the public API but are not meant to be
+  used by anyone. They are only used internally, but for one
+  reason or another, they must have public visibility.
+ */
+void Tree::markDontDocumentNodes()
+{
+    NodeMap::iterator i = dontDocumentMap_.begin();
+    while (i != dontDocumentMap_.end()) {
+        Aggregate* node = findAggregate(i.key());
+        if (node != nullptr)
+            node->setStatus(Node::DontDocument);
+        ++i;
+    }
+}
+
 QT_END_NAMESPACE