QUrlQuery/Doc: update the information about encoded vs decoded

This class was not subject to the QUrl API update that took place
between 5.0 and 5.1 that changed the QUrl string defaults and added
QUrl::ParsingMode. It always parses as TolerantMode.

Fixes: QTBUG-95254
Change-Id: I37d93a60a0d649688bddfffd169348d874eacc92
Reviewed-by: Oswald Buddenhagen <oswald.buddenhagen@gmx.de>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

1 files changed, 28 insertions, 1 deletions

diff --git a/src/corelib/io/qurlquery.cpp b/src/corelib/io/qurlquery.cpp
index c469c51ea9..637e6c3c01 100644
--- a/src/corelib/io/qurlquery.cpp
+++ b/src/corelib/io/qurlquery.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 Intel Corporation.
+** Copyright (C) 2021 Intel Corporation.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the QtCore module of the Qt Toolkit.
@@ -89,6 +89,19 @@ QT_BEGIN_NAMESPACE
   sequences not decodable to UTF-8). For that reason, the percent character is
   always represented by the string "%25".
 
+  All of the setter methods and the query methods like hasQueryItem() in
+  QUrlQuery take encoded forms only. Unlike in QUrl, there's no optional
+  parameter to specify that the strings being passed are decoded. If
+  improperly-encoded strings are passed to the setter or query methods,
+  QUrlQuery will attempt to recover instead of failing. That is to say, all
+  functions in this class parse their string arguments as if the
+  {{QUrl::TolerantMode}} decoding mode was specified.
+
+  Application code should strive to always ensure proper encoding and not rely
+  on TolerantMode parsing fixing the strings. Notably, all user input must be
+  first percent-encoded using QUrl::toPercentEncoding() or similar functions
+  before being passed to the functions in this class.
+
   \section2 Handling of spaces and plus ("+")
 
   Web browsers usually encode spaces found in HTML FORM elements to a plus sign
@@ -618,6 +631,8 @@ QChar QUrlQuery::queryPairDelimiter() const
     as the same, like HTML forms do. If you need spaces to be represented as
     plus signs, use actual plus signs.
 
+    \note The keys and values are expected to be in percent-encoded form.
+
     \sa queryItems(), isEmpty()
 */
 void QUrlQuery::setQueryItems(const QList<QPair<QString, QString> > &query)
@@ -662,6 +677,8 @@ QList<QPair<QString, QString> > QUrlQuery::queryItems(QUrl::ComponentFormattingO
     Returns \c true if there is a query string pair whose key is equal
     to \a key from the URL.
 
+    \note The key expected to be in percent-encoded form.
+
     \sa addQueryItem(), queryItemValue()
 */
 bool QUrlQuery::hasQueryItem(const QString &key) const
@@ -680,6 +697,8 @@ bool QUrlQuery::hasQueryItem(const QString &key) const
     as the same, like HTML forms do. If you need spaces to be represented as
     plus signs, use actual plus signs.
 
+    \note The key and value strings are expected to be in percent-encoded form.
+
     \sa hasQueryItem(), queryItemValue()
 */
 void QUrlQuery::addQueryItem(const QString &key, const QString &value)
@@ -698,6 +717,8 @@ void QUrlQuery::addQueryItem(const QString &key, const QString &value)
     one found, in the order they were present in the query string or added
     using addQueryItem().
 
+    \note The key is expected to be in percent-encoded form.
+
     \sa addQueryItem(), allQueryItemValues(), {encoding}{Encoding}
 */
 QString QUrlQuery::queryItemValue(const QString &key, QUrl::ComponentFormattingOptions encoding) const
@@ -716,6 +737,8 @@ QString QUrlQuery::queryItemValue(const QString &key, QUrl::ComponentFormattingO
     the URL, using the options specified in \a encoding to encode the return
     value. If the key \a key is not found, this function returns an empty list.
 
+    \note The key is expected to be in percent-encoded form.
+
     \sa queryItemValue(), addQueryItem()
 */
 QStringList QUrlQuery::allQueryItemValues(const QString &key, QUrl::ComponentFormattingOptions encoding) const
@@ -738,6 +761,8 @@ QStringList QUrlQuery::allQueryItemValues(const QString &key, QUrl::ComponentFor
     item in the order they were present in the query string or added with
     addQueryItem().
 
+    \note The key is expected to be in percent-encoded form.
+
     \sa removeAllQueryItems()
 */
 void QUrlQuery::removeQueryItem(const QString &key)
@@ -754,6 +779,8 @@ void QUrlQuery::removeQueryItem(const QString &key)
     Removes all the query string pairs whose key is equal to \a key
     from the URL.
 
+    \note The key is expected to be in percent-encoded form.
+
     \sa removeQueryItem()
 */
 void QUrlQuery::removeAllQueryItems(const QString &key)