Fix some more documentation.

Adds the license for Chromium to the legalese part.

Adds some missing documentation to QWebEngineView and QWebEnginePage.

Change-Id: Ie81aaa87db85bb72efb83680defbdb101a134df0
Reviewed-by: Jocelyn Turcotte <jocelyn.turcotte@digia.com>

4 files changed, 132 insertions, 110 deletions

diff --git a/src/webenginewidgets/doc/src/qtwebenginewidgets.qdoc b/src/webenginewidgets/doc/src/qtwebenginewidgets.qdoc
index 4f4d0be55..fe43ca5c4 100644
--- a/src/webenginewidgets/doc/src/qtwebenginewidgets.qdoc
+++ b/src/webenginewidgets/doc/src/qtwebenginewidgets.qdoc
@@ -97,78 +97,10 @@
     \snippet snippets/simple/main.cpp Using QWebEngineView
 
     QWebEngineView is used to view Web pages. An instance of QWebEngineView has one
-    QWebEnginePage. QWebEnginePage provides access to the document structure in a page,
-    describing features such as frames, the navigation history, and the
-    undo/redo stack for editable content.
-
-    Common web browser features, defaults and other settings can be configured
-    through the QWebEngineSettings class. It is possible to provide defaults for all
-    QWebEnginePage instances through the default settings. Individual attributes
-    can be overridden by the page specific settings object.
-
-    \section1 Netscape Plugin Support
-
-    \note Netscape plugin support is only available on desktop platforms.
-
-    Since WebEngine supports the Netscape Plugin API, Qt applications can display
-    Web pages that embed common plugins on platforms for which those plugins
-    are available. To enable plugin support, the user must have the appropriate
-    binary files for those plugins installed and the \l{QWebEngineSettings::PluginsEnabled}
-    attribute must be enabled for the application.
-
-    The following locations are searched for plugins:
-
-    \table
-    \header \li Linux/Unix (X11)
-    \row \li
-    \list
-    \li \c{.mozilla/plugins} in the user's home directory
-    \li \c{.netscape/plugins} in the user's home directory
-    \li System locations, such as
-    \list
-    \li \c{/usr/lib/browser/plugins}
-    \li \c{/usr/local/lib/mozilla/plugins}
-    \li \c{/usr/lib/firefox/plugins}
-    \li \c{/usr/lib64/browser-plugins}
-    \li \c{/usr/lib/browser-plugins}
-    \li \c{/usr/lib/mozilla/plugins}
-    \li \c{/usr/local/netscape/plugins}
-    \li \c{/opt/mozilla/plugins}
-    \li \c{/opt/mozilla/lib/plugins}
-    \li \c{/opt/netscape/plugins}
-    \li \c{/opt/netscape/communicator/plugins}
-    \li \c{/usr/lib/netscape/plugins}
-    \li \c{/usr/lib/netscape/plugins-libc5}
-    \li \c{/usr/lib/netscape/plugins-libc6}
-    \li \c{/usr/lib64/netscape/plugins}
-    \li \c{/usr/lib64/mozilla/plugins}
-    \endlist
-    \li Locations specified by environment variables:
-    \list
-    \li \c{$MOZILLA_HOME/plugins}
-    \li \c{$MOZ_PLUGIN_PATH}
-    \li \c{$QTWEBKIT_PLUGIN_PATH}
-    \endlist
-    \endlist
-    \endtable
-
-    \table
-    \header  \li Windows
-    \row \li
-    \list
-    \li The user's \c{Application Data\Mozilla\plugins} directory
-    \li Standard system locations of plugins for Quicktime, Flash, etc.
-    \endlist
-    \endtable
-
-    \table
-    \header \li Mac OS X
-    \row \li
-    \list
-    \li \c{Library/Internet Plug-Ins} in the user's home directory
-    \li The system \c{/Library/Internet Plug-Ins} directory
-    \endlist
-    \endtable
+    QWebEnginePage. QWebEnginePage provides access to the page's navigation history,
+    allows to run JavaScript code in the context of the page's main frame and enables
+    customization of handlers for specific events such as showing custom authentication
+    dialogs.
 
     \section1 Examples
 
@@ -176,7 +108,6 @@
     \l{Qt WebEngine Widgets Examples} page.
 
     \section1 License Information
-    //FIXME: check if we are allowed to use the name chromium here or if it is considered promotional use.
     This is a snapshot of the integration of Chromium into Qt. The exact version information
     can be found in the \c{VERSION} file supplied with Qt.
 
@@ -188,7 +119,37 @@
     the module under the appropriate version of the GNU LGPL.
 
     \legalese
-    // FIXME: add correct licensing terms for chromium / blink. The one copied from QtWebKit does not apply.
+
+    Chromium is licensed under the following license:
+
+    Copyright (c) 2013 The Chromium Authors. All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are
+    met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following disclaimer
+      in the documentation and/or other materials provided with the
+      distribution.
+    * Neither the name of Google Inc. nor the names of its
+    contributors may be used to endorse or promote products derived from
+    this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
     \endlegalese
 */
 
