Add userScript docs for qml land

WebEngineScript docs were missing after moving classes to core.
Moreover we changed WebEngineScript to be a qml value type and
we introduced WebEngineScriptCollection to mirror C++ class.

Add the documentation for WebEngineScript, WebEngineScriptCollection
and WebEngine.script() method.

Task-number: QTBUG-100404
Change-Id: Ifed1bd1fa398a8634df0dc1bd44111e1a09ded04
Reviewed-by: Kirill Burtsev <kirill.burtsev@qt.io>
(cherry picked from commit 34f509a0a2059c54f9217c5a3dd8e3681bcc0964)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

5 files changed, 238 insertions, 3 deletions

diff --git a/src/webenginequick/api/qquickwebengineprofile.cpp b/src/webenginequick/api/qquickwebengineprofile.cpp
index c7421774b..ec7365064 100644
--- a/src/webenginequick/api/qquickwebengineprofile.cpp
+++ b/src/webenginequick/api/qquickwebengineprofile.cpp
@@ -954,7 +954,7 @@ QQuickWebEngineSettings *QQuickWebEngineProfile::settings() const
 }
 
 /*!
-    \qmlproperty list<WebEngineScript> WebEngineProfile::userScripts
+    \qmlproperty WebEngineScriptCollection WebEngineProfile::userScripts
     \since 1.5
 
     Returns the collection of WebEngineScript objects that are injected into
diff --git a/src/webenginequick/api/qquickwebenginescriptcollection.cpp b/src/webenginequick/api/qquickwebenginescriptcollection.cpp
index 9a12c6f5c..5cc2952f0 100644
--- a/src/webenginequick/api/qquickwebenginescriptcollection.cpp
+++ b/src/webenginequick/api/qquickwebenginescriptcollection.cpp
@@ -46,6 +46,61 @@
 #include <QtQml/private/qv4scopedvalue_p.h>
 #include <QtQml/private/qv4arrayobject_p.h>
 
+/*!
+    \qmltype WebEngineScriptCollection
+    \brief Manages a collection of user scripts.
+    \since QtWebEngine 6.2
+
+    \inqmlmodule QtWebEngine
+
+    WebEngineScriptCollection handles a user scripts collection, which
+    is injected in the JavaScript engine during the loading of web content.
+
+    Use \l{WebEngineView::userScripts}{WebEgineView.userScripts} and
+    \l{WebEngineProfile::userScripts}{WebEngineProfile.userScripts} to access
+    the collection of scripts  associated with a single page or number of pages
+    sharing the same profile.
+
+    The collection of user script objects in QML can be created for a set of
+    user script objects by simple assignment to
+    \l{WebEngineScriptCollection::collection}{WebEngineScriptCollection.collection}
+    property or by WebEngineScriptCollection methods.
+
+    \note The new user script can be instantiated with JavaScript dictionaries when using
+    \e collection property.
+
+    See the following code snippets demonstrating the usage:
+
+    \list
+        \li \e collection property with JavaScript dictionaries
+        \code
+            var scriptFoo = { name: "Foo",
+                            sourceUrl: Qt.resolvedUrl("foo.js"),
+                            injectionPoint: WebEngineScript.DocumentReady }
+
+            webEngineView.userScripts.collection = [ scriptFoo, scriptBar ];
+        \endcode
+        \li \e collection property with user script object as value type
+         \code
+            var script = WebEngine.script()
+            script.name = "FOO"
+            webEngineView.userScripts.collection = [ script ]
+         \endcode
+         \li user script collection \e insert method can be used only with value type
+            or list of value types
+         \code
+            var script = WebEngine.script()
+            script.name = "FOO"
+            webEngineView.userScripts.insert(script)
+
+            var list = [ script ]
+            webEngineView.userScripts.insert(list)
+         \endcode
+     \endlist
+     \sa WebEngineScript WebEngineScriptCollection
+
+*/
+
 QWebEngineScript parseScript(const QJSValue &value, bool *ok)
 {
     QWebEngineScript s;
@@ -97,36 +152,79 @@ QQuickWebEngineScriptCollection::QQuickWebEngineScriptCollection(QQuickWebEngine
 
 QQuickWebEngineScriptCollection::~QQuickWebEngineScriptCollection() { }
 
+/*!
+    \qmlmethod void WebEngineScriptCollection::contains(WebEngineScript script)
+    \since QtWebEngine 6.2
+    Checks if the specified \a script is in the collection.
+    \sa find()
+*/
+
 bool QQuickWebEngineScriptCollection::contains(const QWebEngineScript &value) const
 {
     return d->contains(value);
 }
 
+/*!
+    \qmlmethod list<WebEngineScript> WebEngineScriptCollection::find(string name)
+    \since QtWebEngine 6.2
+    Returns a list of all user script objects with the given \a name.
+    \sa find()
+*/
 QList<QWebEngineScript> QQuickWebEngineScriptCollection::find(const QString &name) const
 {
     return d->find(name);
 }
 
+/*!
+    \qmlmethod void WebEngineScriptCollection::insert(WebEngineScript script)
+    \since QtWebEngine 6.2
+    Inserts a single \a script into the collection.
+    \sa find()
+*/
 void QQuickWebEngineScriptCollection::insert(const QWebEngineScript &s)
 {
     d->insert(s);
 }
 
+/*!
+    \qmlmethod void WebEngineScriptCollection::insert(list<WebEngineScript> list)
+    \since QtWebEngine 6.2
+    Inserts a \a list of WebEngineScript values into the user script collection.
+    \sa find()
+*/
 void QQuickWebEngineScriptCollection::insert(const QList<QWebEngineScript> &list)
 {
     d->insert(list);
 }
 
+/*!
+    \qmlmethod bool WebEngineScriptCollection::remove(WebEngineScript script)
+    \since QtWebEngine 6.2
+    Returns \c true if a given \a script is removed from the collection.
+    \sa insert()
+*/
 bool QQuickWebEngineScriptCollection::remove(const QWebEngineScript &script)
 {
     return d->remove(script);
 }
 
+/*!
+    \qmlmethod void WebEngineScriptCollection::clear()
+    \since QtWebEngine 6.2
+    Removes all script objects from this collection.
+*/
 void QQuickWebEngineScriptCollection::clear()
 {
     d->clear();
 }
 
+/*!
+    \qmlproperty list<WebEngineScript> WebEngineScriptCollection::collection
+    \since QtWebEngine 6.2
+
+    This property holds a JavaScript array of user script objects. The array can
+    take WebEngineScript basic type or a JavaScript dictionary as values.
+*/
 QJSValue QQuickWebEngineScriptCollection::collection() const
 {
     if (!d->m_qmlEngine) {
diff --git a/src/webenginequick/api/qquickwebenginesingleton.cpp b/src/webenginequick/api/qquickwebenginesingleton.cpp
index 3d15a3a2c..6c4e6fb68 100644
--- a/src/webenginequick/api/qquickwebenginesingleton.cpp
+++ b/src/webenginequick/api/qquickwebenginesingleton.cpp
@@ -99,6 +99,19 @@ QQuickWebEngineProfile *QQuickWebEngineSingleton::defaultProfile() const
     return profile;
 }
 
+/*!
+    \qmlmethod WebEngineScript WebEngine::script
+    //! \instantiates QWebEngineScript
+    \since QtWebEngine 6.2
+
+    Constructs WebEngineScript, which can be set up and inserted into user scripts' collection
+    for \l{WebEngineView::userScripts}{WebEngineView.userScripts} or
+    \l{WebEngineProfile::userScripts}{WebEngineProfile.userScripts}
+    using \l{WebEngineScriptCollection}.
+
+    \sa WebEngineScript WebEngineScriptCollection
+*/
+
 QWebEngineScript QQuickWebEngineSingleton::script() const
 {
     return QWebEngineScript();
diff --git a/src/webenginequick/doc/src/webenginescript.qdoc b/src/webenginequick/doc/src/webenginescript.qdoc
new file mode 100644
index 000000000..9f9e4c210
--- /dev/null
+++ b/src/webenginequick/doc/src/webenginescript.qdoc
@@ -0,0 +1,122 @@
+/****************************************************************************
+**
+** Copyright (C) 2022 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \qmltype WebEngineScript
+    \instantiates QWebEngineScript
+    \brief Enables the programmatic injection of scripts in the JavaScript engine.
+    \since QtWebEngine 1.1
+    \ingroup qmlvaluetypes
+    \inqmlmodule QtWebEngine
+
+    The WebEngineScript type enables the programmatic injection of so called \e {user scripts} in
+    the JavaScript engine at different points, determined by injectionPoint, during the loading of
+    web content.
+
+    Scripts can be executed either in the main JavaScript \e world, along with the rest of the
+    JavaScript coming from the web contents, or in their own isolated world. While the DOM of the
+    page can be accessed from any world, JavaScript variables of a function defined in one world are
+    not accessible from a different one. The worldId property provides some predefined IDs for this
+    purpose.
+
+    The following \l Greasemonkey  attributes are supported:
+    \c @exclude, \c @include, \c @name, \c @match, and \c @run-at.
+
+    Use \l{WebEngineScriptCollection} to access a list of scripts attached to the web view.
+*/
+
+/*!
+    \qmlproperty string WebEngineScript::name
+
+    The name of the script. Can be useful to retrieve a particular script from
+    \l{WebEngineScriptCollection::find}{WebEngineScriptCollection.find} method.
+*/
+
+*!
+    \qmlproperty url WebEngineScript::sourceUrl
+
+    This property holds the remote source location of the user script (if any).
+
+    Unlike \l sourceCode, this property allows referring to user scripts that
+    are not already loaded in memory, for instance, when stored on disk.
+
+    Setting this property will change the \l sourceCode of the script.
+
+    \note At present, only file-based sources are supported.
+
+    \sa sourceCode
+*/
+
+/*!
+    \qmlproperty string WebEngineScript::sourceCode
+
+    This property holds the JavaScript source code of the user script.
+
+    \sa sourceUrl
+*/
+
+/*!
+    \qmlproperty enumeration WebEngineScript::injectionPoint
+
+    The point in the loading process at which the script will be executed.
+    The default value is \c Deferred.
+
+    \value WebEngineScript.DocumentCreation
+           The script will be executed as soon as the document is created. This is not suitable for
+           any DOM operation.
+    \value WebEngineScript.DocumentReady
+           The script will run as soon as the DOM is ready. This is equivalent to the
+           \c DOMContentLoaded event firing in JavaScript.
+    \value WebEngineScript.Deferred
+           The script will run when the page load finishes, or 500 ms after the document is ready,
+           whichever comes first.
+*/
+
+/*!
+    \qmlproperty enumeration WebEngineScript::worldId
+
+    The world ID defining which isolated world the script is executed in.
+
+    \value WebEngineScript.MainWorld
+           The world used by the page's web contents. It can be useful in order to expose custom
+           functionality to web contents in certain scenarios.
+    \value WebEngineScript.ApplicationWorld
+           The default isolated world used for application level functionality implemented in
+           JavaScript.
+    \value WebEngineScript.UserWorld
+           The first isolated world to be used by scripts set by users if the application is not
+           making use of more worlds. As a rule of thumb, if that functionality is exposed to the
+           application users, each individual script should probably get its own isolated world.
+*/
+
+/*!
+    \qmlproperty int WebEngineScript::runOnSubframes
+
+    Set this property to \c true if the script is executed on every frame in the page, or \c false
+    if it is only ran for the main frame.
+    The default value is \c{false}.
+*/
diff --git a/src/webenginequick/doc/src/webengineview_lgpl.qdoc b/src/webenginequick/doc/src/webengineview_lgpl.qdoc
index f0f6fc8fe..7f2e329df 100644
--- a/src/webenginequick/doc/src/webengineview_lgpl.qdoc
+++ b/src/webenginequick/doc/src/webengineview_lgpl.qdoc
@@ -327,11 +327,13 @@
 
 
 /*!
-    \qmlproperty list<WebEngineScript> WebEngineView::userScripts
+    \qmlproperty WebEngineScriptCollection WebEngineView::userScripts
     \readonly
     \since QtWebEngine 1.1
 
-    List of WebEngineScript objects attached to the view.
+    The user scripts' collection associated with the view.
+
+    \sa WebEngineScriptCollection
 */
 
 /*!