qdoc: The \wrapper command is added

If \wrapper appears in a \class comment or a
\qmltype comment, qdoc will not print warnings
when it finds public members of the class or the
QML type that are not documented.

The \wrapper command is added to several
opengl classes. This reduces the number of
qdoc warnings by several thousands.

Task-number: QTBUG-30755
Change-Id: Iba1eebc1590ccf54100e40fe91423240c1b3d09d
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>
Reviewed-by: Venugopal Shivashankar <venugopal.shivashankar@digia.com>
Reviewed-by: Martin Smith <martin.smith@digia.com>
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

28 files changed, 56 insertions, 4 deletions

diff --git a/src/gui/opengl/qopenglfunctions_1_0.cpp b/src/gui/opengl/qopenglfunctions_1_0.cpp
index 84db0f2d65..b618dcb5cf 100644
--- a/src/gui/opengl/qopenglfunctions_1_0.cpp
+++ b/src/gui/opengl/qopenglfunctions_1_0.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_1_0
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_1_0 class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_1_1.cpp b/src/gui/opengl/qopenglfunctions_1_1.cpp
index b4860bcec7..bf032b5cf9 100644
--- a/src/gui/opengl/qopenglfunctions_1_1.cpp
+++ b/src/gui/opengl/qopenglfunctions_1_1.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_1_1
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_1_1 class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_1_2.cpp b/src/gui/opengl/qopenglfunctions_1_2.cpp
index 064980bebe..2b14900680 100644
--- a/src/gui/opengl/qopenglfunctions_1_2.cpp
+++ b/src/gui/opengl/qopenglfunctions_1_2.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_1_2
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_1_2 class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_1_3.cpp b/src/gui/opengl/qopenglfunctions_1_3.cpp
index ace7507e35..94605f8638 100644
--- a/src/gui/opengl/qopenglfunctions_1_3.cpp
+++ b/src/gui/opengl/qopenglfunctions_1_3.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_1_3
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_1_3 class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_1_4.cpp b/src/gui/opengl/qopenglfunctions_1_4.cpp
index a27b81d6d8..e3035eeb55 100644
--- a/src/gui/opengl/qopenglfunctions_1_4.cpp
+++ b/src/gui/opengl/qopenglfunctions_1_4.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_1_4
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_1_4 class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_1_5.cpp b/src/gui/opengl/qopenglfunctions_1_5.cpp
index ceb004b02c..581ed14aac 100644
--- a/src/gui/opengl/qopenglfunctions_1_5.cpp
+++ b/src/gui/opengl/qopenglfunctions_1_5.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_1_5
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_1_5 class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_2_0.cpp b/src/gui/opengl/qopenglfunctions_2_0.cpp
index 15c042177d..2736d4a030 100644
--- a/src/gui/opengl/qopenglfunctions_2_0.cpp
+++ b/src/gui/opengl/qopenglfunctions_2_0.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_2_0
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_2_0 class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_2_1.cpp b/src/gui/opengl/qopenglfunctions_2_1.cpp
index 143ac206ed..ed94131e33 100644
--- a/src/gui/opengl/qopenglfunctions_2_1.cpp
+++ b/src/gui/opengl/qopenglfunctions_2_1.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_2_1
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_2_1 class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_3_0.cpp b/src/gui/opengl/qopenglfunctions_3_0.cpp
index e13122e683..e80235b957 100644
--- a/src/gui/opengl/qopenglfunctions_3_0.cpp
+++ b/src/gui/opengl/qopenglfunctions_3_0.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_3_0
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_3_0 class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_3_1.cpp b/src/gui/opengl/qopenglfunctions_3_1.cpp
index 104029177c..ab48658bfc 100644
--- a/src/gui/opengl/qopenglfunctions_3_1.cpp
+++ b/src/gui/opengl/qopenglfunctions_3_1.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_3_1
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_3_1 class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_3_2_compatibility.cpp b/src/gui/opengl/qopenglfunctions_3_2_compatibility.cpp
index f808f2e6dd..171b7454f4 100644
--- a/src/gui/opengl/qopenglfunctions_3_2_compatibility.cpp
+++ b/src/gui/opengl/qopenglfunctions_3_2_compatibility.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_3_2_Compatibility
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_3_2_Compatibility class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_3_2_core.cpp b/src/gui/opengl/qopenglfunctions_3_2_core.cpp
index 0e1af4c28b..48dec29962 100644
--- a/src/gui/opengl/qopenglfunctions_3_2_core.cpp
+++ b/src/gui/opengl/qopenglfunctions_3_2_core.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_3_2_Core
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_3_2_Core class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_3_3_compatibility.cpp b/src/gui/opengl/qopenglfunctions_3_3_compatibility.cpp
index aa53b7d03b..8bebc7d0bc 100644
--- a/src/gui/opengl/qopenglfunctions_3_3_compatibility.cpp
+++ b/src/gui/opengl/qopenglfunctions_3_3_compatibility.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_3_3_Compatibility
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_3_3_Compatibility class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_3_3_core.cpp b/src/gui/opengl/qopenglfunctions_3_3_core.cpp
index d355a466c1..941f9c38b6 100644
--- a/src/gui/opengl/qopenglfunctions_3_3_core.cpp
+++ b/src/gui/opengl/qopenglfunctions_3_3_core.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_3_3_Core
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_3_3_Core class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_4_0_compatibility.cpp b/src/gui/opengl/qopenglfunctions_4_0_compatibility.cpp
index af5d3eccc1..7ab0688084 100644
--- a/src/gui/opengl/qopenglfunctions_4_0_compatibility.cpp
+++ b/src/gui/opengl/qopenglfunctions_4_0_compatibility.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_4_0_Compatibility
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_4_0_Compatibility class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_4_0_core.cpp b/src/gui/opengl/qopenglfunctions_4_0_core.cpp
index b018531b37..a4bf66a44b 100644
--- a/src/gui/opengl/qopenglfunctions_4_0_core.cpp
+++ b/src/gui/opengl/qopenglfunctions_4_0_core.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_4_0_Core
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_4_0_Core class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_4_1_compatibility.cpp b/src/gui/opengl/qopenglfunctions_4_1_compatibility.cpp
index 27c90adc5a..a0ea4a052a 100644
--- a/src/gui/opengl/qopenglfunctions_4_1_compatibility.cpp
+++ b/src/gui/opengl/qopenglfunctions_4_1_compatibility.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_4_1_Compatibility
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_4_1_Compatibility class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_4_2_compatibility.cpp b/src/gui/opengl/qopenglfunctions_4_2_compatibility.cpp
index a415b24f33..6d19fff92b 100644
--- a/src/gui/opengl/qopenglfunctions_4_2_compatibility.cpp
+++ b/src/gui/opengl/qopenglfunctions_4_2_compatibility.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_4_2_Compatibility
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_4_2_Compatibility class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_4_2_core.cpp b/src/gui/opengl/qopenglfunctions_4_2_core.cpp
index 3600c20a41..51ba3e8097 100644
--- a/src/gui/opengl/qopenglfunctions_4_2_core.cpp
+++ b/src/gui/opengl/qopenglfunctions_4_2_core.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_4_2_Core
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_4_2_Core class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_4_3_compatibility.cpp b/src/gui/opengl/qopenglfunctions_4_3_compatibility.cpp
index 75bcef1562..de6cc185c6 100644
--- a/src/gui/opengl/qopenglfunctions_4_3_compatibility.cpp
+++ b/src/gui/opengl/qopenglfunctions_4_3_compatibility.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_4_3_Compatibility
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_4_3_Compatibility class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_4_3_core.cpp b/src/gui/opengl/qopenglfunctions_4_3_core.cpp
index bfe1bcc9c4..29fc8368aa 100644
--- a/src/gui/opengl/qopenglfunctions_4_3_core.cpp
+++ b/src/gui/opengl/qopenglfunctions_4_3_core.cpp
@@ -57,6 +57,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_4_3_Core
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_4_3_Core class provides all functions for this version and profile of OpenGL.
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/gui/opengl/qopenglfunctions_es2.cpp b/src/gui/opengl/qopenglfunctions_es2.cpp
index afac017d53..20a4b50994 100644
--- a/src/gui/opengl/qopenglfunctions_es2.cpp
+++ b/src/gui/opengl/qopenglfunctions_es2.cpp
@@ -48,6 +48,7 @@ QT_BEGIN_NAMESPACE
     \class QOpenGLFunctions_ES2
     \inmodule QtGui
     \since 5.1
