Add documentation for cookie API and request interception in core

Change-Id: I6908ff3da9e0c78c3cf3d9b27d6c532029423d24
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@theqtcompany.com>
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@theqtcompany.com>

2 files changed, 235 insertions, 0 deletions

diff --git a/src/core/api/qwebenginecookiestoreclient.cpp b/src/core/api/qwebenginecookiestoreclient.cpp
index f4770927e..25480c1b3 100644
--- a/src/core/api/qwebenginecookiestoreclient.cpp
+++ b/src/core/api/qwebenginecookiestoreclient.cpp
@@ -171,6 +171,38 @@ void QWebEngineCookieStoreClientPrivate::onCookieChanged(const QNetworkCookie &c
         Q_EMIT q->cookieAdded(cookie);
 }
 
+/*!
+    \class QWebEngineCookieStoreClient
+    \inmodule QtWebEngineCore
+    \since 5.6
+    \brief The QWebEngineCookieStoreClient class provides access to Chromium's cookies.
+
+    By subclassing the QWebEngineCookieStoreClient and installing it on the profile, the user can
+    access HTTP cookies of Chromium.
+    It can be used to synchronize cookies of Chromium and the QNetworkAccessManager, as well as
+    to set, delete, and intercept cookies during navigation.
+    Because cookie operations are asynchronous, the user can choose to provide a callback function
+    to get notified about the success of the operation.
+    The signal handlers for removal and addition should not be used to execute heavy tasks,
+    because they might block the IO thread in case of a blocking connection.
+*/
+
+/*!
+    \fn void QWebEngineCookieStoreClient::cookieAdded(const QNetworkCookie &cookie)
+
+    This signal is emitted whenever a new \a cookie is added to the cookie store.
+*/
+
+/*!
+    \fn void QWebEngineCookieStoreClient::cookieRemoved(const QNetworkCookie &cookie)
+
+    This signal is emitted whenever a \a cookie is deleted from the cookie store.
+*/
+
+/*!
+    Creates a new QWebEngineCookieStoreClient object with \a parent.
+*/
+
 QWebEngineCookieStoreClient::QWebEngineCookieStoreClient(QObject *parent)
     : QObject(parent)
     , d_ptr(new QWebEngineCookieStoreClientPrivate(this))
@@ -178,28 +210,69 @@ QWebEngineCookieStoreClient::QWebEngineCookieStoreClient(QObject *parent)
 
 }
 
+/*!
+    Destroys this QWebEngineCookieStoreClient object.
+*/
+
 QWebEngineCookieStoreClient::~QWebEngineCookieStoreClient()
 {
 
 }
 
+/*!
+    \fn void setCookieWithCallback(const QNetworkCookie &cookie, FunctorOrLambda resultCallback, const QUrl &origin = QUrl())
+
+    Adds \a cookie to the cookie store. When the operation finishes, \a resultCallback will be executed
+    on the caller thread.
+    It is possible to provide an optional \a origin URL argument to limit the scope of the cookie.
+    The provided URL should also include the scheme.
+
+    \sa setCookie()
+*/
+
 void QWebEngineCookieStoreClient::setCookieWithCallback(const QNetworkCookie &cookie, const QWebEngineCallback<bool> &resultCallback, const QUrl &origin)
 {
     Q_D(QWebEngineCookieStoreClient);
     d->setCookie(resultCallback, cookie, origin);
 }
 
+/*!
+    Adds \a cookie to the cookie store. This function is provided for convenience and is
+    equivalent to calling setCookieWithCallback() with an empty callback.
+    It is possible to provide an optional \a origin URL argument to limit the scope of the cookie.
+    The provided URL should also include the scheme.
+
+    \sa setCookieWithCallback()
+*/
+
 void QWebEngineCookieStoreClient::setCookie(const QNetworkCookie &cookie, const QUrl &origin)
 {
     setCookieWithCallback(cookie, QWebEngineCallback<bool>(), origin);
 }
 
+/*!
+    Deletes \a cookie from the cookie store.
+    It is possible to provide an optional \a origin URL argument to limit the scope of the
+    cookie to be deleted.
+    The provided URL should also include the scheme.
+*/
+
 void QWebEngineCookieStoreClient::deleteCookie(const QNetworkCookie &cookie, const QUrl &origin)
 {
     Q_D(QWebEngineCookieStoreClient);
     d->deleteCookie(cookie, origin);
 }
 