diff --git a/src/webenginewidgets/doc/src/qwebenginehistory_lgpl.qdoc b/src/webenginewidgets/doc/src/qwebenginehistory_lgpl.qdoc
index 0cc90fb07..76a0a075d 100644
--- a/src/webenginewidgets/doc/src/qwebenginehistory_lgpl.qdoc
+++ b/src/webenginewidgets/doc/src/qwebenginehistory_lgpl.qdoc
@@ -228,7 +228,7 @@
 */
 
 /*!
-    \fn QDataStream& operator<<(QDataStream& target, const QWebEngineHistory& history)
+    \fn QDataStream& operator<<(QDataStream& stream, const QWebEngineHistory& history)
     \relates QWebEngineHistory
 
     \brief The operator<< function streams a history into a data stream.
@@ -238,7 +238,7 @@
 
 
 /*!
-    \fn QDataStream& operator>>(QDataStream& source, QWebEngineHistory& history)
+    \fn QDataStream& operator>>(QDataStream& stream, QWebEngineHistory& history)
     \relates QWebEngineHistory
 
     \brief The operator>> function loads a history from a data stream.
diff --git a/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc b/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc
index aa397e018..20564d724 100644
--- a/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc
+++ b/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc
@@ -30,14 +30,13 @@
 
     \inmodule QtWebEngine
 
-    QWebEnginePage holds a main frame responsible for web content, settings, the history
-    of navigated links and actions. This class can be used to provide functionality like
-    QWebEngineView in a widget-less environment.
+    QWebEnginePage holds a main frame responsible for web content, the history
+    of navigated links and actions.
 
     QWebEnginePage's API is very similar to QWebEngineView, as you are still provided with
     common functions like action() (known as
     \l{QWebEngineView::pageAction()}{pageAction}() in QWebEngineView), triggerAction(),
-    findText() and settings().
+    and findText().
 
     A page can be loaded using load() or setUrl(). Alternatively, if you have
     the HTML content readily available, you can use setHtml() instead.
@@ -56,11 +55,6 @@
     The zoomFactor() property can be used to change the overall size
     of the content displayed in the page.
 
-    There are multiple ways to programmatically examine the contents of a page.
-    The hitTestContent() function can be used to find elements by coordinate.
-    For access to the underlying DOM tree, there is documentElement(),
-    findAllElements() and findFirstElement().
-
     The loadStarted() signal is emitted when the page begins to load.The
     loadProgress() signal, on the other hand, is emitted whenever an element
     of the web page completes loading, such as an embedded image, a script,
@@ -141,6 +135,33 @@
 */
 
 /*!
+    \enum QWebEnginePage::PermissionPolicy
+
+    This enum describes the permission policies that the user may set for data or device access.
+
+    \value PermissionUnknown It is unknown whether the user grants or denies permission.
+    \value PermissionGrantedByUser The user has granted permission.
+    \value PermissionDeniedByUser The user has denied permission.
+
+    \sa featurePermissionRequested(), featurePermissionRequestCanceled(), setFeaturePermission(), Feature
+*/
+
+/*!
+    \enum QWebEnginePage::Feature
+
+    This enum describes the platform feature access categories that the user may be asked to grant or deny access to.
+
+    \value Notifications Grants access to display notifications to the user.
+    \value Geolocation The geographic location devices that may be available.
+    \value MediaAudioDevices Audio devices such as speakers or microphones
+    \value MediaVideoDevices Video devices, e.g. cameras
+    \value MediaAudioVideoDevices Both Audio and Video devices.
+
+    \sa featurePermissionRequested(), featurePermissionRequestCanceled(), setFeaturePermission(), PermissionPolicy
+
+*/
+
+/*!
     \fn QWebEnginePage::QWebEnginePage(QObject *parent)
     Constructs an empty QWebEnginePage with parent \a parent.
 */
@@ -290,7 +311,8 @@
 
     \a mode indicates whether only one file or multiples files are expected to be returned.
 
