Doc: Fix documentation warnings for Qt GUI

- Remove obsolete dependencies and references.
- Restore previously deleted snippet code referenced in
  richtext.qdoc.
- Add widgets snippets path to exampledirs; some  classes
  were moved from QtWidgets to QtGUI and related \snippet
  commands were broken.
- Mark internal functions under QNativeInterface::Private
  as \internal.

Task-number: QTBUG-86295
Change-Id: I9c165c860c7191dac65972d702698a1745bff77f
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

15 files changed, 105 insertions, 27 deletions

diff --git a/src/gui/doc/qtgui.qdocconf b/src/gui/doc/qtgui.qdocconf
index cbde0ce92c..2ec3470d4c 100644
--- a/src/gui/doc/qtgui.qdocconf
+++ b/src/gui/doc/qtgui.qdocconf
@@ -36,8 +36,6 @@ tagfile                 = ../../../doc/qtgui/qtgui.tags
 depends += \
     qtcore \
     qtimageformats \
-    qtmacextras \
-    qtmultimedia \
     qtnetwork \
     qtopengl \
     qtprintsupport \
@@ -59,6 +57,7 @@ sourcedirs  += .. \
 
 exampledirs += ../../../examples/gui \
                ../../../examples/vulkan \
+               ../../widgets/doc/snippets \
                snippets
 
 imagedirs   += images \
diff --git a/src/gui/doc/snippets/textdocument-frames/mainwindow.cpp b/src/gui/doc/snippets/textdocument-frames/mainwindow.cpp
index 96b84fe61a..2608fb9f00 100644
--- a/src/gui/doc/snippets/textdocument-frames/mainwindow.cpp
+++ b/src/gui/doc/snippets/textdocument-frames/mainwindow.cpp
@@ -65,6 +65,12 @@ MainWindow::MainWindow()
     menuBar()->addMenu(fileMenu);
     editor = new QTextEdit;
 
+//! [rootframe]
+    QTextDocument *editorDocument = editor->document();
+    QTextFrame *root = editorDocument->rootFrame();
+//! [rootframe]
+    processFrame(root);
+
     QTextCursor cursor(editor->textCursor());
     cursor.movePosition(QTextCursor::Start);
 
@@ -151,3 +157,23 @@ void MainWindow::saveFile()
     }
 }
 
+void MainWindow::processBlock(QTextBlock)
+{
+}
+
+void MainWindow::processFrame(QTextFrame *frame)
+{
+//! [4]
+    QTextFrame::iterator it;
+    for (it = frame->begin(); !(it.atEnd()); ++it) {
+
+        QTextFrame *childFrame = it.currentFrame();
+        QTextBlock childBlock = it.currentBlock();
+
+        if (childFrame)
+            processFrame(childFrame);
+        else if (childBlock.isValid())
+            processBlock(childBlock);
+    }
+//! [4]
+}
diff --git a/src/gui/doc/snippets/textdocument-frames/mainwindow.h b/src/gui/doc/snippets/textdocument-frames/mainwindow.h
index 941138d0e9..40fa8e41e0 100644
--- a/src/gui/doc/snippets/textdocument-frames/mainwindow.h
+++ b/src/gui/doc/snippets/textdocument-frames/mainwindow.h
@@ -54,6 +54,8 @@
 #include <QMainWindow>
 
 class QTextEdit;
+class QTextFrame;
+class QTextBlock;
 
 class MainWindow : public QMainWindow
 {
@@ -67,6 +69,8 @@ public slots:
 
 private:
     bool writeXml(const QString &fileName);
+    void processBlock(QTextBlock);
+    void processFrame(QTextFrame *frame);
 
     QTextEdit *editor = nullptr;
 };
diff --git a/src/gui/doc/snippets/textdocument-tables/mainwindow.cpp b/src/gui/doc/snippets/textdocument-tables/mainwindow.cpp
index 7712362d57..ab00f43c2e 100644
--- a/src/gui/doc/snippets/textdocument-tables/mainwindow.cpp
+++ b/src/gui/doc/snippets/textdocument-tables/mainwindow.cpp
@@ -193,3 +193,35 @@ void MainWindow::showTable()
     tableWidget->show();
 }
 
