1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc: Documentation improvement in QHttpHeaders and REST classes

Browse Source 
Language and some other improvisations

Fixes: QTBUG-120028
Change-Id: Id5a5544abf244de5cff83f0d795732595934bd36
Reviewed-by: Juha Vuolle <juha.vuolle@qt.io>
(cherry picked from commit d7b71294e8267123595593efca397151e4bf2595)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
This commit is contained in:
Jaishree Vyas 2024-02-28 11:53:12 +01:00 committed by Qt Cherry-pick Bot
parent 2c743bc0cb
commit 08868b1c4b
4 changed files with 23 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
src/network/access/qhttpheaders.cpp
View File

@ -35,7 +35,7 @@ Q_LOGGING_CATEGORY(lcQHttpHeaders, "qt.network.http.headers");
\l {https://datatracker.ietf.org/doc/html/rfc9110#name-field-values} \l {https://datatracker.ietf.org/doc/html/rfc9110#name-field-values}
{RFC 9110 Chapters 5.1 and 5.5}. {RFC 9110 Chapters 5.1 and 5.5}.
Broadly speaking, this means: In all, this means:
\list \list
\li \c name must consist of visible ASCII characters, and must not be \li \c name must consist of visible ASCII characters, and must not be
empty empty
@ -44,10 +44,9 @@ Q_LOGGING_CATEGORY(lcQHttpHeaders, "qt.network.http.headers");
may be empty may be empty
\endlist \endlist
Furthermore, \e value may have historically contained leading or The setters of this class automatically remove any leading or trailing
trailing whitespace, which has to be ignored while processing such whitespaces from \e value, as they must be ignored during the
values. The setters of this class automatically remove any such \e value processing.
whitespace.
\section1 Combining values \section1 Combining values
@ -62,11 +61,10 @@ Q_LOGGING_CATEGORY(lcQHttpHeaders, "qt.network.http.headers");
myheadername: myheadervalue1,myheadervalue2 myheadername: myheadervalue1,myheadervalue2
\endcode \endcode
However there is a notable exception to this rule: However, there is a notable exception to this rule:
\l {https://datatracker.ietf.org/doc/html/rfc9110#name-field-order} \l {https://datatracker.ietf.org/doc/html/rfc9110#name-field-order}
{Set-Cookie}. Due to this, as well as due to the possibility {Set-Cookie}. Due to this and the possibility of custom use cases,
of custom use cases, QHttpHeaders does not automatically combine QHttpHeaders does not automatically combine the values.
the values.
*/ */
// This list is from IANA HTTP Field Name Registry // This list is from IANA HTTP Field Name Registry

16
src/network/access/qnetworkrequestfactory.cpp
View File

@ -220,8 +220,8 @@ QNetworkRequest QNetworkRequestFactory::createRequest(const QUrlQuery &query) co
/*! /*!
Returns a QNetworkRequest. Returns a QNetworkRequest.
The returned request's URL is formed by appending the provided \a path The returned requests URL is formed by appending the provided \a path
and \a query to the baseUrl (which may itself have a path component). and \a query to the baseUrl (which may have a path component).
If the provided \a path contains query items, they will be combined If the provided \a path contains query items, they will be combined
with the items in \a query. with the items in \a query.
@ -276,13 +276,13 @@ void QNetworkRequestFactory::clearCommonHeaders()
The bearer token, if present, is used to set the The bearer token, if present, is used to set the
\c {Authorization: Bearer my_token} header for requests. This is a common \c {Authorization: Bearer my_token} header for requests. This is a common
authorization convention and provided as an additional convenience. authorization convention and is provided as an additional convenience.
Means to acquire the bearer token varies. Common methods include \c OAuth2 The means to acquire the bearer token vary. Standard methods include \c OAuth2
and the service provider's website/dashboard. It's common that the bearer and the service provider's website/dashboard. It is expected that the bearer
token changes over time, for example when updated with a refresh token. token changes over time. For example, when updated with a refresh token,
By always re-setting the new token ensures that subsequent requests will always setting the new token again ensures that subsequent requests have
always have the latest, valid, token. the latest, valid token.
The presence of the bearer token does not impact the \l commonHeaders() The presence of the bearer token does not impact the \l commonHeaders()
listing. If the \l commonHeaders() also lists \c Authorization header, it listing. If the \l commonHeaders() also lists \c Authorization header, it

4
src/network/access/qrestaccessmanager.cpp
View File

@ -42,8 +42,8 @@ Q_LOGGING_CATEGORY(lcQrest, "qt.network.access.rest")
take ownership of the wrapped QNetworkAccessManager. take ownership of the wrapped QNetworkAccessManager.
QRestAccessManager and related QRestReply classes can only be used in the QRestAccessManager and related QRestReply classes can only be used in the
thread they live in. For further information see thread they live in. See \l {QObject#Thread Affinity}{QObject thread affinity}
\l {QObject#Thread Affinity}{QObject thread affinity} documentation. for more information.
\section1 Issuing Network Requests and Handling Replies \section1 Issuing Network Requests and Handling Replies

13
src/network/access/qrestreply.cpp
View File

@ -146,11 +146,10 @@ QByteArray QRestReply::readBody()
/*! /*!
Returns the received data as a QString. Returns the received data as a QString.
The received data is decoded into a QString (UTF-16). The decoding The received data is decoded into a QString (UTF-16). If available, the decoding
uses the \e Content-Type header's \e charset parameter to determine the uses the \e Content-Type header's \e charset parameter to determine the
source encoding, if available. If the encoding information is not source encoding. If the encoding information is not available or not supported
available or not supported by \l QStringConverter, UTF-8 is used as a by \l QStringConverter, UTF-8 is used by default.
default.
Calling this function consumes the data received so far. Returns Calling this function consumes the data received so far. Returns
a default constructed value if no new data is available, or if the a default constructed value if no new data is available, or if the
@ -196,8 +195,8 @@ QString QRestReply::readText()
yet). yet).
\note The HTTP status is reported as indicated by the received HTTP \note The HTTP status is reported as indicated by the received HTTP
response. It is possible that an error() occurs after receiving the status, response. An error() may occur after receiving the status, for instance
for instance due to network disconnection while receiving a long response. due to network disconnection while receiving a long response.
These potential subsequent errors are not represented by the reported These potential subsequent errors are not represented by the reported
HTTP status. HTTP status.
@ -212,7 +211,7 @@ int QRestReply::httpStatus() const
\fn bool QRestReply::isSuccess() const \fn bool QRestReply::isSuccess() const
Returns whether the HTTP status is between 200..299 and no Returns whether the HTTP status is between 200..299 and no
further errors have occurred while receiving the response (for example further errors have occurred while receiving the response (for example,
abrupt disconnection while receiving the body data). This function abrupt disconnection while receiving the body data). This function
is a convenient way to check whether the response is considered successful. is a convenient way to check whether the response is considered successful.