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, 3 insertions, 0 deletions

diff --git a/src/qdoc/tree.h b/src/qdoc/tree.h
index e8a8f261e..2586f5c01 100644
--- a/src/qdoc/tree.h
+++ b/src/qdoc/tree.h
@@ -110,6 +110,8 @@ class Tree
     void setIndexTitle(const QString &t) { indexTitle_ = t; }
     NodeList &proxies() { return proxies_; }
     void appendProxy(ProxyNode *t) { proxies_.append(t); }
+    void addToDontDocumentMap(QString &arg);
+    void markDontDocumentNodes();
 
  private: // The rest of the class is private.
     Aggregate *findAggregate(const QString &name);
@@ -245,6 +247,7 @@ private:
     ExampleNodeMap          exampleNodeMap_;
     TargetListMap*          targetListMap_;
     NodeList proxies_;
+    NodeMap                 dontDocumentMap_;
 };
 
 QT_END_NAMESPACE