qdoc: Don't report error for things marked \internal

This change allows qdoc to avoid printing warnings about
a qdoc comment, if the comment contains the \internal
command. In these cases, the comment will not be
used in the documentation, so there is no point reporting
warnings about it. However, if the showinternal option is
used, warnings about comments marked internal are printed
anyway.

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

4 files changed, 34 insertions, 13 deletions

diff --git a/src/qdoc/clangcodeparser.cpp b/src/qdoc/clangcodeparser.cpp
index ee7897060..ccab4a08d 100644
--- a/src/qdoc/clangcodeparser.cpp
+++ b/src/qdoc/clangcodeparser.cpp
@@ -1050,7 +1050,7 @@ void ClangCodeParser::parseSourceFile(const Location& /*location*/, const QStrin
             if (n) {
                 nodes.append(n);
                 docs.append(doc);
-            } else {
+            } else if (CodeParser::isWorthWarningAbout(doc)) {
                 doc.location().warning(tr("Cannot tie this documentation to anything"),
                                        tr("I found a /*! ... */ comment, but there was no "
                                        "topic command (e.g., '\\%1', '\\%2') in the "
diff --git a/src/qdoc/codeparser.cpp b/src/qdoc/codeparser.cpp
index 83d2ddc4d..c344ad763 100644
--- a/src/qdoc/codeparser.cpp
+++ b/src/qdoc/codeparser.cpp
@@ -354,6 +354,21 @@ void CodeParser::setLink(Node* node, Node::LinkType linkType, const QString& arg
 }
 
 /*!
+  \brief Test for whether a doc comment warrants warnings.
+
+  Returns true if qdoc should report that it has found something
+  wrong with the qdoc comment in \a doc. Sometimes, qdoc should
+  not report the warning, for example, when the comment contains
+  the \c internal command, which normally means qdoc will not use
+  the comment in the documentation anyway, so there is no point
+  in reporting warnings about it.
+ */
+bool CodeParser::isWorthWarningAbout(const Doc &doc)
+{
+    return (showInternal_ || !doc.metaCommandsUsed().contains(QStringLiteral("internal")));
+}
+
+/*!
   Returns \c true if the file being parsed is a .h file.
  */
 bool CodeParser::isParsingH() const
diff --git a/src/qdoc/codeparser.h b/src/qdoc/codeparser.h
index 0ff7014a7..a8d03d8aa 100644
--- a/src/qdoc/codeparser.h
+++ b/src/qdoc/codeparser.h
@@ -66,6 +66,7 @@ public:
     static CodeParser *parserForHeaderFile(const QString &filePath);
     static CodeParser *parserForSourceFile(const QString &filePath);
     static void setLink(Node* node, Node::LinkType linkType, const QString& arg);
+    static bool isWorthWarningAbout(const Doc &doc);
 
 protected:
     const QSet<QString>& commonMetaCommands();
diff --git a/src/qdoc/cppcodeparser.cpp b/src/qdoc/cppcodeparser.cpp
index 3c21c8b1b..798b6e395 100644
--- a/src/qdoc/cppcodeparser.cpp
+++ b/src/qdoc/cppcodeparser.cpp
@@ -231,7 +231,9 @@ Node* CppCodeParser::processTopicCommand(const Doc& doc,
             if (func == 0)
                 func = qdb_->findNodeInOpenNamespace(parentPath, clone);
 
-            if (func == 0) {
+            if (func) {
+                lastPath_ = parentPath;
+            } else if (isWorthWarningAbout(doc)) {
                 doc.location().warning(tr("Cannot find '%1' in '\\%2' %3")
                                        .arg(clone->name() + "(...)")
                                        .arg(COMMAND_FN)
@@ -241,8 +243,6 @@ Node* CppCodeParser::processTopicCommand(const Doc& doc,
                                           "is identical to the declaration, including 'const' "
                                           "qualifiers."));
             }
-            else
-                lastPath_ = parentPath;
             if (func) {
                 func->borrowParameterNames(clone);
                 func->setParentPath(clone->parentPath());
@@ -306,8 +306,10 @@ Node* CppCodeParser::processTopicCommand(const Doc& doc,
         if (node == 0)
             node = qdb_->findNodeByNameAndType(path, type);
         if (node == 0) {
-            doc.location().warning(tr("Cannot find '%1' specified with '\\%2' in any header file")
-                                   .arg(arg.first).arg(command));
+            if (isWorthWarningAbout(doc)) {
+                doc.location().warning(tr("Cannot find '%1' specified with '\\%2' in any header file")
+                                       .arg(arg.first).arg(command));
+            }
             lastPath_ = path;
 
         }
@@ -798,11 +800,13 @@ void CppCodeParser::processOtherMetaCommand(const Doc& doc,
                 FunctionNode *func = (FunctionNode *) node;
                 const FunctionNode *from = func->reimplementedFrom();
                 if (from == 0) {
-                    doc.location().warning(tr("Cannot find base function for '\\%1' in %2()")
-                                           .arg(COMMAND_REIMP).arg(node->name()),
-                                           tr("The function either doesn't exist in any "
-                                              "base class with the same signature or it "
-                                              "exists but isn't virtual."));
+                    if (isWorthWarningAbout(doc)) {
+                        doc.location().warning(tr("Cannot find base function for '\\%1' in %2()")
+                                               .arg(COMMAND_REIMP).arg(node->name()),
+                                               tr("The function either doesn't exist in any "
+                                                  "base class with the same signature or it "
+                                                  "exists but isn't virtual."));
+                    }
                 }
                 /*
                   Ideally, we would enable this check to warn whenever
@@ -810,8 +814,9 @@ void CppCodeParser::processOtherMetaCommand(const Doc& doc,
                   internal if the function is a reimplementation of
                   another function in a base class.
                 */
-                else if (from->access() == Node::Private
-                         || from->parent()->access() == Node::Private) {
+                else if ((from->access() == Node::Private
+                          || from->parent()->access() == Node::Private)
+                         && isWorthWarningAbout(doc)) {
                     doc.location().warning(tr("'\\%1' in %2() should be '\\internal' "
                                               "because its base function is private "
                                               "or internal").arg(COMMAND_REIMP).arg(node->name()));