+void MainWindow::processFrame(QTextFrame *)
+{
+}
+
+void MainWindow::processBlock(QTextBlock)
+{
+}
+
+void MainWindow::processTable(QTextTable *table)
+{
+    QTextFrame *frame = qobject_cast<QTextFrame *>(table);
+//! [13]
+    QTextFrame::iterator it;
+    for (it = frame->begin(); !(it.atEnd()); ++it) {
+
+        QTextFrame *childFrame = it.currentFrame();
+        QTextBlock childBlock = it.currentBlock();
+
+        if (childFrame) {
+            QTextTable *childTable = qobject_cast<QTextTable*>(childFrame);
+
+            if (childTable)
+                processTable(childTable);
+            else
+                processFrame(childFrame);
+
+        } else if (childBlock.isValid()) {
+            processBlock(childBlock);
+        }
+    }
+//! [13]
+}
diff --git a/src/gui/doc/snippets/textdocument-tables/mainwindow.h b/src/gui/doc/snippets/textdocument-tables/mainwindow.h
index b0ff5c1b91..37a7cc289d 100644
--- a/src/gui/doc/snippets/textdocument-tables/mainwindow.h
+++ b/src/gui/doc/snippets/textdocument-tables/mainwindow.h
@@ -53,6 +53,9 @@
 #include <QMainWindow>
 
 class QTextEdit;
+class QTextFrame;
+class QTextBlock;
+class QTextTable;
 
 class MainWindow : public QMainWindow
 {
@@ -67,6 +70,9 @@ public slots:
 
 private:
     bool writeXml(const QString &fileName);
+    void processFrame(QTextFrame *);
+    void processBlock(QTextBlock);
+    void processTable(QTextTable *table);
 
     QTextEdit *editor = nullptr;
 };
diff --git a/src/gui/doc/src/richtext.qdoc b/src/gui/doc/src/richtext.qdoc
index a963124849..4114067c66 100644
--- a/src/gui/doc/src/richtext.qdoc
+++ b/src/gui/doc/src/richtext.qdoc
@@ -179,8 +179,7 @@
 
     We obtain the root frame in the following manner:
 
-    \snippet textdocument-frames/xmlwriter.h 0
-    \snippet textdocument-frames/xmlwriter.cpp 0
+    \snippet textdocument-frames/mainwindow.cpp rootframe
 
     When navigating the document structure, it is useful to begin at the
     root frame because it provides access to the entire document structure.
@@ -266,8 +265,7 @@
     child frames. We can inspect the contents of a frame by using a
     QTextFrame::iterator to traverse the frame's child elements:
 
-    \snippet textdocument-frames/xmlwriter.cpp 1
-    \snippet textdocument-frames/xmlwriter.cpp 2
+    \snippet textdocument-frames/mainwindow.cpp 4
 
     Note that the iterator selects both frames and blocks, so it is necessary
     to check which it is referring to. This allows us to navigate the document
@@ -291,8 +289,7 @@
     document, we can test whether it represents a table, and deal with it in a
     different way:
 
-    \snippet textdocument-tables/xmlwriter.cpp 0
-    \snippet textdocument-tables/xmlwriter.cpp 1
+    \snippet textdocument-tables/mainwindow.cpp 13
 
     The cells within an existing table can be examined by iterating through
     the rows and columns.
diff --git a/src/gui/image/qimage_darwin.mm b/src/gui/image/qimage_darwin.mm
index 83b6cef980..e2ec52d2df 100644
--- a/src/gui/image/qimage_darwin.mm
+++ b/src/gui/image/qimage_darwin.mm
@@ -94,8 +94,6 @@ QT_BEGIN_NAMESPACE
     The CGImageRef color space is set to the sRGB color space.
 
     \ingroup platform-type-conversions
