Fix a number of qdoc warnings

- Remove obsolete functions and enumeration values
- Remove QObject * parameter from QMetaProperty accessors
- Fix renamed enumerations in QSsl
- Fix list items to be \li
- Fix function signatures and variable names

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

22 files changed, 25 insertions, 257 deletions

diff --git a/src/corelib/global/qnamespace.qdoc b/src/corelib/global/qnamespace.qdoc
index ad79e279be..b221a8c226 100644
--- a/src/corelib/global/qnamespace.qdoc
+++ b/src/corelib/global/qnamespace.qdoc
@@ -3246,6 +3246,7 @@
     \l {QEvent::MouseButtonDblClick}{MouseButtonDblClick} event from this event. The flag is set in the causing
     \l {QEvent::MouseButtonPress}{MouseButtonPress}, and not in the resulting \l {QEvent::MouseButtonDblClick}{MouseButtonDblClick}.
 
+    \omitvalue NoMouseEventFlag
     \omitvalue MouseEventFlagMask
 */
 
diff --git a/src/corelib/io/qfile.cpp b/src/corelib/io/qfile.cpp
index ac6a38b61c..90d6e30bd8 100644
--- a/src/corelib/io/qfile.cpp
+++ b/src/corelib/io/qfile.cpp
@@ -358,18 +358,6 @@ QFile::setFileName(const QString &name)
 */
 
 /*!
-    \typedef QFile::EncoderFn
-    \obsolete
-
-    This is a typedef for a pointer to a function with the following
-    signature:
-
-    \snippet code/src_corelib_io_qfile.cpp 1
-
-    \sa setEncodingFunction(), encodeName()
-*/
-
-/*!
     \fn QString QFile::decodeName(const QByteArray &localFileName)
 
     This does the reverse of QFile::encodeName() using \a localFileName.
@@ -378,39 +366,6 @@ QFile::setFileName(const QString &name)
 */
 
 /*!
-    \fn void QFile::setEncodingFunction(EncoderFn function)
-    \obsolete
-
-    This function does nothing. It is provided for compatibility with Qt 4 code
-    that attempted to set a different encoding function for file names. That
-    feature is flawed and no longer supported in Qt 5.
-
-    \sa encodeName(), setDecodingFunction()
-*/
-
-/*!
-    \typedef QFile::DecoderFn
-
-    This is a typedef for a pointer to a function with the following
-    signature:
-
-    \snippet code/src_corelib_io_qfile.cpp 2
-
-    \sa setDecodingFunction()
-*/
-
-/*!
-    \fn void QFile::setDecodingFunction(DecoderFn function)
-    \obsolete
-
-    This function does nothing. It is provided for compatibility with Qt 4 code
-    that attempted to set a different decoding function for file names. That
-    feature is flawed and no longer supported in Qt 5.
-
-    \sa setEncodingFunction(), decodeName()
-*/
-
-/*!
     \overload
 
     Returns \c true if the file specified by fileName() exists; otherwise
diff --git a/src/corelib/io/qstandardpaths.cpp b/src/corelib/io/qstandardpaths.cpp
index dff113de1e..c44905541b 100644
--- a/src/corelib/io/qstandardpaths.cpp
+++ b/src/corelib/io/qstandardpaths.cpp
@@ -590,10 +590,6 @@ QString QStandardPaths::displayName(StandardLocation type)
 #endif
 
 /*!
-  \fn void QStandardPaths::enableTestMode(bool testMode)
-  \obsolete Use QStandardPaths::setTestModeEnabled
- */
-/*!
   \fn void QStandardPaths::setTestModeEnabled(bool testMode)
 
   \include standardpath/functiondocs.qdocinc setTestModeEnabled
diff --git a/src/corelib/io/qurl.cpp b/src/corelib/io/qurl.cpp
index 615c814e91..105dfa358f 100644
--- a/src/corelib/io/qurl.cpp
+++ b/src/corelib/io/qurl.cpp
@@ -3013,27 +3013,6 @@ QByteArray QUrl::toPercentEncoding(const QString &input, const QByteArray &exclu
 }
 
 /*!
-    \fn QByteArray QUrl::toPunycode(const QString &uc)
-    \obsolete
-    Returns a \a uc in Punycode encoding.
-
-    Punycode is a Unicode encoding used for internationalized domain
-    names, as defined in RFC3492. If you want to convert a domain name from
-    Unicode to its ASCII-compatible representation, use toAce().
-*/
-
-/*!
-    \fn QString QUrl::fromPunycode(const QByteArray &pc)
-    \obsolete
-    Returns the Punycode decoded representation of \a pc.
-
-    Punycode is a Unicode encoding used for internationalized domain
-    names, as defined in RFC3492. If you want to convert a domain from
-    its ASCII-compatible encoding to the Unicode representation, use
-    fromAce().
-*/
-
-/*!
     \since 4.2
 
     Returns the Unicode form of the given domain name
diff --git a/src/corelib/kernel/qabstracteventdispatcher.cpp b/src/corelib/kernel/qabstracteventdispatcher.cpp
index 72504a178d..9f655a50d8 100644
--- a/src/corelib/kernel/qabstracteventdispatcher.cpp
+++ b/src/corelib/kernel/qabstracteventdispatcher.cpp
@@ -248,24 +248,6 @@ QAbstractEventDispatcher *QAbstractEventDispatcher::instance(QThread *thread)
 */
 
 /*!
-    \obsolete
-
-    \fn int QAbstractEventDispatcher::registerTimer(int interval, QObject *object)
-
-    Registers a timer with the specified \a interval for the given \a object
-    and returns the timer id.
-*/
-
-/*!
-    \obsolete
-
-    \fn void QAbstractEventDispatcher::registerTimer(int timerId, int interval, QObject *object)
-
-    Register a timer with the specified \a timerId and \a interval for the
-    given \a object.
-*/
-
-/*!
     Registers a timer with the specified \a interval and \a timerType for the
     given \a object and returns the timer id.
 */
