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}
{RFC 9110 Chapters 5.1 and 5.5}.
Broadly speaking, this means:
In all, this means:
\list
\li \c name must consist of visible ASCII characters, and must not be
empty
@ -44,10 +44,9 @@ Q_LOGGING_CATEGORY(lcQHttpHeaders, "qt.network.http.headers");
may be empty
\endlist
Furthermore, \e value may have historically contained leading or
trailing whitespace, which has to be ignored while processing such
values. The setters of this class automatically remove any such
whitespace.
The setters of this class automatically remove any leading or trailing
whitespaces from \e value, as they must be ignored during the
\e value processing.
\section1 Combining values
@ -62,11 +61,10 @@ Q_LOGGING_CATEGORY(lcQHttpHeaders, "qt.network.http.headers");
myheadername: myheadervalue1,myheadervalue2
\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}
{Set-Cookie}. Due to this, as well as due to the possibility
of custom use cases, QHttpHeaders does not automatically combine
the values.
{Set-Cookie}. Due to this and the possibility of custom use cases,
QHttpHeaders does not automatically combine the values.
*/
// 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.
The returned request's URL is formed by appending the provided \a path
and \a query to the baseUrl (which may itself have a path component).
The returned requests URL is formed by appending the provided \a path
and \a query to the baseUrl (which may have a path component).
If the provided \a path contains query items, they will be combined
with the items in \a query.
@ -276,13 +276,13 @@ void QNetworkRequestFactory::clearCommonHeaders()
The bearer token, if present, is used to set the
\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
and the service provider's website/dashboard. It's common that the bearer
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 have the latest, valid, token.
The means to acquire the bearer token vary. Standard methods include \c OAuth2
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,
always setting the new token again ensures that subsequent requests have
the latest, valid token.
The presence of the bearer token does not impact the \l commonHeaders()
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.
QRestAccessManager and related QRestReply classes can only be used in the
thread they live in. For further information see
\l {QObject#Thread Affinity}{QObject thread affinity} documentation.
thread they live in. See \l {QObject#Thread Affinity}{QObject thread affinity}
for more information.
\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.
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
source encoding, if available. If the encoding information is not
available or not supported by \l QStringConverter, UTF-8 is used as a
default.
source encoding. If the encoding information is not available or not supported
by \l QStringConverter, UTF-8 is used by default.
Calling this function consumes the data received so far. Returns
a default constructed value if no new data is available, or if the
@ -196,8 +195,8 @@ QString QRestReply::readText()
yet).
\note The HTTP status is reported as indicated by the received HTTP
response. It is possible that an error() occurs after receiving the status,
for instance due to network disconnection while receiving a long response.
response. An error() may occur after receiving the status, for instance
due to network disconnection while receiving a long response.
These potential subsequent errors are not represented by the reported
HTTP status.
@ -212,7 +211,7 @@ int QRestReply::httpStatus() const
\fn bool QRestReply::isSuccess() const
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
is a convenient way to check whether the response is considered successful.