+/*!
+    \fn void QWebEngineCookieStoreClient::getAllCookies(FunctorOrLambda resultCallback)
+
+    Requests all the cookies in the cookie store. When the asynchronous operation finishes,
+    \a resultCallback will be called with a QByteArray as the argument containing the cookies.
+    This QByteArray can be parsed using QNetworkCookie::parseCookies().
+
+    \sa deleteCookie()
+*/
+
 void QWebEngineCookieStoreClient::getAllCookies(const QWebEngineCallback<const QByteArray&> &resultCallback)
 {
     Q_D(QWebEngineCookieStoreClient);
@@ -211,6 +284,15 @@ void QWebEngineCookieStoreClient::getAllCookies(const QWebEngineCallback<const Q
     d->getAllCookies();
 }
 
+/*!
+    \fn void QWebEngineCookieStoreClient::deleteSessionCookiesWithCallback(FunctorOrLambda resultCallback)
+
+    Deletes all the session cookies in the cookie store. Session cookies do not have an
+    expiration date assigned to them.
+    When the asynchronous operation finishes, \a resultCallback will be called with the
+    number of cookies deleted as the argument.
+*/
+
 void QWebEngineCookieStoreClient::deleteSessionCookiesWithCallback(const QWebEngineCallback<int> &resultCallback)
 {
     Q_D(QWebEngineCookieStoreClient);
@@ -222,6 +304,15 @@ void QWebEngineCookieStoreClient::deleteSessionCookiesWithCallback(const QWebEng
     d->deleteSessionCookies();
 }
 
+/*!
+    \fn void QWebEngineCookieStoreClient::deleteAllCookiesWithCallback(FunctorOrLambda resultCallback)
+
+    Deletes all the cookies in the cookie store. When the asynchronous operation finishes,
+    \a resultCallback will be called with the number of cookies deleted as the argument.
+
+    \sa deleteSessionCookiesWithCallback(), getAllCookies()
+*/
+
 void QWebEngineCookieStoreClient::deleteAllCookiesWithCallback(const QWebEngineCallback<int> &resultCallback)
 {
     Q_D(QWebEngineCookieStoreClient);
@@ -233,11 +324,23 @@ void QWebEngineCookieStoreClient::deleteAllCookiesWithCallback(const QWebEngineC
     d->deleteAllCookies();
 }
 
+/*!
+    Deletes all the session cookies in the cookie store.
+
+    \sa deleteSessionCookiesWithCallback()
+*/
+
 void QWebEngineCookieStoreClient::deleteSessionCookies()
 {
     deleteSessionCookiesWithCallback(QWebEngineCallback<int>());
 }
 
+/*!
+    Deletes all the cookies in the cookie store.
+
+    \sa deleteAllCookiesWithCallback(), getAllCookies()
+*/
+
 void QWebEngineCookieStoreClient::deleteAllCookies()
 {
     deleteAllCookiesWithCallback(QWebEngineCallback<int>());
diff --git a/src/core/api/qwebengineurlrequestinfo.cpp b/src/core/api/qwebengineurlrequestinfo.cpp
index e97b0c7b9..282361584 100644
--- a/src/core/api/qwebengineurlrequestinfo.cpp
+++ b/src/core/api/qwebengineurlrequestinfo.cpp
@@ -68,6 +68,57 @@ ASSERT_ENUMS_MATCH(QtWebEngineCore::WebContentsAdapterClient::BackForwardNavigat
 ASSERT_ENUMS_MATCH(QtWebEngineCore::WebContentsAdapterClient::ReloadNavigation, QWebEngineUrlRequestInfo::NavigationTypeReload)
 ASSERT_ENUMS_MATCH(QtWebEngineCore::WebContentsAdapterClient::OtherNavigation, QWebEngineUrlRequestInfo::NavigationTypeOther)
 
+/*!
+    \class QWebEngineUrlRequestInfo
+    \inmodule QtWebEngineCore
+    \since 5.6
+    \brief The QWebEngineUrlRequestInfo class provides information about URL requests.
+
+    The QWebEngineUrlRequestInfo is useful for setting extra header fields for requests
+    or for redirecting certain requests without payload data to another URL.
+    This class cannot be instantiated or copied by the user, instead it will
+    be created by Qt WebEngine and sent through the virtual function
+    QWebEngineUrlRequestInterceptor::interceptRequest() if an interceptor has been set.
+*/
+
+/*!
+    \class QWebEngineUrlRequestInterceptor
+    \inmodule QtWebEngineCore
+    \since 5.6
+    \brief The QWebEngineUrlRequestInterceptor class provides an abstract base class for URL interception.
+
+    Implementing the \l{QWebEngineUrlRequestInterceptor} interface and installing the
+    interceptor on the profile enables intercepting, blocking, and modifying URL requests
+    before they reach the networking stack of Chromium.
+
+    \sa QWebEngineUrlRequestInterceptor::interceptRequest, QWebEngineUrlRequestInfo
+*/
+
+/*!
+    \fn QWebEngineUrlRequestInterceptor::QWebEngineUrlRequestInterceptor(QObject * p = 0)
+
+    Creates a new QWebEngineUrlRequestInterceptor object with \a p as parent.
+*/
+
+/*!
+    \fn QWebEngineUrlRequestInterceptor::~QWebEngineUrlRequestInterceptor()
+
+    Destroys this QWebEngineUrlRequestInterceptor object.
+*/
+
+/*!
+    \fn bool QWebEngineUrlRequestInterceptor::interceptRequest(QWebEngineUrlRequestInfo &info)
+
+    Reimplementing this virtual function and setting the interceptor on a profile makes
+    it possible to intercept URL requests. This function is executed on the IO thread,
+    and therefore running long tasks here will block networking.
+    If this function is only used for inspection, it should return \c false, in which
+    case any modification to \a info will be ignored.
+
+    \sa QWebEngineProfile::setRequestInterceptor
+*/
+
+
 QWebEngineUrlRequestInfoPrivate::QWebEngineUrlRequestInfoPrivate(QWebEngineUrlRequestInfo::ResourceType resource, QWebEngineUrlRequestInfo::NavigationType navigation, const QUrl &u, const QByteArray &m)
     : resourceType(resource)
     , navigationType(navigation)
@@ -77,53 +128,134 @@ QWebEngineUrlRequestInfoPrivate::QWebEngineUrlRequestInfoPrivate(QWebEngineUrlRe
 {
 }
 
+/*!
+    \internal
+*/
+
 QWebEngineUrlRequestInfo::~QWebEngineUrlRequestInfo()
 {
 
 }
 
+/*!
+    \internal
+*/
+
 QWebEngineUrlRequestInfo::QWebEngineUrlRequestInfo(QWebEngineUrlRequestInfoPrivate *p)
     : d_ptr(p)
 {
     d_ptr->q_ptr = this;
 }
 
+/*!
+    \enum QWebEngineUrlRequestInfo::ResourceType
+
+    This enum type holds the type of the requested resource:
+
+    \value ResourceTypeMainFrame Top level page.
+    \value ResourceTypeSubFrame  Frame or iframe.
+    \value ResourceTypeStylesheet  A CSS stylesheet.
+    \value ResourceTypeScript  An external script.
+    \value ResourceTypeImage  An image (JPG, GIF, PNG, and so on).
+    \value ResourceTypeFontResource  A font.
+    \value ResourceTypeSubResource  An "other" subresource.
+    \value ResourceTypeObject  An object (or embed) tag for a plugin or a resource that a plugin requested.
+    \value ResourceTypeMedia  A media resource.
+    \value ResourceTypeWorker  The main resource of a dedicated worker.
+    \value ResourceTypeSharedWorker  The main resource of a shared worker.
+    \value ResourceTypePrefetch  An explicitly requested prefetch.
+    \value ResourceTypeFavicon  A favicon.
+    \value ResourceTypeXhr  An XMLHttpRequest.
+    \value ResourceTypePing  A ping request for <a ping>.
+    \value ResourceTypeServiceWorker  The main resource of a service worker.
+    \value ResourceTypeUnknown  Unknown request type.
+*/
+
+/*!
+    Returns the resource type of the request.
+
+    \sa QWebEngineUrlRequestInfo::ResourceType
+*/
+
 QWebEngineUrlRequestInfo::ResourceType QWebEngineUrlRequestInfo::resourceType() const
 {
     Q_D(const QWebEngineUrlRequestInfo);
     return d->resourceType;
 }
 
+/*!
+    \enum QWebEngineUrlRequestInfo::NavigationType
+
+    This enum type describes the navigation type of the request:
+
+    \value NavigationTypeLink Navigation initiated by clicking a link.
+    \value NavigationTypeTyped Navigation explicitly initiated by typing a URL.
+    \value NavigationTypeFormSubmitted Navigation submits a form.
+    \value NavigationTypeBackForward Navigation initiated by a history action.
+    \value NavigationTypeReload Navigation initiated by refreshing the page.
+    \value NavigationTypeOther None of the above.
+*/
+
+/*!
+    Returns the navigation type of the request.
+
+    \sa QWebEngineUrlRequestInfo::NavigationType
+*/
+
 QWebEngineUrlRequestInfo::NavigationType QWebEngineUrlRequestInfo::navigationType() const
 {
     Q_D(const QWebEngineUrlRequestInfo);
     return d->navigationType;
 }
 
+/*!
+    Returns the request URL.
+*/
+
 const QUrl &QWebEngineUrlRequestInfo::url() const
 {
     Q_D(const QWebEngineUrlRequestInfo);
     return d->url;
 }
 
+
+/*!
+    Returns the HTTP method of the request (for example, GET or POST).
+*/
+
 const QByteArray &QWebEngineUrlRequestInfo::method() const
 {
     Q_D(const QWebEngineUrlRequestInfo);
     return d->method;
 }
 
+/*!
+    Redirects this request to \a url.
+    It is only possible to redirect requests that do not have payload data, such as GET requests.
+*/
+
 void QWebEngineUrlRequestInfo::redirectTo(const QUrl &url)
 {
     Q_D(QWebEngineUrlRequestInfo);
     d->url = url;
 }
 
+/*!
+    Blocks this request if \a shouldBlock is true, so that it will not proceed.
+
+    This function can be used to prevent navigating away from a given domain, for example.
+*/
+
 void QWebEngineUrlRequestInfo::blockRequest(bool shouldBlock)
 {
     Q_D(QWebEngineUrlRequestInfo);
     d->shouldBlockRequest = shouldBlock;
 }
 
+/*!
+    Sets an extra request header for this request with \a name and \a value.
+*/
+
 void QWebEngineUrlRequestInfo::setExtraHeader(const QByteArray &name, const QByteArray &value)
 {
     Q_D(QWebEngineUrlRequestInfo);