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>

15 files changed, 65 insertions, 97 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.
diff --git a/src/core/doc/qtwebengine.qdocconf b/src/core/doc/qtwebengine.qdocconf
index 416f06abb..f81c706aa 100644
--- a/src/core/doc/qtwebengine.qdocconf
+++ b/src/core/doc/qtwebengine.qdocconf
@@ -37,6 +37,9 @@ qhp.QtWebEngine.subprojects.examples.sortPages = true
 manifestmeta.highlighted.names += "QtWebEngine/WebEngine Widgets Simple Browser Example" \
                 "QtWebEngine/WebEngine Quick Nano Browser"
 
+# add a generic thumbnail for an example that has no \image in its doc
+manifestmeta.thumbnail.names = "QtWebEngine/PDF Viewer Example"
+
 tagfile                 = ../../../doc/qtwebengine/qtwebengine.tags
 
 # Custom module header for clang that pulls in also QtWebEngineWidgets
@@ -46,13 +49,15 @@ moduleheader = QtWebEngineDoc
 includepaths += -I .
 
 depends += qtcore \
+           qtcore5compat \
+           qtdesigner \
            qtgui \
            qtlocation \
            qtnetwork \
-           qtplatformheaders \
            qtprintsupport \
            qtpositioning \
            qtqml \
+           qtqmlmodels \
            qtquick \
            qtquickcontrols \
            qtdoc \
@@ -64,7 +69,7 @@ headerdirs  += ../../core/api \
                ../../webenginequick/api \
                ../../webenginewidgets/api
 
-sourcedirs   = ../../core/api \
+sourcedirs  += ../../core/api \
                ../../core/doc \
                ../../webenginequick/api \
                ../../webenginequick/doc \
@@ -78,7 +83,9 @@ exampledirs +=  ../../../examples \
 
 examples.fileextensions += *.aff *.dic *.html
 
-imagedirs += images
+imagedirs += \
+             images \
+             ../../webenginequick/doc/images
 
 navigation.landingpage = "Qt WebEngine"
 navigation.cppclassespage = "Qt WebEngine C++ Classes and Namespaces"
@@ -86,5 +93,3 @@ navigation.qmltypespage = "Qt WebEngine QML Types"
 
 # \QWE macro expands to 'Qt WebEngine' without auto-linking anywhere.
 macro.QWE    = "Qt \\WebEngine"
-
-Cpp.ignoretokens += Q_WEBENGINE_EXPORT Q_WEBENGINECORE_EXPORT QWEBENGINEWIDGETS_EXPORT
diff --git a/src/core/doc/src/qwebenginehistory_lgpl.qdoc b/src/core/doc/src/qwebenginehistory_lgpl.qdoc
index c2c9d69c6..37f96e7c1 100644
--- a/src/core/doc/src/qwebenginehistory_lgpl.qdoc
+++ b/src/core/doc/src/qwebenginehistory_lgpl.qdoc
@@ -88,7 +88,7 @@
 
 /*!
     \class QWebEngineHistoryModel
-    \inqmlmodule QtWebEngineCore
+    \inmodule QtWebEngineCore
     \since 6.2
 
     \brief A data model that represents the history of a web engine page.
@@ -188,18 +188,18 @@
 */
 
 /*!
-    \fn QWebEngineHistoryModel *QWebEngineHistory::itemsModel
+    \fn QWebEngineHistoryModel *QWebEngineHistory::itemsModel() const
     Returns the data model, which represents URLs of back items, forward items,
     and the current item in the history.
 */
 
 /*!
-    \fn QWebEngineHistoryModel *QWebEngineHistory::backItemsModel
+    \fn QWebEngineHistoryModel *QWebEngineHistory::backItemsModel() const
     Return the data model, which represents URLs of visited pages.
 */
 
 /*!
-    \fn QWebEngineHistoryModel *QWebEngineHistory::forwardItemsModel
+    \fn QWebEngineHistoryModel *QWebEngineHistory::forwardItemsModel() const
     Return the data model, which represents URLs of the pages
     that were visited after visiting the current page.
 */
diff --git a/src/core/doc/src/qwebenginepage_lgpl.qdoc b/src/core/doc/src/qwebenginepage_lgpl.qdoc
index 8fddb5ebd..b1a79bcae 100644
--- a/src/core/doc/src/qwebenginepage_lgpl.qdoc
+++ b/src/core/doc/src/qwebenginepage_lgpl.qdoc
@@ -329,17 +329,6 @@
 */
 
 /*!
-    \fn QMenu *QWebEnginePage::createStandardContextMenu()
-    Creates the standard context menu which is shown when
-    the user clicks on the web page with the right mouse button. It is
-    called from the default \l{QWidget::}{contextMenuEvent()} handler. The popup menu's
-    ownership is transferred to the caller.
-
-    Returns \c nullptr if the context menu data is not initialized, for example when it
-    is called when there is actually no context menu requested.
- */
-
-/*!
     \fn void QWebEnginePage::javaScriptConsoleMessage(JavaScriptConsoleMessageLevel level, const QString& message, int lineNumber, const QString& sourceID)
     This function is called when a JavaScript program tries to print the \a message to the web
     browser's console.
@@ -431,8 +420,8 @@
     If the view associated with the web page is a QWebEngineView object, then the default implementation forwards
     the request to QWebEngineView::createWindow(); otherwise it returns a null pointer.
 
-    If this call is not implemented or does not return a new page, \l newWindowRequested() is emitted to handle
-    the request.
+    If this call is not implemented or does not return a new page, \l newWindowRequested()
+    is emitted to handle the request.
 
     \note In the cases when the window creation is being triggered by JavaScript, apart from
     reimplementing this method the application must also set
@@ -505,8 +494,6 @@
 /*!
     \fn QWebEngineSettings *QWebEnginePage::settings() const
     Returns a pointer to the page's settings object.
-
-    \sa QWebEngineSettings::defaultSettings()
 */
 
 /*!
diff --git a/src/core/doc/src/qwebenginesettings_lgpl.qdoc b/src/core/doc/src/qwebenginesettings_lgpl.qdoc
index a62abfbab..7c6ccd3d3 100644
--- a/src/core/doc/src/qwebenginesettings_lgpl.qdoc
+++ b/src/core/doc/src/qwebenginesettings_lgpl.qdoc
@@ -201,6 +201,7 @@
            from JavaScript) are suppressed.
     \value AllowAllUnknownUrlSchemes
            Allows all navigation requests to URLs with unknown schemes.
+    \omitvalue InheritedUnknownUrlSchemePolicy
 
     \sa unknownUrlSchemePolicy setUnknownUrlSchemePolicy resetUnknownUrlSchemePolicy
 */
@@ -240,12 +241,6 @@
 */
 
 /*!
-    \fn void QWebEngineSettings::setFontFamily(FontFamily which, const QString& family)
-    Sets the actual font family to \a family for the specified generic family,
-    \a which.
-*/
-
-/*!
     \fn QString QWebEngineSettings::fontFamily(FontFamily which) const
     Returns the actual font family for the specified generic font family,
     \a which.