Merge remote-tracking branch 'origin/5.8' into devv5.9.0-alpha1

Conflicts:
	.qmake.conf

Change-Id: I602be0ed9a7f23e94a0fb5099488b7c54e39a421

3 files changed, 196 insertions, 10 deletions

diff --git a/src/oauth/qabstractoauth.cpp b/src/oauth/qabstractoauth.cpp
index 0f34fa2..9a53b46 100644
--- a/src/oauth/qabstractoauth.cpp
+++ b/src/oauth/qabstractoauth.cpp
@@ -152,25 +152,82 @@ QT_BEGIN_NAMESPACE
 /*!
     \property QAbstractOAuth::authorizationUrl
     \brief This property holds the URL used to request the Resource
-    Owner Authorization.
-
-    \b {See also} \l {https://tools.ietf.org/html/rfc5849#section-2.2}
-    {The OAuth 1.0 Protocol: Resource Owner Authorization}.
+    Owner Authorization as described in:
+    \l{https://tools.ietf.org/html/rfc5849#section-2.2}{The OAuth
+    1.0 Protocol: Resource Owner Authorization}
 */
 
 /*!
-    \fn void QAbstractOAuth::authorizeWithBrowser(const QUrl &url)
-    This signal is emitted when the URL \a url, generated by
-    resourceOwnerAuthorization(), is ready to be used in the web
+    \fn void authorizeWithBrowser(const QUrl &url)
+
+    This signal is emitted when the URL generated by
+    \a resourceOwnerAuthorization is ready to be used in the web
     browser to allow the application to impersonate the user.
 */
 
 /*!
-    \fn void QAbstractOAuth::granted()
+    \fn void granted()
+
     This signal is emitted when the authorization flow finishes
     successfully.
 */
 
+/*!
+    \fn QNetworkReply *head(const QUrl &url, const QVariantMap &parameters)
+
+    Posts an authenticated HEAD request and returns a new
+    QNetworkReply. The \a url and \a parameters are used to create
+    the request.
+
+    \b {See also}: \l {https://tools.ietf.org/html/rfc2616#section-9.4}
+    {Hypertext Transfer Protocol -- HTTP/1.1: HEAD}
+*/
+
+/*!
+    \fn QNetworkReply *get(const QUrl &url, const QVariantMap &parameters)
+
+    Posts an authenticated GET request and returns a new
+    QNetworkReply. The \a url and \a parameters are used to create
+    the request.
+
+    \b {See also}: \l {https://tools.ietf.org/html/rfc2616#section-9.3}
+    {Hypertext Transfer Protocol -- HTTP/1.1: GET}
+*/
+
+/*!
+    \fn QNetworkReply *post(const QUrl &url, const QVariantMap &parameters)
+
+    Posts an authenticated POST request and returns a new
+    QNetworkReply. The \a url and \a parameters are used to create
+    the request.
+
+    \b {See also}: \l {https://tools.ietf.org/html/rfc2616#section-9.5}
+    {Hypertext Transfer Protocol -- HTTP/1.1: POST}
+*/
+
+/*!
+    \fn QNetworkReply *deleteResource(const QUrl &url, const QVariantMap &parameters)
+
+    Posts an authenticated DELETE request and returns a new
+    QNetworkReply. The \a url and \a parameters are used to create
+    the request.
+
+    \b {See also}: \l {https://tools.ietf.org/html/rfc2616#section-9.7}
+    {Hypertext Transfer Protocol -- HTTP/1.1: DELETE}
+*/
+
+/*!
+    \fn void grant()
+
+    Override this function to implement the corresponding
+    authentication flow in the subclasses. Client code calls this
+    function to start the authentication workflow. This may require
+    user interaction: for example, asking the user's authorization
+    via a web browser. When the authentication succeeds, it should
+    emit granted(); this gives notice that credentials are ready to
+    be used in authenticated calls.
+*/
+
 QAbstractOAuthPrivate::QAbstractOAuthPrivate(QNetworkAccessManager *manager) :
     QAbstractOAuthPrivate(QUrl(), manager)
 {}
