Doc: Edit docs on script injection

Task-number: QTBUG-76489
Change-Id: If489ebed802d273b0015bc6cfc190d948c4896e3
Reviewed-by: Jüri Valdmann <juri.valdmann@qt.io>

5 files changed, 18 insertions, 10 deletions

diff --git a/src/webenginewidgets/api/qwebenginepage.cpp b/src/webenginewidgets/api/qwebenginepage.cpp
index 78b89a53c..055047341 100644
--- a/src/webenginewidgets/api/qwebenginepage.cpp
+++ b/src/webenginewidgets/api/qwebenginepage.cpp
@@ -2183,7 +2183,7 @@ void QWebEnginePage::runJavaScript(const QString& scriptSource, quint32 worldId,
     In addition, a page might also execute scripts
     added through QWebEngineProfile::scripts().
 
-    \sa QWebEngineScriptCollection, QWebEngineScript
+    \sa QWebEngineScriptCollection, QWebEngineScript, {Script Injection}
 */
 
 QWebEngineScriptCollection &QWebEnginePage::scripts()
diff --git a/src/webenginewidgets/api/qwebengineprofile.cpp b/src/webenginewidgets/api/qwebengineprofile.cpp
index c8aafa0e8..6644af3ff 100644
--- a/src/webenginewidgets/api/qwebengineprofile.cpp
+++ b/src/webenginewidgets/api/qwebengineprofile.cpp
@@ -593,7 +593,8 @@ bool QWebEngineProfile::visitedLinksContainsUrl(const QUrl &url) const
     Returns the collection of scripts that are injected into all pages that share
     this profile.
 
-    \sa QWebEngineScriptCollection, QWebEngineScript, QWebEnginePage::scripts()
+    \sa QWebEngineScriptCollection, QWebEngineScript, QWebEnginePage::scripts(),
+        {Script Injection}
 */
 QWebEngineScriptCollection *QWebEngineProfile::scripts() const
 {
diff --git a/src/webenginewidgets/api/qwebenginescript.cpp b/src/webenginewidgets/api/qwebenginescript.cpp
index d1e996b3a..af6b9aa8d 100644
--- a/src/webenginewidgets/api/qwebenginescript.cpp
+++ b/src/webenginewidgets/api/qwebenginescript.cpp
@@ -67,6 +67,8 @@ using QtWebEngineCore::UserScript;
     Use QWebEnginePage::scripts() and QWebEngineProfile::scripts() to access
     the collection of scripts associated with a single page or a
     number of pages sharing the same profile.
+
+    \sa {Script Injection}
 */
 /*!
     \enum QWebEngineScript::InjectionPoint
diff --git a/src/webenginewidgets/api/qwebenginescriptcollection.cpp b/src/webenginewidgets/api/qwebenginescriptcollection.cpp
index 5ef0ffd44..8cbeeb804 100644
--- a/src/webenginewidgets/api/qwebenginescriptcollection.cpp
+++ b/src/webenginewidgets/api/qwebenginescriptcollection.cpp
@@ -55,6 +55,8 @@ using QtWebEngineCore::UserScript;
     Use QWebEnginePage::scripts() and QWebEngineProfile::scripts() to access
     the collection of scripts associated with a single page or a
     number of pages sharing the same profile.
+
+    \sa {Script Injection}
 */
 
 /*!
diff --git a/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc b/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc
index 15e57e904..2bf4d0413 100644
--- a/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc
+++ b/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc
@@ -759,10 +759,15 @@
     \fn void QWebEnginePage::runJavaScript(const QString &scriptSource, const QWebEngineCallback<const QVariant &> &resultCallback)
     \since 5.7
 
-    Runs the JavaScript code contained in \a scriptSource in the world specified by \a worldId.
-    The world ID values are the same as provided by QWebEngineScript::ScriptWorldId, and between \c 0
-    and \c 256. Using the \e runJavaScript() versions without the world ID is the same as running the
-    script in the \c MainWorld.
+    Runs the JavaScript code contained in \a scriptSource without checking
+    whether the DOM of the page has been constructed. If you need more
+    control over how the script is run, consider using \l scripts() instead.
+
+    To avoid conflicts with other scripts executed on the page, the world in
+    which the script is run is specified by \a worldId. The world ID values are
+    the same as provided by QWebEngineScript::ScriptWorldId, and between \c 0
+    and \c 256. If you leave out the \c world ID, the script is run in the
+    \c MainWorld.
 
     When the script has been executed, \a resultCallback is called with the result of the last
     executed statement. \c resultCallback can be any of a function pointer, a functor or a lambda,
@@ -772,7 +777,7 @@
     page.runJavaScript("document.title", [](const QVariant &v) { qDebug() << v.toString(); });
     \endcode
 
-    Only "plain data" can be returned from JavaScript as the result value.
+    Only plain data can be returned from JavaScript as the result value.
     Supported data types include all of the JSON data types as well as, for
     example, \c{Date} and \c{ArrayBuffer}. Unsupported data types include, for
     example, \c{Function} and \c{Promise}.
@@ -784,9 +789,7 @@
     during page destruction. When QWebEnginePage is deleted, the callback is triggered with an invalid
     value and it is not safe to use the corresponding QWebEnginePage or QWebEngineView instance inside it.
 
-    See scripts() for an alternative API to inject scripts.
-
-    \sa QWebEngineScript::ScriptWorldId
+    \sa scripts(), QWebEngineScript::ScriptWorldId, {Script Injection}
 */
 
 /*!