Doc: Fix documentation issues for Qt WebEngine

API and documentation changes since 5.15 caused multiple warnings from
QDoc; this change addresses most of them. Some warnings indicate
missing documentation, those issues still remain.

Change-Id: I96be38b7daac37a7e35c149b4b3ec3f18c4415c9
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit c248844b3b8ee004800606d1a6c6e6d6bee31738)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

11 files changed, 48 insertions, 67 deletions

diff --git a/src/core/api/qwebenginecertificateerror.cpp b/src/core/api/qwebenginecertificateerror.cpp
index 40c9a1c7b..e20b55f81 100644
--- a/src/core/api/qwebenginecertificateerror.cpp
+++ b/src/core/api/qwebenginecertificateerror.cpp
@@ -99,12 +99,14 @@ QWebEngineCertificateError::~QWebEngineCertificateError() = default;
             used for interception by an entity other the device owner. (Added in
             5.15)
     \value SslObsoleteVersion The connection uses an obsolete version of SSL/TLS. (Added in Qt 6.0)
+    \value CertificateSymantecLegacy The certificate is a legacy Symantec one that's no longer valid. (Added in Qt 6.0)
 */
 
 /*!
-    Returns whether this error can be overridden and accepted.
+    \property QWebEngineCertificateError::overridable
+    \brief Whether this error can be overridden and accepted.
 
-    \sa error(), description()
+    \sa description()
 */
 bool QWebEngineCertificateError::isOverridable() const
 {
@@ -114,7 +116,7 @@ bool QWebEngineCertificateError::isOverridable() const
 /*!
     Returns the URL that triggered the error.
 
-    \sa error(), description()
+    \sa description()
 */
 QUrl QWebEngineCertificateError::url() const
 {
@@ -134,7 +136,7 @@ QWebEngineCertificateError::Type QWebEngineCertificateError::type() const
 /*!
     Returns a short localized human-readable description of the error.
 
-    \sa error(), url(), isOverridable()
+    \sa url(), isOverridable()
 */
 QString QWebEngineCertificateError::description() const
 {
@@ -152,7 +154,7 @@ QString QWebEngineCertificateError::description() const
 
     \note It is only possible to defer overridable certificate errors.
 
-    \sa isOverridable(), deferred()
+    \sa isOverridable()
 */
 void QWebEngineCertificateError::defer()
 {
diff --git a/src/core/api/qwebenginedownloadrequest.cpp b/src/core/api/qwebenginedownloadrequest.cpp
index 57823a7c9..7e3abed28 100644
--- a/src/core/api/qwebenginedownloadrequest.cpp
+++ b/src/core/api/qwebenginedownloadrequest.cpp
@@ -234,7 +234,7 @@ void QWebEngineDownloadRequestPrivate::setFinished()
     into the \l DownloadInProgress state and the downloading will begin. If the
     item is in any other state, then nothing will happen.
 
-    \sa finished(), stateChanged()
+    \sa isFinished, stateChanged()
 */
 
 void QWebEngineDownloadRequest::accept()
@@ -259,7 +259,7 @@ void QWebEngineDownloadRequest::accept()
     If the item is in any other state, then it will transition into the \l
     DownloadCancelled state without further effect.
 
-    \sa finished(), stateChanged()
+    \sa isFinished, stateChanged()
 */
 
 void QWebEngineDownloadRequest::cancel()
@@ -337,19 +337,11 @@ quint32 QWebEngineDownloadRequest::id() const
 }
 
 /*!
-    \fn void QWebEngineDownloadRequest::finished()
+    \fn void QWebEngineDownloadRequest::isPausedChanged()
 
-    This signal is emitted when the download finishes.
+    This signal is emitted whenever isPaused changes.
 
-    \sa state(), isFinished()
-*/
-
-/*!
-    \fn void QWebEngineDownloadRequest::isPausedChanged(bool isPaused)
-
-    This signal is emitted whenever \a isPaused changes.
-
-    \sa pause(), isPaused()
+    \sa pause(), isPaused
 */
 
 /*!
@@ -579,9 +571,11 @@ QString QWebEngineDownloadRequest::suggestedFileName() const
 }
 
 /*!
-    Returns whether this download is finished (completed, cancelled, or non-resumable interrupted state).
+    \property QWebEngineDownloadRequest::isFinished
+    \brief Whether this download is finished (completed, cancelled,
+           or non-resumable interrupted state).
 
-    \sa finished(), state(),
+    \sa state()
 */
 
 bool QWebEngineDownloadRequest::isFinished() const
@@ -591,7 +585,8 @@ bool QWebEngineDownloadRequest::isFinished() const
 }
 
 /*!
-    Returns whether this download is paused.
+    \property QWebEngineDownloadRequest::isPaused
+    \brief Whether this download is paused.
 
     \sa pause(), resume()
 */
diff --git a/src/core/api/qwebenginefullscreenrequest.cpp b/src/core/api/qwebenginefullscreenrequest.cpp
index facc8910d..5c75b9cc4 100644
--- a/src/core/api/qwebenginefullscreenrequest.cpp
+++ b/src/core/api/qwebenginefullscreenrequest.cpp
@@ -83,7 +83,7 @@ QT_BEGIN_NAMESPACE
     \brief The URL to be opened in the fullscreen mode.
 */
 
-/*!
+/*
     Creates a request for opening the \a page from the URL specified by
     \a origin in the fullscreen mode if \a fullscreen is \c true.
 */
diff --git a/src/core/api/qwebengineloadinginfo.cpp b/src/core/api/qwebengineloadinginfo.cpp
index 03a31ab72..ce6e57d5c 100644
--- a/src/core/api/qwebengineloadinginfo.cpp
+++ b/src/core/api/qwebengineloadinginfo.cpp
@@ -113,7 +113,7 @@ QUrl QWebEngineLoadingInfo::url() const
     return d->url;
 }
 /*!
-    \enum QWebEngineLoadingInfo::status
+    \enum QWebEngineLoadingInfo::LoadStatus
 
     This enumeration represents the load status of a web page load request:
 
@@ -125,10 +125,8 @@ QUrl QWebEngineLoadingInfo::url() const
     \value  LoadFailedStatus Page could not be loaded.
 */
 /*!
-    \property Holds the page's load status.
-*/
-/*!
-    Returns the page's load status.
+    \property QWebEngineLoadingInfo::status
+    \brief The load status of the page.
 */
 LoadStatus QWebEngineLoadingInfo::status() const
 {
@@ -137,10 +135,7 @@ LoadStatus QWebEngineLoadingInfo::status() const
 }
 /*!
     \property QWebEngineLoadingInfo::isErrorPage
-    \property Indicates if the load's resulted in an error page.
-*/
-/*!
-    Returns true if the load's resulted is an error page.
+    \brief Indicates if the load resulted in an error page.
 */
 bool QWebEngineLoadingInfo::isErrorPage() const
 {
@@ -151,16 +146,13 @@ bool QWebEngineLoadingInfo::isErrorPage() const
     \property QWebEngineLoadingInfo::errorString
     \brief Holds the error message.
 */
-/*
-    Returns the error message.
-*/
 QString QWebEngineLoadingInfo::errorString() const
 {
     Q_D(const QWebEngineLoadingInfo);
     return d->errorString;
 }
 /*!
-    \enum enumeration QWebEngineLoadingInfo::errorDomain
+    \enum QWebEngineLoadingInfo::ErrorDomain
     This enumeration holds the type of a load error:
 
     \value  NoErrorDomain
@@ -180,10 +172,7 @@ QString QWebEngineLoadingInfo::errorString() const
 */
 /*
     \property QWebEngineLoadingInfo::errorDomain
-    \brief Holds the error domain
-*/
-/*
-    Returns the error domain.
+    \brief Holds the error domain.
 */
 ErrorDomain QWebEngineLoadingInfo::errorDomain() const
 {
@@ -192,12 +181,9 @@ ErrorDomain QWebEngineLoadingInfo::errorDomain() const
 }
 
 /*!
-    \property int QWebEngineLoadingInfo::errorCode
+    \property QWebEngineLoadingInfo::errorCode
     \brief Holds the error code.
 */
-/*
-    Returns the error code.
-*/
 int QWebEngineLoadingInfo::errorCode() const
 {
     Q_D(const QWebEngineLoadingInfo);
diff --git a/src/core/api/qwebenginenewwindowrequest.cpp b/src/core/api/qwebenginenewwindowrequest.cpp
index 1656bcaef..5899c0dc3 100644
--- a/src/core/api/qwebenginenewwindowrequest.cpp
+++ b/src/core/api/qwebenginenewwindowrequest.cpp
@@ -55,14 +55,14 @@ struct QWebEngineNewWindowRequestPrivate
 
 /*!
     \class QWebEngineNewWindowRequest
-    \brief A utility type for the QWebEnginePage::newPageRequested signal.
+    \brief A utility type for the QWebEnginePage::newWindowRequested() signal.
     \since 6.2
 
     \inmodule QtWebEngineCore
 
     Contains information about a request to load a page in a separate web engine view.
 
-    \sa QWebEnginePage::newPageRequested
+    \sa QWebEnginePage::newWindowRequested()
 */
 
 /*!
diff --git a/src/core/api/qwebenginepage.cpp b/src/core/api/qwebenginepage.cpp
index 12dcc867b..57c660020 100644
--- a/src/core/api/qwebenginepage.cpp
+++ b/src/core/api/qwebenginepage.cpp
@@ -792,8 +792,8 @@ QWebEnginePage::QWebEnginePage(QObject* parent)
 */
 
 /*!
-    \fn QWebEnginePage::registerProtocolHandlerRequested(QWebEngineRegisterProtocolHandlerRequest
-   request) \since 5.11
+    \fn QWebEnginePage::registerProtocolHandlerRequested(QWebEngineRegisterProtocolHandlerRequest request)
+    \since 5.11
 
     This signal is emitted when the web page tries to register a custom protocol
     using the \l registerProtocolHandler API.
@@ -841,7 +841,7 @@ QWebEnginePage::QWebEnginePage(QObject* parent)
   \fn void QWebEnginePage::renderProcessPidChanged(qint64 pid);
   \since 5.15
 
-  This signal is emitted when the underlying render process PID, \a renderProcessPid, changes.
+  This signal is emitted when the underlying render process PID, \a pid, changes.
 */
 
 /*!
@@ -1534,7 +1534,6 @@ void QWebEnginePage::triggerAction(WebAction action, bool)
  * The current misspelled word can be found in QWebEngineContextMenuRequest::misspelledWord(),
  * and suggested replacements in QWebEngineContextMenuRequest::spellCheckerSuggestions().
  *
- * \sa contextMenuData(),
  */
 
 void QWebEnginePage::replaceMisspelledWord(const QString &replacement)
@@ -1570,14 +1569,13 @@ void QWebEnginePagePrivate::contextMenuRequested(QWebEngineContextMenuRequest *d
 }
 
 /*!
-    \fn void QWebEnginePage::navigationRequested(QWebEngineNavigationRequest &request)
+    \fn bool QWebEnginePage::navigationRequested(QWebEngineNavigationRequest &request)
     \since 6.2
 
     This signal is emitted on navigation together with the call the acceptNavigationRequest().
-    It can be used to accept or ignore the request. The default is to accept.
+    It can be used to accept or ignore the \a request. The default is to accept.
 
     \sa acceptNavigationRequest()
-
 */
 
 void QWebEnginePagePrivate::navigationRequested(int navigationType, const QUrl &url, int &navigationRequestAction, bool isMainFrame)
@@ -1881,13 +1879,18 @@ void QWebEnginePage::download(const QUrl& url, const QString& filename)
 }
 
 /*!
+    \fn void QWebEnginePage::loadingChanged(const QWebEngineLoadingInfo &loadingInfo)
+    \since 6.2
+    This signal is emitted when loading the page specified by \a loadingInfo begins,
+    ends, or fails.
+*/
+
+/*!
   \property QWebEnginePage::loading
   \since 6.2
 
   \brief Whether the page is currently loading.
 
-  The \l loadingChanged() signal is emitted when loading the page begins, ends, or fails.
-
   \sa QWebEngineLoadingInfo, loadStarted, loadFinished
 */
 bool QWebEnginePage::isLoading() const
@@ -2256,7 +2259,7 @@ QSizeF QWebEnginePage::contentsSize() const
 }
 
 /*!
-    \fn void QWebEnginePage::newWindowRequested(WebEngineNewViewRequest &request)
+    \fn void QWebEnginePage::newWindowRequested(QWebEngineNewWindowRequest &request)
     \since 6.2
 
     This signal is emitted when \a request is issued to load a page in a separate
@@ -2276,7 +2279,7 @@ QSizeF QWebEnginePage::contentsSize() const
 /*!
     Handles the newWindowRequested() signal by opening the \a request in this page.
     \since 6.2
-    \sa newWindowRequested
+    \sa newWindowRequested()
 */
 void QWebEnginePage::acceptAsNewWindow(QWebEngineNewWindowRequest &request)
 {
@@ -2383,7 +2386,7 @@ QWebEnginePage::LifecycleState QWebEnginePage::recommendedState() const
   to voluntarily reduce their resource usage if they are not visible to the
   user.
 
-  If the page is connected to a \l{view} then this property will be managed
+  If the page is connected to a \e {view} then this property will be managed
   automatically by the view according to it's own visibility.
 
   \sa lifecycleState
diff --git a/src/core/api/qwebengineprofile.cpp b/src/core/api/qwebengineprofile.cpp
index 6ec48e75b..f72e43161 100644
--- a/src/core/api/qwebengineprofile.cpp
+++ b/src/core/api/qwebengineprofile.cpp
@@ -654,7 +654,8 @@ void QWebEngineProfile::setNotificationPresenter(std::function<void(std::unique_
 }
 
 /*!
-    Returns presenter responsible for presenting sent notifications
+    \fn QWebEngineProfile::notificationPresenter()
+    Returns the presenter responsible for presenting sent notifications.
     \since 6.2
  */
 std::function<void(std::unique_ptr<QWebEngineNotification>)> QWebEngineProfile::notificationPresenter()
diff --git a/src/core/api/qwebengineregisterprotocolhandlerrequest.cpp b/src/core/api/qwebengineregisterprotocolhandlerrequest.cpp
index a3960327d..bb59282ea 100644
--- a/src/core/api/qwebengineregisterprotocolhandlerrequest.cpp
+++ b/src/core/api/qwebengineregisterprotocolhandlerrequest.cpp
@@ -50,7 +50,7 @@ QT_BEGIN_NAMESPACE
     \brief The QWebEngineRegisterProtocolHandlerRequest class enables
     accepting or rejecting requests from the \l registerProtocolHandler API.
 
-    \sa QWebEnginePage::registerProtocolHandlerRequested
+    \sa QWebEnginePage::registerProtocolHandlerRequested()
 */
 
 /*! \fn QWebEngineRegisterProtocolHandlerRequest::QWebEngineRegisterProtocolHandlerRequest()
diff --git a/src/core/api/qwebenginescript.cpp b/src/core/api/qwebenginescript.cpp
index 650ad5c53..f23e91ea5 100644
--- a/src/core/api/qwebenginescript.cpp
+++ b/src/core/api/qwebenginescript.cpp
@@ -149,7 +149,7 @@ QWebEngineScript &QWebEngineScript::operator=(const QWebEngineScript &other)
  * Returns the name of the script. Can be useful to retrieve a particular script from a
  * QWebEngineScriptCollection.
  *
- * \sa QWebEngineScriptCollection::findScript(), QWebEngineScriptCollection::findScripts()
+ * \sa QWebEngineScriptCollection::find()
  */
 
 QString QWebEngineScript::name() const
diff --git a/src/core/api/qwebenginescriptcollection.cpp b/src/core/api/qwebenginescriptcollection.cpp
index 6dfa12c46..193c42a79 100644
--- a/src/core/api/qwebenginescriptcollection.cpp
+++ b/src/core/api/qwebenginescriptcollection.cpp
@@ -65,12 +65,6 @@ using QtWebEngineCore::UserScript;
     Returns \c true if the collection is empty; otherwise returns \c false.
 */
 
-/*!
-    \fn QWebEngineScriptCollection::size() const
-
-    Returns the number of elements in the collection.
-*/
-
 QWebEngineScriptCollection::QWebEngineScriptCollection(QWebEngineScriptCollectionPrivate *collectionPrivate)
     :d(collectionPrivate)
 {
diff --git a/src/core/api/qwebenginesettings.cpp b/src/core/api/qwebenginesettings.cpp
index c7c0a47b2..08f76b80e 100644
--- a/src/core/api/qwebenginesettings.cpp
+++ b/src/core/api/qwebenginesettings.cpp
@@ -52,7 +52,7 @@ QWebEngineSettings::QWebEngineSettings(QWebEngineSettings *parentSettings)
 
 QWebEngineSettings::~QWebEngineSettings() { }
 
-/*!
+/*
     Returns the settings for a web engine page that belongs to the default
     profile. All web pages not specifically created with another profile belong
     to the default profile.