@@ -408,7 +465,7 @@ void QAbstractOAuth::resourceOwnerAuthorization(const QUrl &url, const QVariantM
     The parameter \a length determines the size of the generated
     string.
 
-    \b {See also} \l {https://tools.ietf.org/html/rfc5849#section-3.3}{The
+    \b {See also}: \l {https://tools.ietf.org/html/rfc5849#section-3.3}{The
     OAuth 1.0 Protocol: Nonce and Timestamp}.
 */
 QByteArray QAbstractOAuth::generateRandomString(quint8 length)
diff --git a/src/oauth/qabstractoauth2.cpp b/src/oauth/qabstractoauth2.cpp
index 5808b97..76a5b12 100644
--- a/src/oauth/qabstractoauth2.cpp
+++ b/src/oauth/qabstractoauth2.cpp
@@ -53,6 +53,79 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \class QAbstractOAuth2
+    \inmodule QtNetworkAuth
+    \ingroup oauth
+    \brief The QAbstractOAuth2 class is the base of all
+    implementations of OAuth 2 authentication methods.
+    \since 5.8
+
+    The class defines the basic interface of the OAuth 2
+    authentication classes. By inheriting this class, you
+    can create custom authentication methods using the OAuth 2
+    standard for different web services.
+
+    A description of how OAuth 2 works can be found in:
+    \l {https://tools.ietf.org/html/rfc6749}{The OAuth 2.0
+    Authorization Framework}
+*/
+/*!
+    \property QAbstractOAuth2::scope
+    \brief This property holds the desired scope which defines the
+    permissions requested by the client.
+*/
+
+/*!
+    \property QAbstractOAuth2::userAgent
+    This property holds the User-Agent header used to create the
+    network requests.
+
+    The default value is "QtOAuth/1.0 (+https://www.qt.io)".
+*/
+
+/*!
+    \property QAbstractOAuth2::clientIdentifier
+    This property holds the client identifier used to identify the
+    application in the authentication process.
+*/
+
+/*!
+    \property QAbstractOAuth2::clientIdentifierSharedKey
+    This property holds the client shared key used as a password if
+    the server requires authentication to request the token.
+*/
+
+/*!
+    \property QAbstractOAuth2::state
+    This property holds the string sent to the server during
+    authentication. The state is used to identify and validate the
+    request when the callback is received.
+*/
+
+/*!
+    \property QAbstractOAuth2::expiration
+    This property holds the expiration time of the current access
+    token.
+*/
+
+/*!
+    \fn QAbstractOAuth2::error(const QString &error, const QString &errorDescription, const QUrl &uri)
+
+    Signal emitted when the server responds to the request with an
+    error: \a error is the name of the error; \a description describes
+    the error and \a uri is an optional URI containing more
+    information about the error.
+*/
+
+/*!
+    \fn QAbstractOAuth2::authorizationCallbackReceived(const QVariantMap &data)
+
+    Signal emitted when the reply server receives the authorization
+    callback from the server: \a data contains the values received
+    from the server.
+*/
+
 using Key = QAbstractOAuth2Private::OAuth2KeyString;
 const QString Key::accessToken =        QStringLiteral("access_token");
 const QString Key::apiKey =             QStringLiteral("api_key");
@@ -78,7 +151,7 @@ QAbstractOAuth2Private::QAbstractOAuth2Private(const QPair<QString, QString> &cl
 {}
 
 QAbstractOAuth2Private::QAbstractOAuth2Private(QNetworkAccessManager *manager) :
-    QAbstractOAuthPrivate(authorizationUrl, manager)
+    QAbstractOAuthPrivate(manager)
 {}
 
 QAbstractOAuth2Private::~QAbstractOAuth2Private()
@@ -106,10 +179,17 @@ QNetworkRequest QAbstractOAuth2Private::createRequest(const QUrl &url, const QVa
     return request;
 }
 
+/*!
+    Constructs a QAbstractOAuth2 object using \a parent as parent.
+*/
 QAbstractOAuth2::QAbstractOAuth2(QObject *parent) :
     QAbstractOAuth2(nullptr, parent)
 {}
 
+/*!
+    Constructs a QAbstractOAuth2 object using \a parent as parent and
+    sets \a manager as the network access manager.
+*/
 QAbstractOAuth2::QAbstractOAuth2(QNetworkAccessManager *manager, QObject *parent) :
     QAbstractOAuth(*new QAbstractOAuth2Private(manager), parent)
 {}
@@ -118,9 +198,16 @@ QAbstractOAuth2::QAbstractOAuth2(QAbstractOAuth2Private &dd, QObject *parent) :
     QAbstractOAuth(dd, parent)
 {}
 
+/*!
+    Destroys the QAbstractOAuth2 instance.
+*/
 QAbstractOAuth2::~QAbstractOAuth2()
 {}
 
+/*!
+    The returned URL is based on \a url, combining it with the given
+    \a parameters and the access token.
+*/
 QUrl QAbstractOAuth2::createAuthenticatedUrl(const QUrl &url, const QVariantMap &parameters)
 {
     Q_D(const QAbstractOAuth2);
@@ -137,6 +224,14 @@ QUrl QAbstractOAuth2::createAuthenticatedUrl(const QUrl &url, const QVariantMap
     return ret;
 }
 
+/*!
+    Sends an authenticated HEAD request and returns a new
+    QNetworkReply. The \a url and \a parameters are used to create
+    the request.
+
+    \b {See also}: \l {https://tools.ietf.org/html/rfc2616#section-9.4}
+    {Hypertext Transfer Protocol -- HTTP/1.1: HEAD}
+*/
 QNetworkReply *QAbstractOAuth2::head(const QUrl &url, const QVariantMap &parameters)
 {
     Q_D(QAbstractOAuth2);
@@ -145,6 +240,14 @@ QNetworkReply *QAbstractOAuth2::head(const QUrl &url, const QVariantMap &paramet
     return reply;
 }
 
+/*!
+    Sends an authenticated GET request and returns a new
+    QNetworkReply. The \a url and \a parameters are used to create
+    the request.
+
+    \b {See also}: \l {https://tools.ietf.org/html/rfc2616#section-9.3}
+    {Hypertext Transfer Protocol -- HTTP/1.1: GET}
+*/
 QNetworkReply *QAbstractOAuth2::get(const QUrl &url, const QVariantMap &parameters)
 {
     Q_D(QAbstractOAuth2);
@@ -154,6 +257,14 @@ QNetworkReply *QAbstractOAuth2::get(const QUrl &url, const QVariantMap &paramete
     return reply;
 }
 
+/*!
+    Sends an authenticated POST request and returns a new
+    QNetworkReply. The \a url and \a parameters are used to create
+    the request.
+
+    \b {See also}: \l {https://tools.ietf.org/html/rfc2616#section-9.5}
+    {Hypertext Transfer Protocol -- HTTP/1.1: POST}
+*/
 QNetworkReply *QAbstractOAuth2::post(const QUrl &url, const QVariantMap &parameters)
 {
     Q_D(QAbstractOAuth2);
@@ -163,6 +274,14 @@ QNetworkReply *QAbstractOAuth2::post(const QUrl &url, const QVariantMap &paramet
     return reply;
 }
 
+/*!
+    Sends an authenticated DELETE request and returns a new
+    QNetworkReply. The \a url and \a parameters are used to create
+    the request.
+
+    \b {See also}: \l {https://tools.ietf.org/html/rfc2616#section-9.7}
+    {Hypertext Transfer Protocol -- HTTP/1.1: DELETE}
+*/
 QNetworkReply *QAbstractOAuth2::deleteResource(const QUrl &url, const QVariantMap &parameters)
 {
     Q_D(QAbstractOAuth2);
diff --git a/src/oauth/qabstractoauthreplyhandler.cpp b/src/oauth/qabstractoauthreplyhandler.cpp
index 6237732..52bf8a0 100644
--- a/src/oauth/qabstractoauthreplyhandler.cpp
+++ b/src/oauth/qabstractoauthreplyhandler.cpp
@@ -54,6 +54,16 @@ QAbstractOAuthReplyHandler::QAbstractOAuthReplyHandler(QObjectPrivate &d, QObjec
     : QObject(d, parent)
 {}
 
+/*!
+    \class QAbstractOAuthReplyHandler
+    \inmodule QtNetworkAuth
+    \ingroup oauth
+    \brief Handles replies to OAuth authentication requests
+    \since 5.8
+
+    The QAbstractOAuthReplyHandler class handles the answers
+    to all OAuth authentication requests
+*/
 QT_END_NAMESPACE
 
 #endif // QT_NO_HTTP