bpo-42967: Fix urllib.parse docs and make logic clearer (GH-24536)

4 files changed, 18 insertions, 12 deletions

diff --git a/Doc/library/urllib.parse.rst b/Doc/library/urllib.parse.rst
index 1a790782392..67c21208196 100644
--- a/Doc/library/urllib.parse.rst
+++ b/Doc/library/urllib.parse.rst
@@ -190,7 +190,8 @@ or on combining URL components into a URL string.
    read. If set, then throws a :exc:`ValueError` if there are more than
    *max_num_fields* fields read.
 
-   The optional argument *separator* is the symbol to use for separating the query arguments. It defaults to `&`.
+   The optional argument *separator* is the symbol to use for separating the
+   query arguments. It defaults to ``&``.
 
    Use the :func:`urllib.parse.urlencode` function (with the ``doseq``
    parameter set to ``True``) to convert such dictionaries into query
@@ -204,8 +205,10 @@ or on combining URL components into a URL string.
       Added *max_num_fields* parameter.
 
    .. versionchanged:: 3.10
-      Added *separator* parameter with the default value of `&`. Python versions earlier than Python 3.10 allowed using both ";" and "&" as
-      query parameter separator. This has been changed to allow only a single separator key, with "&" as the default separator.
+      Added *separator* parameter with the default value of ``&``. Python
+      versions earlier than Python 3.10 allowed using both ``;`` and ``&`` as
+      query parameter separator. This has been changed to allow only a single
+      separator key, with ``&`` as the default separator.
 
 
 .. function:: parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')
@@ -232,7 +235,8 @@ or on combining URL components into a URL string.
    read. If set, then throws a :exc:`ValueError` if there are more than
    *max_num_fields* fields read.
 
-   The optional argument *separator* is the symbol to use for separating the query arguments. It defaults to `&`.
+   The optional argument *separator* is the symbol to use for separating the
+   query arguments. It defaults to ``&``.
 
    Use the :func:`urllib.parse.urlencode` function to convert such lists of pairs into
    query strings.
@@ -244,8 +248,10 @@ or on combining URL components into a URL string.
       Added *max_num_fields* parameter.
 
    .. versionchanged:: 3.10
-      Added *separator* parameter with the default value of `&`. Python versions earlier than Python 3.10 allowed using both ";" and "&" as
-      query parameter separator. This has been changed to allow only a single separator key, with "&" as the default separator.
+      Added *separator* parameter with the default value of ``&``. Python
+      versions earlier than Python 3.10 allowed using both ``;`` and ``&`` as
+      query parameter separator. This has been changed to allow only a single
+      separator key, with ``&`` as the default separator.
 
 
 .. function:: urlunparse(parts)
diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst
index 8a64da1b249..03a877a3d91 100644
--- a/Doc/whatsnew/3.6.rst
+++ b/Doc/whatsnew/3.6.rst
@@ -2447,11 +2447,11 @@ details, see the documentation for ``loop.create_datagram_endpoint()``.
 Notable changes in Python 3.6.13
 ================================
 
-Earlier Python versions allowed using both ";" and "&" as
+Earlier Python versions allowed using both ``;`` and ``&`` as
 query parameter separators in :func:`urllib.parse.parse_qs` and
 :func:`urllib.parse.parse_qsl`.  Due to security concerns, and to conform with
 newer W3C recommendations, this has been changed to allow only a single
-separator key, with "&" as the default.  This change also affects
+separator key, with ``&`` as the default.  This change also affects
 :func:`cgi.parse` and :func:`cgi.parse_multipart` as they use the affected
 functions internally. For more details, please see their respective
 documentation.
diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
index d21921d3dd5..91afffb58a7 100644
--- a/Doc/whatsnew/3.8.rst
+++ b/Doc/whatsnew/3.8.rst
@@ -2238,11 +2238,11 @@ details, see the documentation for ``loop.create_datagram_endpoint()``.
 Notable changes in Python 3.8.8
 ===============================
 
-Earlier Python versions allowed using both ";" and "&" as
+Earlier Python versions allowed using both ``;`` and ``&`` as
 query parameter separators in :func:`urllib.parse.parse_qs` and
 :func:`urllib.parse.parse_qsl`.  Due to security concerns, and to conform with
 newer W3C recommendations, this has been changed to allow only a single
-separator key, with "&" as the default.  This change also affects
+separator key, with ``&`` as the default.  This change also affects
 :func:`cgi.parse` and :func:`cgi.parse_multipart` as they use the affected
 functions internally. For more details, please see their respective
 documentation.
diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst
index 5f4f8ba211b..3086930569d 100644
--- a/Doc/whatsnew/3.9.rst
+++ b/Doc/whatsnew/3.9.rst
@@ -1520,11 +1520,11 @@ become a :exc:`TypeError` in Python 3.10.
 urllib.parse
 ------------
 
-Earlier Python versions allowed using both ";" and "&" as
+Earlier Python versions allowed using both ``;`` and ``&`` as
 query parameter separators in :func:`urllib.parse.parse_qs` and
 :func:`urllib.parse.parse_qsl`.  Due to security concerns, and to conform with
 newer W3C recommendations, this has been changed to allow only a single
-separator key, with "&" as the default.  This change also affects
+separator key, with ``&`` as the default.  This change also affects
 :func:`cgi.parse` and :func:`cgi.parse_multipart` as they use the affected
 functions internally. For more details, please see their respective
 documentation.