Doc: Fix documentation warnings for Qt GUI

* Drop deprecation warnings for now-dropped items
* Use the 'qt6' define and a new \nothing doc macro to conditionally
  document items on Qt 6
* Add a custom module header for docs that pulls in also Vulkan headers
* Add \internal command for internal classes/functions
* Move QtGUI-related code snippets from widgets to gui docs

Change-Id: Ieb386b96631a49568d09059906d307c45c01d93a
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

6 files changed, 26 insertions, 35 deletions

diff --git a/src/gui/kernel/qaction.cpp b/src/gui/kernel/qaction.cpp
index 661ba53132..30100c3fcd 100644
--- a/src/gui/kernel/qaction.cpp
+++ b/src/gui/kernel/qaction.cpp
@@ -1108,7 +1108,7 @@ QVariant QAction::data() const
 }
 
 /*!
-  Sets the action's internal data to the given \a userData.
+  Sets the action's internal data to the given \a data.
 
   \sa data()
 */
diff --git a/src/gui/kernel/qopenglcontext.cpp b/src/gui/kernel/qopenglcontext.cpp
index 13fae561f8..81ab994f10 100644
--- a/src/gui/kernel/qopenglcontext.cpp
+++ b/src/gui/kernel/qopenglcontext.cpp
@@ -347,7 +347,7 @@ void QOpenGLContextPrivate::_q_screenDestroyed(QObject *object)
 }
 
 /*!
-    \fn template<typename T> T *QOpenGLContext::platformInterface<T>()
+    \fn template <typename T> T *QOpenGLContext::platformInterface() const
 
     Returns a platform interface of type T for the context.
 
diff --git a/src/gui/kernel/qplatformscreen.cpp b/src/gui/kernel/qplatformscreen.cpp
index b27792ae07..a89d4d007b 100644
--- a/src/gui/kernel/qplatformscreen.cpp
+++ b/src/gui/kernel/qplatformscreen.cpp
@@ -67,8 +67,6 @@ QPlatformScreen::~QPlatformScreen()
 }
 
 /*!
-    \fn QPixmap QPlatformScreen::grabWindow(WId window, int x, int y, int width, int height) const
-
     This function is called when Qt needs to be able to grab the content of a window.
 
     Returns the content of the window specified with the WId handle within the boundaries of
diff --git a/src/gui/kernel/qscreen.cpp b/src/gui/kernel/qscreen.cpp
index 1d11358b3d..7cc88af302 100644
--- a/src/gui/kernel/qscreen.cpp
+++ b/src/gui/kernel/qscreen.cpp
@@ -518,7 +518,7 @@ QRect QScreen::availableVirtualGeometry() const
     based on how it is being held; in that case, this \c orientation property
     will change.
 
-    \sa primaryOrientation(), QWindow::contentOrientation(), QOrientationSensor
+    \sa primaryOrientation(), QWindow::contentOrientation()
 */
 Qt::ScreenOrientation QScreen::orientation() const
 {
diff --git a/src/gui/kernel/qshortcut.cpp b/src/gui/kernel/qshortcut.cpp
index c4305d5a7f..b927f2435e 100644
--- a/src/gui/kernel/qshortcut.cpp
+++ b/src/gui/kernel/qshortcut.cpp
@@ -220,10 +220,7 @@ QShortcut::QShortcut(const QKeySequence &key, QObject *parent,
 
 
 /*!
-    \fn template<typename Functor>
-        QShortcut(const QKeySequence &key, QObject *parent,
-                  Functor functor,
-                  Qt::ShortcutContext shortcutContext = Qt::WindowShortcut);
+    \fn template<typename Functor> QShortcut::QShortcut(const QKeySequence &key, QObject *parent, Functor functor, Qt::ShortcutContext shortcutContext = Qt::WindowShortcut)
     \since 5.15
     \overload
 
@@ -231,10 +228,7 @@ QShortcut::QShortcut(const QKeySequence &key, QObject *parent,
     \l{QShortcut::activated()}{activated()} signal to the \a functor.
 */
 /*!
-    \fn template<typename Functor>
-        QShortcut(const QKeySequence &key, QObject *parent,
-                  const QObject *context, Functor functor,
-                  Qt::ShortcutContext shortcutContext = Qt::WindowShortcut);
+    \fn template<typename Functor> QShortcut::QShortcut(const QKeySequence &key, QObject *parent, const QObject *context, Functor functor, Qt::ShortcutContext shortcutContext = Qt::WindowShortcut)
     \since 5.15
     \overload
 
@@ -246,46 +240,38 @@ QShortcut::QShortcut(const QKeySequence &key, QObject *parent,
     If the \a context object is destroyed, the \a functor will not be called.
 */
 /*!
-    \fn template<typename Functor, typename FunctorAmbiguous>
-        QShortcut(const QKeySequence &key, QObject *parent,
-                  const QObject *context1, Functor functor,
-                  FunctorAmbiguous functorAmbiguous,
-                  Qt::ShortcutContext shortcutContext = Qt::WindowShortcut);
+    \fn template<typename Functor, typename FunctorAmbiguous> QShortcut::QShortcut(const QKeySequence &key, QObject *parent, const QObject *context, Functor functor, FunctorAmbiguous functorAmbiguous, Qt::ShortcutContext shortcutContext = Qt::WindowShortcut)
     \since 5.15
     \overload
 
     This is a QShortcut convenience constructor which connects the shortcut's
     \l{QShortcut::activated()}{activated()} signal to the \a functor and
     \l{QShortcut::activatedAmbiguously()}{activatedAmbiguously()}
-    signal to the \a FunctorAmbiguous.
+    signal to the \a functorAmbiguous.
 
-    The \a functor and \a FunctorAmbiguous can be a pointer to a member
+    The \a functor and \a functorAmbiguous can be a pointer to a member
     function of the \a context object.
 
     If the \a context object is destroyed, the \a functor and
-    \a FunctorAmbiguous will not be called.
+    \a functorAmbiguous will not be called.
 */
 /*!
-    \fn template<typename Functor, typename FunctorAmbiguous>
-        QShortcut(const QKeySequence &key, QObject *parent,
-                  const QObject *context1, Functor functor,
-                  const QObject *context2, FunctorAmbiguous functorAmbiguous,
-                  Qt::ShortcutContext shortcutContext = Qt::WindowShortcut);
+    \fn template<typename Functor, typename FunctorAmbiguous> QShortcut::QShortcut(const QKeySequence &key, QObject *parent, const QObject *context1, Functor functor, const QObject *context2, FunctorAmbiguous functorAmbiguous, Qt::ShortcutContext shortcutContext = Qt::WindowShortcut)
     \since 5.15
     \overload
 
     This is a QShortcut convenience constructor which connects the shortcut's
     \l{QShortcut::activated()}{activated()} signal to the \a functor and
     \l{QShortcut::activatedAmbiguously()}{activatedAmbiguously()}
-    signal to the \a FunctorAmbiguous.
+    signal to the \a functorAmbiguous.
 
     The \a functor can be a pointer to a member function of the
     \a context1 object.
-    The \a FunctorAmbiguous can be a pointer to a member function of the
+    The \a functorAmbiguous can be a pointer to a member function of the
     \a context2 object.
 
     If the \a context1 object is destroyed, the \a functor will not be called.
-    If the \a context2 object is destroyed, the \a FunctorAmbiguous
+    If the \a context2 object is destroyed, the \a functorAmbiguous
     will not be called.
 */
 
@@ -412,8 +398,7 @@ bool QShortcut::autoRepeat() const
 
 
 /*!
-    \property QShortcut::whatsThis
-    \brief the shortcut's "What's This?" help text
+    Sets the shortcut's "What's This?" help \a text.
 
     The text will be shown when a widget application is in "What's
     This?" mode and the user types the shortcut key() sequence.
@@ -421,9 +406,9 @@ bool QShortcut::autoRepeat() const
     To set "What's This?" help on a menu item (with or without a
     shortcut key), set the help on the item's action.
 
-    By default, this property contains an empty string.
+    By default, the help text is an empty string.
 
-    This property has no effect in applications that don't use
+    This function has no effect in applications that don't use
     widgets.
 
     \sa QWhatsThis::inWhatsThisMode(), QAction::setWhatsThis()
@@ -434,13 +419,17 @@ void QShortcut::setWhatsThis(const QString &text)
     d->sc_whatsthis = text;
 }
 
+/*!
+    Returns the shortcut's "What's This?" help text.
+
+    \sa setWhatsThis()
+*/
 QString QShortcut::whatsThis() const
 {
     Q_D(const QShortcut);
     return d->sc_whatsthis;
 }
 
-
 /*!
     Returns the shortcut's ID.
 
diff --git a/src/gui/kernel/qwindow.h b/src/gui/kernel/qwindow.h
index a82d2c3c05..6989d0bb63 100644
--- a/src/gui/kernel/qwindow.h
+++ b/src/gui/kernel/qwindow.h
@@ -107,7 +107,7 @@ class Q_GUI_EXPORT QWindow : public QObject, public QSurface
 
     // Any new properties which you add here MUST be versioned and MUST be documented both as
     // C++ properties in qwindow.cpp AND as QML properties in qquickwindow.cpp.
-    // http://qt-project.org/doc/qt-5.0/qtqml/qtqml-cppintegration-definetypes.html#type-revisions-and-versions
+    // https://doc.qt.io/qt/qtqml-cppintegration-definetypes.html#type-revisions-and-versions
 
     Q_PROPERTY(QString title READ title WRITE setTitle NOTIFY windowTitleChanged)
     Q_PROPERTY(Qt::WindowModality modality READ modality WRITE setModality NOTIFY modalityChanged)
@@ -125,7 +125,11 @@ class Q_GUI_EXPORT QWindow : public QObject, public QSurface
     Q_PROPERTY(Visibility visibility READ visibility WRITE setVisibility NOTIFY visibilityChanged REVISION(2, 1))
     Q_PROPERTY(Qt::ScreenOrientation contentOrientation READ contentOrientation WRITE reportContentOrientationChange NOTIFY contentOrientationChanged)
     Q_PROPERTY(qreal opacity READ opacity WRITE setOpacity NOTIFY opacityChanged REVISION(2, 1))
+#ifdef Q_QDOC
+    Q_PROPERTY(QWindow* transientParent READ transientParent WRITE setTransientParent NOTIFY transientParentChanged)
+#else
     Q_PRIVATE_PROPERTY(QWindow::d_func(), QWindow* transientParent MEMBER transientParent WRITE setTransientParent NOTIFY transientParentChanged REVISION(2, 13))
+#endif
 
 public:
     enum Visibility {