-
-    \sa QtMac::toNSImage()
 */
 CGImageRef QImage::toCGImage() const
 {
diff --git a/src/gui/image/qmovie.cpp b/src/gui/image/qmovie.cpp
index 79019d0fdf..096b4f6877 100644
--- a/src/gui/image/qmovie.cpp
+++ b/src/gui/image/qmovie.cpp
@@ -45,9 +45,7 @@
     \brief The QMovie class is a convenience class for playing movies
     with QImageReader.
 
-    This class is used to show simple animations without sound. If you want
-    to display video and media content, use the \l{Qt Multimedia}
-    multimedia framework instead.
+    This class is used to show simple animations without sound.
 
     First, create a QMovie object by passing either the name of a file or a
     pointer to a QIODevice containing an animated image format to QMovie's
diff --git a/src/gui/kernel/qaction.cpp b/src/gui/kernel/qaction.cpp
index d3a1c069f0..ec205a5012 100644
--- a/src/gui/kernel/qaction.cpp
+++ b/src/gui/kernel/qaction.cpp
@@ -206,7 +206,7 @@ QObject *QActionPrivate::menu() const
     menu and toolbar, then connected to the slot which will perform
     the action. For example:
 
-    \snippet mainwindows/application/mainwindow.cpp 19
+    \snippet ../widgets/mainwindows/application/mainwindow.cpp 19
 
     Actions are added to widgets using QWidget::addAction() or
     QGraphicsWidget::addAction(). Note that an action must be added to a
diff --git a/src/gui/kernel/qdrag.cpp b/src/gui/kernel/qdrag.cpp
index d6dfc6387c..330be0ac8a 100644
--- a/src/gui/kernel/qdrag.cpp
+++ b/src/gui/kernel/qdrag.cpp
@@ -99,9 +99,8 @@ QT_BEGIN_NAMESPACE
     \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()} to check whether a QDrag is
     required.
 
-    \sa {Drag and Drop}, QClipboard, QMimeData, QMacPasteboardMime,
-        {Draggable Icons Example}, {Draggable Text Example}, {Drop Site Example},
-        {Fridge Magnets Example}
+    \sa {Drag and Drop}, QClipboard, QMimeData, {Draggable Icons Example},
+        {Draggable Text Example}, {Drop Site Example}, {Fridge Magnets Example}
 */
 
 /*!
diff --git a/src/gui/kernel/qwindow.cpp b/src/gui/kernel/qwindow.cpp
index 546a90b2e9..544849a197 100644
--- a/src/gui/kernel/qwindow.cpp
+++ b/src/gui/kernel/qwindow.cpp
@@ -1187,7 +1187,7 @@ QRegion QWindow::mask() const
 /*!
     Requests the window to be activated, i.e. receive keyboard focus.
 
-    \sa isActive(), QGuiApplication::focusWindow(), QWindowsWindowFunctions::setWindowActivationBehavior()
+    \sa isActive(), QGuiApplication::focusWindow()
 */
 void QWindow::requestActivate()
 {
diff --git a/src/gui/math3d/qgenericmatrix.cpp b/src/gui/math3d/qgenericmatrix.cpp
index b144d132d0..cf79ed9786 100644
--- a/src/gui/math3d/qgenericmatrix.cpp
+++ b/src/gui/math3d/qgenericmatrix.cpp
@@ -177,8 +177,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn template<int NN, int M1, int M2, typename TT> QGenericMatrix<M1, M2, TT> operator*(const QGenericMatrix<NN, M2, TT>& m1, const QGenericMatrix<M1, NN, TT>& m2)
-    \relates QGenericMatrix
+    \fn template <int N, int M, typename T> template<int NN, int M1, int M2, typename TT> QGenericMatrix<M1, M2, TT> QGenericMatrix<N, M, T>::operator*(const QGenericMatrix<NN, M2, TT>& m1, const QGenericMatrix<M1, NN, TT>& m2)
 
     Returns the product of the NNxM2 matrix \a m1 and the M1xNN matrix \a m2
     to produce a M1xM2 matrix result.
diff --git a/src/gui/platform/macos/qcocoanativeinterface.mm b/src/gui/platform/macos/qcocoanativeinterface.mm
index 5d199f8a0f..f0c18a1bde 100644
--- a/src/gui/platform/macos/qcocoanativeinterface.mm
+++ b/src/gui/platform/macos/qcocoanativeinterface.mm
@@ -94,7 +94,8 @@ QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QCocoaMenuBar);
 
     \brief Adopts an NSOpenGLContext.
 