@@ -495,15 +477,6 @@ bool QAbstractEventDispatcher::filterNativeEvent(const QByteArray &eventType, vo
     return false;
 }
 
-/*! \fn bool QAbstractEventDispatcher::filterEvent(void *message)
-    \deprecated
-
-    Calls filterNativeEvent() with an empty eventType and \a message.
-    This function returns \c true as soon as an
-    event filter returns \c true, and false otherwise to indicate that
-    the processing of the event should continue.
-*/
-
 /*! \fn bool QAbstractEventDispatcher::registerEventNotifier(QWinEventNotifier *notifier)
 
   This pure virtual method exists on windows only and has to be reimplemented by a Windows specific
diff --git a/src/corelib/kernel/qcoreapplication.cpp b/src/corelib/kernel/qcoreapplication.cpp
index 728ac6e7c1..303190ae69 100644
--- a/src/corelib/kernel/qcoreapplication.cpp
+++ b/src/corelib/kernel/qcoreapplication.cpp
@@ -1929,21 +1929,6 @@ bool QCoreApplication::event(QEvent *e)
     return QObject::event(e);
 }
 
-/*! \enum QCoreApplication::Encoding
-    \obsolete
-
-    This enum type used to define the 8-bit encoding of character string
-    arguments to translate(). This enum is now obsolete and UTF-8 will be
-    used in all cases.
-
-    \value UnicodeUTF8   UTF-8.
-    \omitvalue Latin1
-    \omitvalue DefaultCodec \omit UTF-8. \endomit
-    \omitvalue CodecForTr
-
-    \sa QObject::tr(), QString::fromUtf8()
-*/
-
 void QCoreApplicationPrivate::ref()
 {
     quitLockRef.ref();
@@ -2178,11 +2163,6 @@ QString QCoreApplication::translate(const char *context, const char *sourceText,
     return result;
 }
 
-/*! \fn static QString QCoreApplication::translate(const char *context, const char *key, const char *disambiguation, Encoding encoding, int n = -1)
-
-  \obsolete
-*/
-
 // Declared in qglobal.h
 QString qtTrId(const char *id, int n)
 {
diff --git a/src/corelib/kernel/qmetaobject.cpp b/src/corelib/kernel/qmetaobject.cpp
index 6cb43cea72..09297e4c2e 100644
--- a/src/corelib/kernel/qmetaobject.cpp
+++ b/src/corelib/kernel/qmetaobject.cpp
@@ -3389,12 +3389,8 @@ bool QMetaProperty::isWritable() const
 
 
 /*!
-    Returns \c true if this property is designable;
-    otherwise returns \c false.
-
-    If no \a object is given, the function returns \c false if the
-    \c{Q_PROPERTY()}'s \c DESIGNABLE attribute is false; otherwise
-    returns \c true.
+    Returns \c false if the \c{Q_PROPERTY()}'s \c DESIGNABLE attribute
+    is false; otherwise returns \c true.
 
     \sa isScriptable(), isStored()
 */
@@ -3406,12 +3402,8 @@ bool QMetaProperty::isDesignable() const
 }
 
 /*!
-    Returns \c true if the property is scriptable;
-    otherwise returns \c false.
-
-    If no \a object is given, the function returns \c false if the
-    \c{Q_PROPERTY()}'s \c SCRIPTABLE attribute is false; otherwise returns
-    true.
+    Returns \c false if the \c{Q_PROPERTY()}'s \c SCRIPTABLE attribute
+    is false; otherwise returns true.
 
     \sa isDesignable(), isStored()
 */
@@ -3440,15 +3432,10 @@ bool QMetaProperty::isStored() const
 }
 
 /*!
-    Returns \c true if this property is designated as the \c USER
-    property, i.e., the one that the user can edit or
-    that is significant in some other way.  Otherwise it returns
-    false. e.g., the \c text property is the \c USER editable property
-    of a QLineEdit.
-
-    If \a object is \nullptr, the function returns \c false if the \c
-    {Q_PROPERTY()}'s \c USER attribute is false. Otherwise it returns
-    true.
+    Returns \c false if the \c {Q_PROPERTY()}'s \c USER attribute is false.
+    Otherwise it returns true, indicating the property is designated as the
+    \c USER property, i.e., the one that the user can edit or
+    that is significant in some other way.
 
     \sa QMetaObject::userProperty(), isDesignable(), isScriptable()
 */
