Doc: clean up QWebEngineSettings docs

... and the corresponding QQuickWebEngineSettings docs

- Add missing documentation
- Remove references to obsolete classes
- Edit for grammar and style

Change-Id: I368fff274609941d6435ddf3343b81bca6013945
Reviewed-by: Joerg Bornemann <joerg.bornemann@theqtcompany.com>

3 files changed, 84 insertions, 79 deletions

diff --git a/src/webengine/api/qquickwebenginesettings.cpp b/src/webengine/api/qquickwebenginesettings.cpp
index 8a88bac68..248713543 100644
--- a/src/webengine/api/qquickwebenginesettings.cpp
+++ b/src/webengine/api/qquickwebenginesettings.cpp
@@ -56,8 +56,8 @@ QQuickWebEngineSettings::QQuickWebEngineSettings(QQuickWebEngineSettings *parent
     \since QtWebEngine 1.1
     \brief WebEngineSettings allows configuration of browser properties and attributes.
 
-    WebEngineSettings allows configuration of browser properties and generic attributes like for example
-    JavaScript, focus behavior and access to remote content.
+    WebEngineSettings allows configuration of browser properties and generic attributes, such as
+    JavaScript support, focus behavior, and access to remote content.
 
     Each WebEngineView can have individual settings.
 
@@ -70,9 +70,9 @@ QQuickWebEngineSettings::~QQuickWebEngineSettings()
 /*!
     \qmlproperty bool WebEngineSettings::autoLoadImages
 
-    Specifies whether images are automatically loaded in web pages.
+    Automatically loads images on web pages.
 
-    This is enabled by default.
+    Enabled by default.
 */
 bool QQuickWebEngineSettings::autoLoadImages() const
 {
@@ -82,9 +82,9 @@ bool QQuickWebEngineSettings::autoLoadImages() const
 /*!
     \qmlproperty bool WebEngineSettings::javascriptEnabled
 
-    Enables or disables the running of JavaScript programs.
+    Enables the running of JavaScript programs.
 
-    This is enabled by default.
+    Enabled by default.
 */
 bool QQuickWebEngineSettings::javascriptEnabled() const
 {
@@ -94,9 +94,9 @@ bool QQuickWebEngineSettings::javascriptEnabled() const
 /*!
     \qmlproperty bool WebEngineSettings::javascriptCanOpenWindows
 
-    Specifies whether JavaScript programs can open new windows.
+    Allows JavaScript programs to open new windows.
 
-    This is enabled by default.
+    Enabled by default.
 */
 bool QQuickWebEngineSettings::javascriptCanOpenWindows() const
 {
@@ -106,9 +106,9 @@ bool QQuickWebEngineSettings::javascriptCanOpenWindows() const
 /*!
     \qmlproperty bool WebEngineSettings::javascriptCanAccessClipboard
 
-    Specifies whether JavaScript programs can read or write to the clipboard.
+    Allows JavaScript programs to read from or write to the clipboard.
 
-    This is disabled by default.
+    Disabled by default.
 */
 bool QQuickWebEngineSettings::javascriptCanAccessClipboard() const
 {
@@ -118,9 +118,9 @@ bool QQuickWebEngineSettings::javascriptCanAccessClipboard() const
 /*!
     \qmlproperty bool WebEngineSettings::linksIncludedInFocusChain
 
-    Specifies whether hyperlinks should be included in the keyboard focus chain.
+    Includes hyperlinks in the keyboard focus chain.
 
-    This is enabled by default.
+    Enabled by default.
 */
 bool QQuickWebEngineSettings::linksIncludedInFocusChain() const
 {
@@ -130,9 +130,9 @@ bool QQuickWebEngineSettings::linksIncludedInFocusChain() const
 /*!
     \qmlproperty bool WebEngineSettings::localStorageEnabled
 
-    Specifies whether support for the HTML 5 local storage feature is enabled or not.
+    Enables support for the HTML 5 local storage feature.
 
-    This is enabled by default.
+    Enabled by default.
 */
 bool QQuickWebEngineSettings::localStorageEnabled() const
 {
@@ -142,10 +142,9 @@ bool QQuickWebEngineSettings::localStorageEnabled() const
 /*!
     \qmlproperty bool WebEngineSettings::localContentCanAccessRemoteUrls
 
-    Specifies whether locally loaded documents are allowed to access remote urls.
-    For more information about security origins and local vs. remote content see QWebEngineSecurityOrigin.
+    Allows locally loaded documents to access remote URLs.
 
-    This is disabled by default.
+    Disabled by default.
 */
 bool QQuickWebEngineSettings::localContentCanAccessRemoteUrls() const
 {
@@ -155,15 +154,14 @@ bool QQuickWebEngineSettings::localContentCanAccessRemoteUrls() const
 /*!
     \qmlproperty bool WebEngineSettings::spatialNavigationEnabled
 
-    Enables or disables the Spatial Navigation feature, which consists in the
-    ability to navigate between focusable elements in a Web page, such as hyperlinks
-    and form controls, by using Left, Right, Up and Down arrow keys.
+    Enables the Spatial Navigation feature, which means the ability to navigate between focusable
+    elements, such as hyperlinks and form controls, on a web page by using the Left, Right, Up and
+    Down arrow keys.
 
-    For example, if a user presses the Right key, heuristics determine whether there
-    is an element they might be trying to reach towards the right and which element
-    they probably want.
+    For example, if a user presses the Right key, heuristics determine whether there is an element
+    they might be trying to reach towards the right and which element they probably want.
 
-    This is disabled by default.
+    Disabled by default.
 
 */
 bool QQuickWebEngineSettings::spatialNavigationEnabled() const
@@ -174,10 +172,9 @@ bool QQuickWebEngineSettings::spatialNavigationEnabled() const
 /*!
     \qmlproperty bool WebEngineSettings::localContentCanAccessFileUrls
 
-    Specifies whether locally loaded documents are allowed to access other local urls.
-    For more information about security origins and local vs. remote content see QWebEngineSecurityOrigin.
+    Allows locally loaded documents to access other local URLs.
 
-    This is enabled by default.
+    Enabled by default.
 */
 bool QQuickWebEngineSettings::localContentCanAccessFileUrls() const
 {
@@ -187,9 +184,9 @@ bool QQuickWebEngineSettings::localContentCanAccessFileUrls() const
 /*!
     \qmlproperty bool WebEngineSettings::hyperlinkAuditingEnabled
 
-    This setting enables support for the ping attribute for hyperlinks.
+    Enables support for the \c ping attribute for hyperlinks.
 
-    It is disabled by default.
+    Disabled by default.
 */
 bool QQuickWebEngineSettings::hyperlinkAuditingEnabled() const
 {
@@ -199,9 +196,9 @@ bool QQuickWebEngineSettings::hyperlinkAuditingEnabled() const
 /*!
     \qmlproperty bool WebEngineSettings::errorPageEnabled
 
-    This setting enables built-in error pages of Chromium.
+    Enables displaying the built-in error pages of Chromium.
 
-    It is enabled by default.
+    Enabled by default.
 */
 bool QQuickWebEngineSettings::errorPageEnabled() const
 {
@@ -211,10 +208,10 @@ bool QQuickWebEngineSettings::errorPageEnabled() const
 /*!
     \qmlproperty QString WebEngineSettings::defaultTextEncoding
 
-    The \a encoding, must be a string describing an encoding such as "utf-8",
-    "iso-8859-1", etc.
+    Sets the default encoding. The value must be a string describing an encoding such as "utf-8" or
+    "iso-8859-1".
 
-    If left empty a default value will be used.
+    If left empty, a default value will be used.
 */
 QString QQuickWebEngineSettings::defaultTextEncoding() const
 {
diff --git a/src/webenginewidgets/api/qwebenginesettings.cpp b/src/webenginewidgets/api/qwebenginesettings.cpp
index dadc3bfe1..164bf8db6 100644
--- a/src/webenginewidgets/api/qwebenginesettings.cpp
+++ b/src/webenginewidgets/api/qwebenginesettings.cpp
@@ -95,6 +95,11 @@ QWebEngineSettings *QWebEngineSettings::globalSettings()
 }
 #endif
 
+/*!
+    Returns the default settings for the web engine page.
+
+    \sa globalSettings()
+*/
 QWebEngineSettings *QWebEngineSettings::defaultSettings()
 {
     return QWebEngineProfile::defaultProfile()->settings();
diff --git a/src/webenginewidgets/doc/src/qwebenginesettings_lgpl.qdoc b/src/webenginewidgets/doc/src/qwebenginesettings_lgpl.qdoc
index 521c08781..567f26e20 100644
--- a/src/webenginewidgets/doc/src/qwebenginesettings_lgpl.qdoc
+++ b/src/webenginewidgets/doc/src/qwebenginesettings_lgpl.qdoc
@@ -28,13 +28,15 @@
 
     Any setting changed on the default object is automatically applied to all
     QWebEnginePage instances where the particular setting is not overridden already.
+
+    \sa defaultSettings()
 */
 
 /*!
     \class QWebEngineSettings
     \since 5.4
     \brief The QWebEngineSettings class provides an object to store the settings used
-    by QWebEnginePage
+    by QWebEnginePage.
 
     \inmodule QtWebEngineWidgets
 
@@ -44,10 +46,9 @@
     globalSettings().
 
     QWebEngineSettings allows configuration of browser properties, such as font sizes and
-    families, the location of a custom style sheet, and generic attributes like
-    JavaScript and plugins. Individual attributes are set using the setAttribute()
-    function. The \l{QWebEngineSettings::WebAttribute}{WebAttribute} enum further describes
-    each attribute.
+    families, the location of a custom style sheet, and generic attributes, such as JavaScript
+    support. Individual attributes are set using the setAttribute() function. The
+    \l{QWebEngineSettings::WebAttribute}{WebAttribute} enum further describes each attribute.
 
     \sa QWebEnginePage::settings(), QWebEngineView::settings()
 */
@@ -70,11 +71,11 @@
 /*!
     \enum QWebEngineSettings::FontSize
 
-    This enum describes the font sizes configurable through QWebEngineSettings.
+    This enum describes the font sizes configurable through QWebEngineSettings:
 
     \value MinimumFontSize The hard minimum font size.
     \value MinimumLogicalFontSize The minimum logical font size that is applied
-        when zooming out with QWebEngineFrame::setTextSizeMultiplier().
+        when zooming out.
     \value DefaultFontSize The default font size for regular text.
     \value DefaultFixedFontSize The default font size for fixed-pitch text.
 */
@@ -82,40 +83,42 @@
 /*!
     \enum QWebEngineSettings::WebAttribute
 
-    This enum describes various attributes that are configurable through QWebEngineSettings.
-
-    \value AutoLoadImages Specifies whether images are automatically loaded in
-        web pages. This is enabled by default.
-    \value JavascriptEnabled Enables or disables the running of JavaScript
-        programs. This is enabled by default
-    \value JavascriptCanOpenWindows Specifies whether JavaScript programs
-        can open new windows. This is enabled by default.
-    \value JavascriptCanAccessClipboard Specifies whether JavaScript programs
-        can read or write to the clipboard. This is disabled by default.
-    \value LinksIncludedInFocusChain Specifies whether hyperlinks should be
-        included in the keyboard focus chain. This is enabled by default.
-    \value LocalStorageEnabled Specifies whether support for the HTML 5
-        local storage feature is enabled or not. This is enabled by default.
-    \value LocalContentCanAccessRemoteUrls Specifies whether locally loaded documents are
-        allowed to access remote urls. This is disabled by default. For more information
-        about security origins and local vs. remote content see QWebEngineSecurityOrigin.
-    \value XSSAuditingEnabled Specifies whether load requests should be monitored for cross-site
-        scripting attempts. Suspicious scripts will be blocked and reported in the inspector's
-        JavaScript console. Enabling this feature might have an impact on performance
-        and it is disabled by default.
-    \value SpatialNavigationEnabled Enables or disables the Spatial Navigation
-        feature, which consists in the ability to navigate between focusable
-        elements in a Web page, such as hyperlinks and form controls, by using
-        Left, Right, Up and Down arrow keys. For example, if a user presses the
-        Right key, heuristics determine whether there is an element they might be
-        trying to reach towards the right and which element they probably want.
-        This is disabled by default.
-    \value LocalContentCanAccessFileUrls Specifies whether locally loaded documents are
-        allowed to access other local urls. This is enabled by default. For more information
-        about security origins and local vs. remote content see QWebEngineSecurityOrigin.
-    \value HyperlinkAuditingEnabled This setting enables support for the ping attribute for hyperlinks. It is disabled by default.
-    \value ScrollAnimatorEnabled This setting enables animated scrolling. It is disabled by default.
-    \value ErrorPageEnabled This setting enables built-in error pages of Chromium. It is enabled by default.
+    This enum type specifies settings for web pages:
+
+    \value  AutoLoadImages
+            Automatically loads images on web pages. Enabled by default.
+    \value  JavascriptEnabled
+            Enables the running of JavaScript programs. Enabled by default.
+    \value  JavascriptCanOpenWindows
+            Allows JavaScript programs to open new windows. Enabled by default.
+    \value  JavascriptCanAccessClipboard
+            Allows JavaScript programs to read from and write to the clipboard. Disabled by
+            default.
+    \value  LinksIncludedInFocusChain
+            Includes hyperlinks in the keyboard focus chain. Enabled by default.
+    \value  LocalStorageEnabled
+            Enables support for the HTML 5 local storage feature. Enabled by default.
+    \value  LocalContentCanAccessRemoteUrls
+            Allows locally loaded documents to access remote URLs. Disabled by default.
+    \value  XSSAuditingEnabled
+            Monitors load requests for cross-site scripting attempts. Suspicious scripts are blocked
+            and reported in the inspector's JavaScript console. Disabled by default, because it
+            might negatively affect performance.
+    \value  SpatialNavigationEnabled
+            Enables the Spatial Navigation feature, which means the ability to navigate between
+            focusable elements, such as hyperlinks and form controls, on a web page by using the
+            Left, Right, Up and Down arrow keys. For example, if a user presses the
+            Right key, heuristics determine whether there is an element they might be
+            trying to reach towards the right and which element they probably want.
+            Disabled by default.
+    \value  LocalContentCanAccessFileUrls
+            Allows locally loaded documents to access other local URLs. Enabled by default.
+    \value  HyperlinkAuditingEnabled
+            Enables support for the \c ping attribute for hyperlinks. Disabled by default.
+    \value  ScrollAnimatorEnabled
+            Enables animated scrolling. Disabled by default.
+    \value  ErrorPageEnabled
+            Enables displaying the built-in error pages of Chromium. Enabled by default.
 */
 
 /*!
@@ -140,9 +143,9 @@
     \fn void QWebEngineSettings::setDefaultTextEncoding(const QString& encoding)
     Specifies the default text encoding system.
 
-    The \a encoding, must be a string describing an encoding such as "utf-8",
-    "iso-8859-1", etc. If left empty a default value will be used. For a more
-    extensive list of encoding names see \l{QTextCodec}
+    The value of \a encoding must be a string describing an encoding such as "utf-8" or
+    "iso-8859-1". If left empty, a default value will be used. For a more
+    extensive list of encoding names see \l{QTextCodec}.
 
     \sa defaultTextEncoding()
 */
@@ -184,7 +187,7 @@
 /*!
     \fn bool QWebEngineSettings::testAttribute(WebAttribute attribute) const
 
-    Returns true if \a attribute is enabled; otherwise returns false.
+    Returns \c true if \a attribute is enabled; otherwise returns \c false.
 */
 
 /*!