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>

9 files changed, 16 insertions, 27 deletions

diff --git a/src/gui/text/qfont.cpp b/src/gui/text/qfont.cpp
index 195904a4b1..2dd341f7c4 100644
--- a/src/gui/text/qfont.cpp
+++ b/src/gui/text/qfont.cpp
@@ -611,7 +611,7 @@ QFontEngineData::~QFontEngineData()
 */
 
 #if QT_VERSION < QT_VERSION_CHECK(6, 0, 0)
-/*!
+/*
   \obsolete
   Constructs a font from \a font for use on the paint device \a pd.
 */
@@ -1922,7 +1922,7 @@ void QFont::removeSubstitutions(const QString &familyName)
 /*!
     Returns a sorted list of substituted family names.
 
-    \sa insertSubstitution(), removeSubstitution(), substitute()
+    \sa insertSubstitution(), removeSubstitutions(), substitute()
 */
 QStringList QFont::substitutions()
 {
diff --git a/src/gui/text/qrawfont.cpp b/src/gui/text/qrawfont.cpp
index 6d9acf9bd4..36c94a080a 100644
--- a/src/gui/text/qrawfont.cpp
+++ b/src/gui/text/qrawfont.cpp
@@ -579,7 +579,7 @@ bool QRawFont::glyphIndexesForChars(const QChar *chars, int numChars, quint32 *g
    to make it appear as if the two glyphs are unspaced. How the advances are calculated is
    controlled by \a layoutFlags.
 
-   \sa QTextLine::horizontalAdvance(), QFontMetricsF::width()
+   \sa QTextLine::horizontalAdvance(), QFontMetricsF::horizontalAdvance()
 */
 
 /*!
@@ -592,7 +592,7 @@ bool QRawFont::glyphIndexesForChars(const QChar *chars, int numChars, quint32 *g
    to make it appear as if the two glyphs are unspaced. The advance of each glyph is calculated
    separately.
 
-   \sa QTextLine::horizontalAdvance(), QFontMetricsF::width()
+   \sa QTextLine::horizontalAdvance(), QFontMetricsF::horizontalAdvance()
 */
 
 /*!
@@ -604,7 +604,7 @@ bool QRawFont::glyphIndexesForChars(const QChar *chars, int numChars, quint32 *g
    array \a glyphIndexes while the results are returned through \a advances, both of them must
    have \a numGlyphs elements. How the advances are calculated is controlled by \a layoutFlags.
 
-   \sa QTextLine::horizontalAdvance(), QFontMetricsF::width()
+   \sa QTextLine::horizontalAdvance(), QFontMetricsF::horizontalAdvance()
 */
 bool QRawFont::advancesForGlyphIndexes(const quint32 *glyphIndexes, QPointF *advances, int numGlyphs, LayoutFlags layoutFlags) const
 {
@@ -640,7 +640,7 @@ bool QRawFont::advancesForGlyphIndexes(const quint32 *glyphIndexes, QPointF *adv
    array \a glyphIndexes while the results are returned through \a advances, both of them must
    have \a numGlyphs elements. The advance of each glyph is calculated separately
 
-   \sa QTextLine::horizontalAdvance(), QFontMetricsF::width()
+   \sa QTextLine::horizontalAdvance(), QFontMetricsF::horizontalAdvance()
 */
 bool QRawFont::advancesForGlyphIndexes(const quint32 *glyphIndexes, QPointF *advances, int numGlyphs) const
 {
diff --git a/src/gui/text/qstatictext.cpp b/src/gui/text/qstatictext.cpp
index a21eb95968..2d4fd5594d 100644
--- a/src/gui/text/qstatictext.cpp
+++ b/src/gui/text/qstatictext.cpp
@@ -207,7 +207,7 @@ void QStaticText::detach()
   making changes, you can use the prepare() function and pass in the \a matrix and \a font you
   expect to use when drawing the text.
 
-  \sa QPainter::setFont(), QPainter::setMatrix()
+  \sa QPainter::setFont(), QPainter::setWorldTransform()
 */
 void QStaticText::prepare(const QTransform &matrix, const QFont &font)
 {
diff --git a/src/gui/text/qtextdocumentfragment.cpp b/src/gui/text/qtextdocumentfragment.cpp
index 4344522a5d..6e7c5f1ed9 100644
--- a/src/gui/text/qtextdocumentfragment.cpp
+++ b/src/gui/text/qtextdocumentfragment.cpp
@@ -1257,15 +1257,6 @@ void QTextHtmlImporter::appendBlock(const QTextBlockFormat &format, QTextCharFor
 
 #endif // QT_NO_TEXTHTMLPARSER
 
-/*!
-    \fn QTextDocumentFragment QTextDocumentFragment::fromHtml(const QString &text)
-
-    Returns a QTextDocumentFragment based on the arbitrary piece of
-    HTML in the given \a text. The formatting is preserved as much as
-    possible; for example, "<b>bold</b>" will become a document
-    fragment with the text "bold" with a bold character format.
-*/
-
 #ifndef QT_NO_TEXTHTMLPARSER
 /*!
     \fn QTextDocumentFragment QTextDocumentFragment::fromHtml(const QString &text, const QTextDocument *resourceProvider)
diff --git a/src/gui/text/qtextlayout.cpp b/src/gui/text/qtextlayout.cpp
index 35dbf677a3..bec1f4a542 100644
--- a/src/gui/text/qtextlayout.cpp
+++ b/src/gui/text/qtextlayout.cpp
@@ -356,9 +356,13 @@ QTextLayout::QTextLayout(const QString& text)
 
 #if QT_VERSION < QT_VERSION_CHECK(6, 0, 0)
 /*!
+\if !defined(qt6)
     \fn QTextLayout::QTextLayout(const QString &text, const QFont &font, QPaintDevice *paintdevice)
     \obsolete
     Identical to QTextLayout::QTextLayout(const QString &text, const QFont &font, const QPaintDevice *paintdevice)
+\else
+    \nothing
+\endif
 */
 
 QTextLayout::QTextLayout(const QString &text, const QFont &font, QPaintDevice *paintdevice)
diff --git a/src/gui/text/qtextobject.cpp b/src/gui/text/qtextobject.cpp
index f7a7d25364..91e607ca0e 100644
--- a/src/gui/text/qtextobject.cpp
+++ b/src/gui/text/qtextobject.cpp
@@ -929,12 +929,6 @@ bool QTextBlock::isValid() const
 */
 
 /*!
-    \fn QTextBlock::iterator::iterator(const iterator &other)
-
-    Copy constructor. Constructs a copy of the \a other iterator.
-*/
-
-/*!
     \fn bool QTextBlock::iterator::atEnd() const
 
     Returns \c true if the current item is the last item in the text block.
diff --git a/src/gui/text/qtextoption.cpp b/src/gui/text/qtextoption.cpp
index 59b75d6a26..908e0f914a 100644
--- a/src/gui/text/qtextoption.cpp
+++ b/src/gui/text/qtextoption.cpp
@@ -156,7 +156,7 @@ void QTextOption::setTabArray(const QList<qreal> &tabStops)
     Sets the tab positions for the text layout to those specified by
     \a tabStops.
 
-    \sa tabStop()
+    \sa tabStopDistance()
 */
 void QTextOption::setTabs(const QList<QTextOption::Tab> &tabStops)
 {
@@ -168,7 +168,7 @@ void QTextOption::setTabs(const QList<QTextOption::Tab> &tabStops)
 /*!
     Returns a list of tab positions defined for the text layout.
 
-    \sa setTabArray(), tabStop()
+    \sa setTabArray(), tabStopDistance()
 */
 QList<qreal> QTextOption::tabArray() const
 {
diff --git a/src/gui/text/windows/qwindowsfontdatabase.cpp b/src/gui/text/windows/qwindowsfontdatabase.cpp
index f180e91e97..b5e0997015 100644
--- a/src/gui/text/windows/qwindowsfontdatabase.cpp
+++ b/src/gui/text/windows/qwindowsfontdatabase.cpp
@@ -95,7 +95,7 @@ static inline bool useDirectWrite(QFont::HintingPreference hintingPreference,
 #endif // !QT_NO_DIRECTWRITE
 
 /*!
-    \struct QWindowsFontEngineData
+    \class QWindowsFontEngineData
     \brief Static constant data shared by the font engines.
     \internal
 */
diff --git a/src/gui/text/windows/qwindowsfontdatabase_ft.cpp b/src/gui/text/windows/qwindowsfontdatabase_ft.cpp
index 91d3b5b74d..284b43a1bf 100644
--- a/src/gui/text/windows/qwindowsfontdatabase_ft.cpp
+++ b/src/gui/text/windows/qwindowsfontdatabase_ft.cpp
@@ -330,8 +330,8 @@ static int QT_WIN_CALLBACK storeFont(const LOGFONT *logFont, const TEXTMETRIC *t
     return 1;
 }
 
-/*!
-    \brief Populate font database using EnumFontFamiliesEx().
+/*
+    \brief Populates the font database using EnumFontFamiliesEx().
 
     Normally, leaving the name empty should enumerate
     all fonts, however, system fonts like "MS Shell Dlg 2"