diff --git a/src/corelib/kernel/qobject.cpp b/src/corelib/kernel/qobject.cpp
index b26bd0298e..4a3356d810 100644
--- a/src/corelib/kernel/qobject.cpp
+++ b/src/corelib/kernel/qobject.cpp
@@ -2274,33 +2274,6 @@ void QObject::deleteLater()
     \sa QCoreApplication::translate(), {Internationalization with Qt}
 */
 
-/*!
-    \fn QString QObject::trUtf8(const char *sourceText, const char *disambiguation, int n)
-    \reentrant
-    \obsolete
-
-    Returns a translated version of \a sourceText, or
-    QString::fromUtf8(\a sourceText) if there is no appropriate
-    version. It is otherwise identical to tr(\a sourceText, \a
-    disambiguation, \a n).
-
-    \warning This method is reentrant only if all translators are
-    installed \e before calling this method. Installing or removing
-    translators while performing translations is not supported. Doing
-    so will probably result in crashes or other undesirable behavior.
-
-    \warning For portability reasons, we recommend that you use
-    escape sequences for specifying non-ASCII characters in string
-    literals to trUtf8(). For example:
-
-    \snippet code/src_corelib_kernel_qobject.cpp 20
-
-    \sa tr(), QCoreApplication::translate(), {Internationalization with Qt}
-*/
-
-
-
-
 /*****************************************************************************
   Signals and slots
  *****************************************************************************/
diff --git a/src/corelib/kernel/qvariant.cpp b/src/corelib/kernel/qvariant.cpp
index c0aea0e98d..bb37072dc8 100644
--- a/src/corelib/kernel/qvariant.cpp
+++ b/src/corelib/kernel/qvariant.cpp
@@ -3714,9 +3714,9 @@ bool QVariant::convert(const int type, void *ptr) const
     exceptions:
 
     \list
-    \i If both types are numeric types (integers and floatins point numbers)
+    \li If both types are numeric types (integers and floatins point numbers)
     Qt will compare those types using standard C++ type promotion rules.
-    \i If one type is numeric and the other one a QString, Qt will try to
+    \li If one type is numeric and the other one a QString, Qt will try to
     convert the QString to a matching numeric type and if successful compare
     those.
     \endlist
