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)