+    \wrapper
     \brief The QOpenGLFunctions_ES2 class provides all functions for OpenGL ES 2
 
     \sa QAbstractOpenGLFunctions
diff --git a/src/tools/qdoc/codeparser.cpp b/src/tools/qdoc/codeparser.cpp
index 557a6f08fa..7b534a6c95 100644
--- a/src/tools/qdoc/codeparser.cpp
+++ b/src/tools/qdoc/codeparser.cpp
@@ -70,6 +70,7 @@ QT_BEGIN_NAMESPACE
 #define COMMAND_SUBTITLE                Doc::alias(QLatin1String("subtitle"))
 #define COMMAND_THREADSAFE              Doc::alias(QLatin1String("threadsafe"))
 #define COMMAND_TITLE                   Doc::alias(QLatin1String("title"))
+#define COMMAND_WRAPPER                 Doc::alias(QLatin1String("wrapper"))
 
 QString CodeParser::currentSubDir_;
 QList<CodeParser *> CodeParser::parsers;
@@ -219,7 +220,8 @@ QSet<QString> CodeParser::commonMetaCommands()
                            << COMMAND_SINCE
                            << COMMAND_SUBTITLE
                            << COMMAND_THREADSAFE
-                           << COMMAND_TITLE;
+                           << COMMAND_TITLE
+                           << COMMAND_WRAPPER;
 }
 
 /*!
@@ -286,6 +288,9 @@ void CodeParser::processCommonMetaCommand(const Location& location,
     else if (command == COMMAND_SINCE) {
         node->setSince(arg.first);
     }
+    else if (command == COMMAND_WRAPPER) {
+        node->setWrapper();
+    }
     else if (command == COMMAND_PAGEKEYWORDS) {
         node->addPageKeywords(arg.first);
     }
diff --git a/src/tools/qdoc/generator.cpp b/src/tools/qdoc/generator.cpp
index dfa49e8563..81be63abe1 100644
--- a/src/tools/qdoc/generator.cpp
+++ b/src/tools/qdoc/generator.cpp
@@ -654,7 +654,7 @@ void Generator::generateBody(const Node *node, CodeMarker *marker)
         }
     }
     if (node->doc().isEmpty()) {
-        if (!quiet && !node->isReimp()) { // ### might be unnecessary
+        if (!node->isWrapper() && !quiet && !node->isReimp()) { // ### might be unnecessary
             node->location().warning(tr("No documentation for '%1'").arg(node->plainFullName()));
         }
     }
diff --git a/src/tools/qdoc/node.cpp b/src/tools/qdoc/node.cpp
index 028c0a0b2a..e627cf859e 100644
--- a/src/tools/qdoc/node.cpp
+++ b/src/tools/qdoc/node.cpp
@@ -1079,6 +1079,16 @@ void InnerNode::deleteChildren()
  */
 
 /*!
+  Returns true if the node is a class node or a QML type node
+  that is marked as being a wrapper class or QML type, or if
+  it is a member of a wrapper class or type.
+ */
+bool Node::isWrapper() const
+{
+    return (parent_ ? parent_->isWrapper() : false);
+}
+
+/*!
  */
 const Node *InnerNode::findChildNodeByName(const QString& name) const
 {
@@ -1441,6 +1451,7 @@ ClassNode::ClassNode(InnerNode *parent, const QString& name)
     : InnerNode(Class, parent, name)
 {
     abstract_ = false;
+    wrapper_ = false;
     qmlelement = 0;
     setPageType(ApiPage);
 }
@@ -2105,6 +2116,7 @@ QmlClassNode::QmlClassNode(InnerNode *parent, const QString& name)
     : DocNode(parent, name, QmlClass, Node::ApiPage),
       abstract_(false),
       cnodeRequired_(false),
+      wrapper_(false),
       cnode_(0),
       baseNode_(0)
 {
diff --git a/src/tools/qdoc/node.h b/src/tools/qdoc/node.h
index d1a95358f0..326146a962 100644
--- a/src/tools/qdoc/node.h
+++ b/src/tools/qdoc/node.h
@@ -200,11 +200,13 @@ public:
     virtual bool isCollisionNode() const { return false; }
     virtual bool isAttached() const { return false; }
     virtual bool isGroup() const { return false; }
+    virtual bool isWrapper() const;
     virtual void addMember(Node* ) { }
     virtual bool hasMembers() const { return false; }
     virtual bool hasNamespaces() const { return false; }
     virtual bool hasClasses() const { return false; }
     virtual void setAbstract(bool ) { }
+    virtual void setWrapper() { }
     virtual QString title() const { return QString(); }
     virtual bool hasProperty(const QString& ) const { return false; }
     virtual void getMemberNamespaces(NodeMap& ) { }
@@ -437,8 +439,10 @@ public:
     ClassNode(InnerNode* parent, const QString& name);
     virtual ~ClassNode() { }
     virtual bool isClass() const { return true; }
+    virtual bool isWrapper() const { return wrapper_; }
     virtual QString obsoleteLink() const { return obsoleteLink_; }
     virtual void setObsoleteLink(const QString& t) { obsoleteLink_ = t; };
+    virtual void setWrapper() { wrapper_ = true; }
 
     void addBaseClass(Access access,
                       ClassNode* node,
@@ -463,6 +467,7 @@ private:
     QList<RelatedClass> derived;
     QList<RelatedClass> ignoredBases;
     bool abstract_;
+    bool wrapper_;
     QString sname;
     QString obsoleteLink_;
     QmlClassNode* qmlelement;
@@ -568,7 +573,9 @@ public:
     virtual void setCurrentChild();
     virtual void clearCurrentChild();
     virtual bool isAbstract() const { return abstract_; }
+    virtual bool isWrapper() const { return wrapper_; }
     virtual void setAbstract(bool b) { abstract_ = b; }
+    virtual void setWrapper() { wrapper_ = true; }
     virtual bool isInternal() const { return (status() == Internal); }
     virtual QString qmlFullBaseName() const;
     virtual QString obsoleteLink() const { return obsoleteLink_; }
@@ -592,6 +599,7 @@ public:
 private:
     bool abstract_;
     bool cnodeRequired_;
+    bool wrapper_;
     ClassNode*    cnode_;
     QString      baseName_;
     QString             obsoleteLink_;
diff --git a/src/tools/qdoc/qmlcodeparser.cpp b/src/tools/qdoc/qmlcodeparser.cpp
index c86982eb95..b9c0ad9218 100644
--- a/src/tools/qdoc/qmlcodeparser.cpp
+++ b/src/tools/qdoc/qmlcodeparser.cpp
@@ -63,6 +63,7 @@ QT_BEGIN_NAMESPACE
 #define COMMAND_PAGEKEYWORDS            Doc::alias("pagekeywords")
 #define COMMAND_PRELIMINARY             Doc::alias("preliminary")
 #define COMMAND_SINCE                   Doc::alias("since")
+#define COMMAND_WRAPPER                 Doc::alias("wrapper")
 
 #define COMMAND_QMLABSTRACT             Doc::alias("qmlabstract")
 #define COMMAND_QMLCLASS                Doc::alias("qmlclass")
@@ -228,8 +229,8 @@ QSet<QString> QmlCodeParser::otherMetaCommands()
                                 << COMMAND_PRELIMINARY
                                 << COMMAND_SINCE
                                 << COMMAND_QMLABSTRACT
-                                << COMMAND_INQMLMODULE;
-
+                                << COMMAND_INQMLMODULE
+                                << COMMAND_WRAPPER;
 }
 
 /*!
diff --git a/src/tools/qdoc/qmlvisitor.cpp b/src/tools/qdoc/qmlvisitor.cpp
index ac659720b2..86b86c8f34 100644
--- a/src/tools/qdoc/qmlvisitor.cpp
+++ b/src/tools/qdoc/qmlvisitor.cpp
@@ -60,6 +60,7 @@ QT_BEGIN_NAMESPACE
 #define COMMAND_PAGEKEYWORDS            Doc::alias(QLatin1String("pagekeywords"))
 #define COMMAND_PRELIMINARY             Doc::alias(QLatin1String("preliminary"))
 #define COMMAND_SINCE                   Doc::alias(QLatin1String("since"))
+#define COMMAND_WRAPPER                 Doc::alias(QLatin1String("wrapper"))
 
 #define COMMAND_QMLABSTRACT             Doc::alias(QLatin1String("qmlabstract"))
 #define COMMAND_QMLCLASS                Doc::alias(QLatin1String("qmlclass"))
@@ -367,6 +368,9 @@ void QmlDocVisitor::applyMetacommands(QQmlJS::AST::SourceLocation,
                 QString arg = args[0].first; //.join(' ');
                 node->setSince(arg);
             }
+            else if (command == COMMAND_WRAPPER) {
+                node->setWrapper();
+            }
             else {
                 doc.location().warning(tr("The \\%1 command is ignored in QML files").arg(command));
             }