@@ -3735,9 +3735,9 @@ bool QVariant::convert(const int type, void *ptr) const
     exceptions:
 
     \list
-    \i If both types are numeric types (integers and floatins point numbers)
+    \li If both types are numeric types (integers and floatins point numbers)
     Qt will compare those types using standard C++ type promotion rules.
-    \i If one type is numeric and the other one a QString, Qt will try to
+    \li If one type is numeric and the other one a QString, Qt will try to
     convert the QString to a matching numeric type and if successful compare
     those.
     \endlist
diff --git a/src/corelib/text/qbytearray.cpp b/src/corelib/text/qbytearray.cpp
index b5327280f9..bcbbdc234f 100644
--- a/src/corelib/text/qbytearray.cpp
+++ b/src/corelib/text/qbytearray.cpp
@@ -2544,7 +2544,7 @@ qsizetype QtPrivate::count(QByteArrayView haystack, QByteArrayView needle) noexc
     return num;
 }
 
-/*! \fn int QByteArray::count(QByteArrayView &bv) const
+/*! \fn int QByteArray::count(const QByteArrayView &bv) const
     \since 6.0
 
     Returns the number of (potentially overlapping) occurrences of the
diff --git a/src/corelib/tools/qiterator.qdoc b/src/corelib/tools/qiterator.qdoc
index 49ee9ef00c..2c07dcf423 100644
--- a/src/corelib/tools/qiterator.qdoc
+++ b/src/corelib/tools/qiterator.qdoc
@@ -210,14 +210,6 @@
 */
 
 /*!
-    \class QVectorIterator
-    \inmodule QtCore
-    \brief QVectorIterator is an alias for QListIterator.
-
-    Please see the QListIterator documentation for details.
-*/
-
-/*!
     \class QSetIterator
     \inmodule QtCore
     \brief The QSetIterator class provides a Java-style const iterator for QSet.
@@ -331,14 +323,6 @@
 */
 
 /*!
-    \class QMutableVectorIterator
-    \inmodule QtCore
-    \brief QMutableVectorIterator is an alias for QMutableListIterator.
-
-    Please see the QMutableListIterator documentation for details.
-*/
-
-/*!
     \class QMutableSetIterator
     \inmodule QtCore
     \since 4.2
diff --git a/src/corelib/tools/qmargins.cpp b/src/corelib/tools/qmargins.cpp
index 2d7816e217..d914124280 100644
--- a/src/corelib/tools/qmargins.cpp
+++ b/src/corelib/tools/qmargins.cpp
@@ -663,7 +663,7 @@ QDebug operator<<(QDebug dbg, const QMargins &m)
 */
 
 /*!
-    \fn QMargins operator|(const QMargins &m1, const QMargins &m2)
+    \fn QMarginsF operator|(const QMarginsF &m1, const QMarginsF &m2)
     \relates QMarginsF
     \overload
 
diff --git a/src/gui/image/qbitmap.cpp b/src/gui/image/qbitmap.cpp
index 7ee3989684..58953e8d9a 100644
--- a/src/gui/image/qbitmap.cpp
+++ b/src/gui/image/qbitmap.cpp
@@ -194,17 +194,6 @@ QBitmap &QBitmap::operator=(const QPixmap &pixmap)
     return *this;
 }
 
-#if QT_VERSION < QT_VERSION_CHECK(6, 0, 0)
-
-/*!
-  Destroys the bitmap.
-*/
-QBitmap::~QBitmap()
-{
-}
-
-#endif
-
 /*!
     \fn void QBitmap::swap(QBitmap &other)
     \since 4.8
diff --git a/src/gui/image/qimage.cpp b/src/gui/image/qimage.cpp
index 4f00a03268..708f9f3146 100644
--- a/src/gui/image/qimage.cpp
+++ b/src/gui/image/qimage.cpp
@@ -1362,15 +1362,6 @@ int QImage::depth() const
 }
 
 /*!
-    \obsolete
-    \fn int QImage::numColors() const
-
-    Returns the size of the color table for the image.
-
-    \sa setColorCount()
-*/
-
-/*!
     \since 4.6
     \fn int QImage::colorCount() const
 
diff --git a/src/gui/painting/qpolygon.cpp b/src/gui/painting/qpolygon.cpp
index aa65fd5b99..24b696aafd 100644
--- a/src/gui/painting/qpolygon.cpp
+++ b/src/gui/painting/qpolygon.cpp
@@ -134,16 +134,7 @@ static void qt_polygon_isect_line(const QPointF &p1, const QPointF &p2, const QP
 */
 
 /*!
-    \fn QPolygon::QPolygon(int size)
-
-    Constructs a polygon of the given \a size. Creates an empty
-    polygon if \a size == 0.
-
-    \sa QList::isEmpty()
-*/
-
-/*!
-    \fn QPolygon::QPolygon(const QPolygon &polygon)
+    \fn QPolygon::QPolygon(const QPolygon &polygon) noexcept
 
     Constructs a copy of the given \a polygon.
 
@@ -197,14 +188,6 @@ QPolygon::QPolygon(int nPoints, const int *points)
     setPoints(nPoints, points);
 }
 
-
-/*!
-    \fn QPolygon::~QPolygon()
-
-    Destroys the polygon.
-*/
-
-
 /*!
     Translates all points in the polygon by (\a{dx}, \a{dy}).
 
@@ -532,7 +515,7 @@ QDebug operator<<(QDebug dbg, const QPolygon &a)
 */
 
 /*!
-    \fn QPolygonF::QPolygonF(const QPolygonF &polygon)
+    \fn QPolygonF::QPolygonF(const QPolygonF &polygon) noexcept
 
     Constructs a copy of the given \a polygon.
 */