-    The adopted NSOpenGLContext is retained. Ownership of the created QOpenGLContext is transferred to the caller.
+    The adopted NSOpenGLContext \a context is retained. Ownership of the
+    created QOpenGLContext \a shareContext is transferred to the caller.
 */
 
 /*!
diff --git a/src/gui/platform/unix/qunixnativeinterface.cpp b/src/gui/platform/unix/qunixnativeinterface.cpp
index 43184daa12..a182fce182 100644
--- a/src/gui/platform/unix/qunixnativeinterface.cpp
+++ b/src/gui/platform/unix/qunixnativeinterface.cpp
@@ -72,11 +72,11 @@ using namespace QNativeInterface::Private;
 /*!
     \fn QOpenGLContext *QNativeInterface::QGLXContext::fromNative(GLXContext configBasedContext, QOpenGLContext *shareContext = nullptr)
 
-    \brief Adopts a GLXContext created from an FBConfig.
+    \brief Adopts a GLXContext \a configBasedContext created from an FBConfig.
 
     The context must be created from a framebuffer configuration, using the \c glXCreateNewContext function.
 
-    Ownership of the created QOpenGLContext is transferred to the caller.
+    Ownership of the created QOpenGLContext \a shareContext is transferred to the caller.
 */
 
 /*!
@@ -129,11 +129,12 @@ QOpenGLContext *QNativeInterface::QGLXContext::fromNative(GLXContext visualBased
 /*!
     \fn QOpenGLContext *QNativeInterface::QEGLContext::fromNative(EGLContext context, EGLDisplay display, QOpenGLContext *shareContext = nullptr)
 
-    \brief Adopts an EGLContext.
+    \brief Adopts an EGLContext \a context.
 
     The same \c EGLDisplay passed to \c eglCreateContext must be passed as the \a display argument.
 
-    Ownership of the created QOpenGLContext is transferred to the caller.
+    Ownership of the created QOpenGLContext \a shareContext is transferred
+    to the caller.
 */
 
 /*!
diff --git a/src/gui/platform/windows/qwindowsnativeinterface.cpp b/src/gui/platform/windows/qwindowsnativeinterface.cpp
index 700a3b34bf..cacfceeb7c 100644
--- a/src/gui/platform/windows/qwindowsnativeinterface.cpp
+++ b/src/gui/platform/windows/qwindowsnativeinterface.cpp
@@ -66,7 +66,7 @@ using namespace QNativeInterface::Private;
 /*!
     \fn QOpenGLContext *QNativeInterface::QWGLContext::fromNative(HGLRC context, HWND window, QOpenGLContext *shareContext = nullptr)
 
-    \brief Adopts an WGL context handle.
+    \brief Adopts an WGL \a context handle.
 
     The \a window is needed because the its pixel format will be queried. When the
     adoption is successful, QOpenGLContext::format() will return a QSurfaceFormat
@@ -76,7 +76,8 @@ using namespace QNativeInterface::Private;
     format compatible with the context's. If no SetPixelFormat() call was made on
     any device context belonging to the window, adopting the context will fail.
 
-    Ownership of the created QOpenGLContext is transferred to the caller.
+    Ownership of the created QOpenGLContext \a shareContext is transferred to the
+    caller.
 */
 
 /*!
@@ -133,12 +134,14 @@ QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QWindowsApplication);
 
 /*!
     \fn void QNativeInterface::Private::QWindowsApplication::setTouchWindowTouchType(QNativeInterface::Private::QWindowsApplication::TouchWindowTouchTypes type)
+    \internal
 
     Sets the touch window type for all windows to \a type.
 */
 
 /*!
     \fn QNativeInterface::Private::QWindowsApplication::TouchWindowTouchTypes QNativeInterface::Private::QWindowsApplication::touchWindowTouchType() const
+    \internal
 
     Returns the currently set the touch window type.
 */
