From 8841b96f5a9490add79924991cb2fc8d54764109 Mon Sep 17 00:00:00 2001
From: Markus Unterwaditzer <markus@unterwaditzer.net>
Date: Fri, 5 Sep 2014 18:20:20 +0200
Subject: [PATCH] Document ``werkzeug.urls`` in full detail.

---
 docs/contents.rst.inc |  1 +
 docs/urls.rst         |  6 ++++++
 docs/utils.rst        | 27 +--------------------------
 werkzeug/urls.py      | 16 ++++++++++++----
 4 files changed, 20 insertions(+), 30 deletions(-)
 create mode 100644 docs/urls.rst

diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc
index 975dc9611..7615eaeaa 100644
--- a/docs/contents.rst.inc
+++ b/docs/contents.rst.inc
@@ -39,6 +39,7 @@ Reference
    http
    datastructures
    utils
+   urls
    local
    middlewares
    exceptions
diff --git a/docs/urls.rst b/docs/urls.rst
new file mode 100644
index 000000000..f97e54bf5
--- /dev/null
+++ b/docs/urls.rst
@@ -0,0 +1,6 @@
+===========
+URL Helpers
+===========
+
+.. automodule:: werkzeug.urls
+   :members:
diff --git a/docs/utils.rst b/docs/utils.rst
index 99af0acf1..89b6ef9d1 100644
--- a/docs/utils.rst
+++ b/docs/utils.rst
@@ -49,32 +49,7 @@ General Helpers
 URL Helpers
 ===========
 
-.. module:: werkzeug.urls
-
-.. autoclass:: Href
-
-.. autofunction:: url_decode
-
-.. autofunction:: url_decode_stream
-
-.. autofunction:: url_encode
-
-.. autofunction:: url_encode_stream
-
-.. autofunction:: url_quote
-
-.. autofunction:: url_quote_plus
-
-.. autofunction:: url_unquote
-
-.. autofunction:: url_unquote_plus
-
-.. autofunction:: url_fix
-
-.. autofunction:: uri_to_iri
-
-.. autofunction:: iri_to_uri
-
+Please refer to :doc:`urls`.
 
 UserAgent Parsing
 =================
diff --git a/werkzeug/urls.py b/werkzeug/urls.py
index 93be6ba1a..0fdb8c042 100644
--- a/werkzeug/urls.py
+++ b/werkzeug/urls.py
@@ -3,7 +3,14 @@
     werkzeug.urls
     ~~~~~~~~~~~~~
 
-    This module implements various URL related functions.
+    ``werkzeug.urls`` used to provide several wrapper functions for Python 2
+    urlparse, whose main purpose were to work around the behavior of the Py2
+    stdlib and its lack of unicode support. While this was already a somewhat
+    inconvenient situation, it got even more complicated because Python 3's
+    ``urllib.parse`` actually does handle unicode properly. In other words,
+    this module would wrap two libraries with completely different behavior. So
+    now this module contains a 2-and-3-compatible backport of Python 3's
+    ``urllib.parse``, which is mostly API-compatible.
 
     :copyright: (c) 2014 by the Werkzeug Team, see AUTHORS for more details.
     :license: BSD, see LICENSE for more details.
@@ -37,7 +44,8 @@
     ['scheme', 'netloc', 'path', 'query', 'fragment']))
 
 
-class _URLMixin(object):
+class BaseURL(_URLTuple):
+    '''Superclass of :py:class:`URL` and :py:class:`BytesURL`.'''
     __slots__ = ()
 
     def replace(self, **kwargs):
@@ -268,7 +276,7 @@ def _split_host(self):
 
 
 @implements_to_string
-class URL(_URLTuple, _URLMixin):
+class URL(BaseURL):
     """Represents a parsed URL.  This behaves like a regular tuple but
     also has some extra attributes that give further insight into the
     URL.
@@ -311,7 +319,7 @@ def encode(self, charset='utf-8', errors='replace'):
         )
 
 
-class BytesURL(_URLTuple, _URLMixin):
+class BytesURL(BaseURL):
     """Represents a parsed URL in bytes."""
     __slots__ = ()
     _at = b'@'