@@ -581,13 +564,6 @@ QPolygonF::QPolygonF(const QPolygon &a)
 }
 
 /*!
-    \fn QPolygonF::~QPolygonF()
-
-    Destroys the polygon.
-*/
-
-
-/*!
     Translate all points in the polygon by the given \a offset.
 
     \sa translated()
diff --git a/src/gui/text/windows/qwindowsfontdatabase.cpp b/src/gui/text/windows/qwindowsfontdatabase.cpp
index 4db0043b7f..003d61d805 100644
--- a/src/gui/text/windows/qwindowsfontdatabase.cpp
+++ b/src/gui/text/windows/qwindowsfontdatabase.cpp
@@ -97,6 +97,7 @@ static inline bool useDirectWrite(QFont::HintingPreference hintingPreference,
 /*!
     \struct QWindowsFontEngineData
     \brief Static constant data shared by the font engines.
+    \internal
 */
 
 QWindowsFontEngineData::QWindowsFontEngineData()
diff --git a/src/network/ssl/qsslsocket.cpp b/src/network/ssl/qsslsocket.cpp
index 9d8fa035e2..ab4ce1527e 100644
--- a/src/network/ssl/qsslsocket.cpp
+++ b/src/network/ssl/qsslsocket.cpp
@@ -323,7 +323,7 @@
 */
 
 /*!
-    \fn void QSslSocket::alertSent(QAlertLevel level, QAlertType type, const QString &description)
+    \fn void QSslSocket::alertSent(QSsl::AlertLevel level, QSsl::AlertType type, const QString &description)
 
     QSslSocket emits this signal if an alert message was sent to a peer. \a level
     describes if it was a warning or a fatal error. \a type gives the code
@@ -334,11 +334,11 @@
     purposes, normally it does not require any actions from the application.
     \note Not all backends support this functionality.
 
-    \sa alertReceived(), QAlertLevel, QAlertType
+    \sa alertReceived(), QSsl::AlertLevel, QSsl::AlertType
 */
 
 /*!
-    \fn void QSslSocket::alertReceived(QAlertLevel level, QAlertType type, const QString &description)
+    \fn void QSslSocket::alertReceived(QSsl::AlertLevel level, QSsl::AlertType type, const QString &description)
 
     QSslSocket emits this signal if an alert message was received from a peer.
     \a level tells if the alert was fatal or it was a warning. \a type is the
@@ -350,7 +350,7 @@
     backend will handle it and close the connection.
     \note Not all backends support this functionality.
 
-    \sa alertSent(), QAlertLevel, QAlertType
+    \sa alertSent(), QSsl::AlertLevel, QSsl::AlertType
 */
 
 /*!
diff --git a/src/sql/kernel/qsqlerror.cpp b/src/sql/kernel/qsqlerror.cpp
index 478ca421d2..002e0dc076 100644
--- a/src/sql/kernel/qsqlerror.cpp
+++ b/src/sql/kernel/qsqlerror.cpp
@@ -90,15 +90,6 @@ public:
     \value UnknownError  Unknown error.
 */
 