@@ -161,6 +164,7 @@ QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QWindowsApplication);
 
 /*!
     \fn void QNativeInterface::Private::QWindowsApplication::setWindowActivationBehavior(QNativeInterface::Private::QWindowsApplication::WindowActivationBehavior behavior)
+    \internal
 
     Sets the window activation behavior to \a behavior.
 
@@ -169,12 +173,14 @@ QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QWindowsApplication);
 
 /*!
     \fn QNativeInterface::Private::QWindowsApplication::WindowActivationBehavior QNativeInterface::Private::QWindowsApplication::windowActivationBehavior() const
+    \internal
 
     Returns the currently set the window activation behavior.
 */
 
 /*!
     \fn bool QNativeInterface::Private::QWindowsApplication::isTabletMode() const
+    \internal
 
     Returns \c true if Windows 10 operates in \e{Tablet Mode}.
     In this mode, Windows forces all application main windows to open in maximized
@@ -199,6 +205,7 @@ QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QWindowsApplication);
 
 /*!
     \fn bool QNativeInterface::Private::QWindowsApplication::isDarkMode() const = 0
+    \internal
 
     Returns \c true if Windows 10 is configured to use dark mode for
     applications.
@@ -206,24 +213,28 @@ QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QWindowsApplication);
 
 /*!
     \fn void QNativeInterface::Private::QWindowsApplication::setDarkModeHandling(DarkModeHandling handling) = 0
+    \internal
 
     Sets the dark mode handling to \a handling.
 */
 
 /*!
     \fn QNativeInterface::Private::QWindowsApplication::DarkModeHandling QNativeInterface::Private::QWindowsApplication::darkModeHandling() const
+    \internal
 
     Returns the currently set dark mode handling.
 */
 
 /*!
     \fn bool QNativeInterface::Private::QWindowsApplication::isWinTabEnabled() const = 0
+    \internal
 
     Returns whether the \e{Tablet WinTab Driver} (\c Wintab32.dll) is used.
 */
 
 /*!
     \fn bool QNativeInterface::Private::QWindowsApplication::setWinTabEnabled(bool enabled)
+    \internal
 
     Sets whether the \e{Tablet WinTab Driver} (\c Wintab32.dll) should be used to \a enabled.
 
@@ -232,6 +243,7 @@ QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QWindowsApplication);
 
 /*!
     \fn bool QNativeInterface::Private::QWindowsApplication::registerMime(QWindowsMime *mime)
+    \internal
 
     Registers the converter \a mime to the system.
 
@@ -240,6 +252,7 @@ QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QWindowsApplication);
 
 /*!
     \fn void QNativeInterface::Private::QWindowsApplication::unregisterMime(QWindowsMime *mime)
+    \internal
 
     Unregisters the converter \a mime from the system.
 
@@ -248,6 +261,7 @@ QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QWindowsApplication);
 
 /*!
     \fn int QNativeInterface::Private::QWindowsApplication::registerMimeType(const QString &mime)
+    \internal
 
     Registers the MIME type \a mime, and returns an ID number
     identifying the format on Windows.
@@ -291,6 +305,7 @@ QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QWindowsWindow);
 
 /*!
     \fn void QNativeInterface::Private::QWindowsWindow::setHasBorderInFullScreen(bool border)
+    \internal
 
     Sets whether the WS_BORDER flag will be set for the window in full screen mode
     to \a border.
@@ -300,6 +315,7 @@ QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QWindowsWindow);
 
 /*!
     \fn bool QNativeInterface::Private::QWindowsWindow::hasBorderInFullScreen() const
+    \internal
 
     Returns whether the WS_BORDER flag will be set for the window in full screen
     mode.
@@ -307,12 +323,14 @@ QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QWindowsWindow);
 
 /*!
     \fn QMargins QNativeInterface::Private::QWindowsWindow::customMargins() const
+    \internal
 
     Returns the margin to be used when handling the \c WM_NCCALCSIZE message.
 */
 
 /*!
     \fn void QNativeInterface::Private::QWindowsWindow::setCustomMargins(const QMargins &margins)
+    \internal
 
     Sets the\a  margins to be used when handling the \c WM_NCCALCSIZE message. It is
     possible to remove a frame border by specifying a negative value.