-    A suggested filename may be provided as the first entry of \a oldFiles.
+    A suggested filename may be provided as the first entry of \a oldFiles. \a acceptedMimeTypes is ignored by the default implementation,
+    but might be used by overrides.
 */
 
 /*!
@@ -309,7 +331,6 @@
     which is the default range of QProgressBar.
     It accumulates changes from all the child frames.
 
-    \sa bytesReceived()
 */
 
 /*!
@@ -319,7 +340,7 @@
     is independent of script execution or page rendering.
     \a ok will indicate whether the load was successful or any error occurred.
 
-    \sa loadStarted(), ErrorPageExtension
+    \sa loadStarted()
 */
 
 /*!
@@ -332,6 +353,29 @@
 */
 
 /*!
+    \fn void QWebEnginePage::linkHovered(const QString &url)
+
+    This signal is emitted when the mouse hovers over a link.
+    \a url contains the target URL of the link.
+*/
+
+/*!
+
+    \fn void QWebEnginePage::authenticationRequired(const QUrl &requestUrl, QAuthenticator *authenticator)
+
+    This signal is emitted when access to \a requestUrl requires authentication.
+    \a authenticator should be used to pass the user name and password for the connection.
+*/
+
+/*!
+    \fn void QWebEnginePage::proxyAuthenticationRequired(const QUrl &requestUrl, QAuthenticator *authenticator, const QString &proxyHost)
+
+    This signal is emitted when access to \a requestUrl via \a proxyHost requires authentication for the proxy.
+    \a authenticator should be used to pass the user name and password for the connection.
+
+*/
+
+/*!
     \fn void QWebEnginePage::geometryChangeRequested(const QRect& geom)
 
     This signal is emitted whenever the document wants to change the position and size of the
@@ -346,16 +390,18 @@
 */
 
 /*!
-    \fn QString QWebEnginePage::toHtml() const
-    Returns the frame's content as HTML, enclosed in HTML and BODY tags.
+    \fn void QWebEnginePage::toHtml(const QWebEngineCallback<const QString &> &resultCallback) const
+    Asynchronous method to retrieve the page's content as HTML, enclosed in HTML and BODY tags.
+    Upon successful completion, \a resultCallback is called with the page's content.
 
     \sa setHtml(), toPlainText()
 */
 
 /*!
-    \fn QString QWebEnginePage::toPlainText() const
-    Returns the content of this frame converted to plain text, completely
-    stripped of all HTML formatting.
+    \fn void QWebEnginePage::toPlainText(const QWebEngineCallback<const QString &> &resultCallback) const
+    Asynchronous method to retrieve the page's content converted to plain text, completely stripped of all
+    HTML formatting.
+    Upon successful completion, \a resultCallback is called with the page's content.
 
     \sa toHtml()
 */
@@ -443,17 +489,45 @@
 */
 
 /*!
-    \fn void runJavaScript(const QString& scriptSource)
+    \fn void QWebEnginePage::runJavaScript(const QString& scriptSource)
     Runs the JavaScript code contained in \a scriptSource.
 */
 
 /*!
-    \fn void runJavaScript(const QString& scriptSource, const QWebEngineCallback<const QVariant &> &resultCallback)
+    \fn void QWebEnginePage::runJavaScript(const QString& scriptSource, const QWebEngineCallback<const QVariant &> &resultCallback)
     Runs the JavaScript code contained in \a scriptSource.
+
     When the script has been executed, \a resultCallback is called with the result of the last executed statement.
 */
 
 /*!
+    \fn void QWebEnginePage::setFeaturePermission(const QUrl &securityOrigin, Feature feature, PermissionPolicy policy)
+
+    Sets the permission for the web site identified by \a securityOrigin to use \a feature to \a policy.
+
+    \sa featurePermissionRequested(), featurePermissionRequestCanceled()
+*/
+
+/*!
+    \fn void QWebEnginePage::featurePermissionRequested(const QUrl &securityOrigin, Feature feature)
+
+    This is signal is emitted when the web site identified by \a securityOrigin requests to make use of
+    the resource or device identified by \a feature.
+
+    \sa featurePermissionRequestCanceled(), setFeaturePermission()
+*/
+
+/*!
+    \fn void QWebEnginePage::featurePermissionRequestCanceled(const QUrl &securityOrigin, Feature feature)
+
+    This is signal is emitted when the web site identified by \a securityOrigin cancels a previously issued
+    request to make use of \a feature.
+
+    \sa featurePermissionRequested(), setFeaturePermission()
+
+*/
+
+/*!
     \fn void QWebEnginePage::titleChanged(const QString &title)
 
     This signal is emitted whenever the title of the main frame changes.
diff --git a/src/webenginewidgets/doc/src/qwebengineview_lgpl.qdoc b/src/webenginewidgets/doc/src/qwebengineview_lgpl.qdoc
index 7d7066088..bdfd4b20a 100644
--- a/src/webenginewidgets/doc/src/qwebengineview_lgpl.qdoc
+++ b/src/webenginewidgets/doc/src/qwebengineview_lgpl.qdoc
@@ -234,19 +234,12 @@
 */
 
 /*!
-    \fn bool QWebEngineView::findText(const QString &subString, QWebEnginePage::FindFlags options)
+    \fn void QWebEngineView::findText(const QString &subString, QWebEnginePage::FindFlags options, const QWebEngineCallback<bool> &resultCallback)
     Finds the specified string, \a subString, in the page, using the given \a options.
 
-    If the HighlightAllOccurrences flag is passed, the function will highlight all occurrences
-    that exist in the page. All subsequent calls will extend the highlight, rather than
-    replace it, with occurrences of the new string.
-
-    If the HighlightAllOccurrences flag is not passed, the function will select an occurrence
-    and all subsequent calls will replace the current occurrence with the next one.
-
     To clear the selection, just pass an empty string.
 
-    Returns true if \a subString was found; otherwise returns false.
+    The \a resultCallback will be called with a value of true if the \a subString was found; otherwise the callback value will be false.
 
     \sa selectedText(), selectionChanged()
 */
@@ -322,12 +315,6 @@
 */
 
 /*!
-    \fn void QWebEngineView::statusBarMessage(const QString& text)
-
-    This signal is emitted when the status bar \a text is changed by the page.
-*/
-
-/*!
     \fn void QWebEngineView::loadStarted()
 
     This signal is emitted when a new load of the page is started.