-/*!
-    \fn QSqlError::QSqlError(const QString &driverText, const QString &databaseText, ErrorType type, int number)
-    \obsolete
-
-    Constructs an error containing the driver error text \a
-    driverText, the database-specific error text \a databaseText, the
-    type \a type and the optional error number \a number.
-*/
-
 /*! \fn QSqlError::QSqlError(QSqlError &&other)
     Move-constructs a QSqlError instance, making it point at the same
     object that \a other was pointing to.
diff --git a/src/widgets/dialogs/qfiledialog.cpp b/src/widgets/dialogs/qfiledialog.cpp
index 0a39217b99..bd58062375 100644
--- a/src/widgets/dialogs/qfiledialog.cpp
+++ b/src/widgets/dialogs/qfiledialog.cpp
@@ -239,12 +239,6 @@ Q_GLOBAL_STATIC(QUrl, lastVisitedDir)
     \value HideNameFilterDetails Indicates if the file name filter details are
     hidden or not.
 
-    \value DontUseSheet In previous versions of Qt, the static
-    functions would create a sheet by default if the static function
-    was given a parent. This is no longer supported and does nothing in Qt 4.5, The
-    static functions will always be an application modal dialog. If
-    you want to use sheets, use QFileDialog::open() instead.
-
     \value DontUseCustomDirectoryIcons Always use the default directory icon.
     Some platforms allow the user to set a different icon. Custom icon lookup
     cause a big performance impact over network or removable drives.
diff --git a/src/widgets/itemviews/qheaderview.cpp b/src/widgets/itemviews/qheaderview.cpp
index dd6dbab0c3..2e64918ac2 100644
--- a/src/widgets/itemviews/qheaderview.cpp
+++ b/src/widgets/itemviews/qheaderview.cpp
@@ -2833,7 +2833,7 @@ bool QHeaderView::viewportEvent(QEvent *e)
 }
 
 /*!
-    \fn void QHeaderView::initStyleOptionForIndex(QStyleOptionHeader *option, int logicalIndex)
+    \fn void QHeaderView::initStyleOptionForIndex(QStyleOptionHeader *option, int logicalIndex) const
     \since 6.0
 
     Initializes the style \a option from the specified \a logicalIndex.
diff --git a/src/widgets/kernel/qwidget.cpp b/src/widgets/kernel/qwidget.cpp
index 38f51e270e..29080dc863 100644
--- a/src/widgets/kernel/qwidget.cpp
+++ b/src/widgets/kernel/qwidget.cpp
@@ -2506,10 +2506,10 @@ QScreen *QWidget::screen() const
     window will get recreated on \a screen.
 
     \note If the screen is part of a virtual desktop of multiple screens,
-    the window will not move automatically to \a newScreen. To place the
+    the window will not move automatically to \a screen. To place the
     window relative to the screen, use the screen's topLeft() position.
 
-    \sa QWindow::setScreen
+    \sa QWindow::setScreen()
 */
 void QWidget::setScreen(QScreen *screen)
 {
diff --git a/src/widgets/styles/qstyle.cpp b/src/widgets/styles/qstyle.cpp
index a4fe0365f9..87d33c689f 100644
--- a/src/widgets/styles/qstyle.cpp
+++ b/src/widgets/styles/qstyle.cpp
@@ -637,8 +637,6 @@ void QStyle::drawItemPixmap(QPainter *painter, const QRect &rect, int alignment,
     primitive element is a common GUI element, such as a checkbox
     indicator or button bevel.
 
-    \omitvalue PE_IndicatorViewItemCheck
-
     \value PE_PanelButtonCommand  Button used to initiate an action, for
         example, a QPushButton.