Bug #649974: make docstrings for url2pathname consistent

4 files changed, 25 insertions, 21 deletions

diff --git a/Lib/macurl2path.py b/Lib/macurl2path.py
index ed23883..4c5ae64 100644
--- a/Lib/macurl2path.py
+++ b/Lib/macurl2path.py
@@ -8,7 +8,8 @@ import os
 __all__ = ["url2pathname","pathname2url"]
 
 def url2pathname(pathname):
-    "Convert /-delimited pathname to mac pathname"
+    """OS-specific conversion from a relative URL of the 'file' scheme
+    to a file system path; not recommended for general use."""
     #
     # XXXX The .. handling should be fixed...
     #
@@ -49,7 +50,8 @@ def url2pathname(pathname):
     return urllib.unquote(rv)
 
 def pathname2url(pathname):
-    "convert mac pathname to /-delimited pathname"
+    """OS-specific conversion from a file system path to a relative URL
+    of the 'file' scheme; not recommended for general use."""
     if '/' in pathname:
         raise RuntimeError, "Cannot convert pathname containing slashes"
     components = pathname.split(':')
diff --git a/Lib/nturl2path.py b/Lib/nturl2path.py
index 2ced9a9..31064044 100644
--- a/Lib/nturl2path.py
+++ b/Lib/nturl2path.py
@@ -1,14 +1,12 @@
 """Convert a NT pathname to a file URL and vice versa."""
 
 def url2pathname(url):
-    r"""Convert a URL to a DOS path.
-
-            ///C|/foo/bar/spam.foo
-
-                    becomes
-
-            C:\foo\bar\spam.foo
-    """
+    """OS-specific conversion from a relative URL of the 'file' scheme
+    to a file system path; not recommended for general use."""
+    # e.g.
+    # ///C|/foo/bar/spam.foo
+    # becomes
+    # C:\foo\bar\spam.foo
     import string, urllib
     # Windows itself uses ":" even in URLs.
     url = url.replace(':', '|')
@@ -35,15 +33,12 @@ def url2pathname(url):
     return path
 
 def pathname2url(p):
-    r"""Convert a DOS path name to a file url.
-
-            C:\foo\bar\spam.foo
-
-                    becomes
-
-            ///C|/foo/bar/spam.foo
-    """
-
+    """OS-specific conversion from a file system path to a relative URL
+    of the 'file' scheme; not recommended for general use."""
+    # e.g.
+    # C:\foo\bar\spam.foo
+    # becomes
+    # ///C|/foo/bar/spam.foo
     import urllib
     if not ':' in p:
         # No drive specifier, just convert slashes and quote the name
diff --git a/Lib/plat-riscos/rourl2path.py b/Lib/plat-riscos/rourl2path.py
index 7642b9f..7a8badf 100644
--- a/Lib/plat-riscos/rourl2path.py
+++ b/Lib/plat-riscos/rourl2path.py
@@ -11,7 +11,8 @@ __all__ = ["url2pathname","pathname2url"]
 __slash_dot = string.maketrans("/.", "./")
 
 def url2pathname(url):
-    "Convert URL to a RISC OS path."
+    """OS-specific conversion from a relative URL of the 'file' scheme
+    to a file system path; not recommended for general use."""
     tp = urllib.splittype(url)[0]
     if tp and tp <> 'file':
         raise RuntimeError, 'Cannot convert non-local URL to pathname'
@@ -46,7 +47,8 @@ def url2pathname(url):
     return '.'.join(components)
 
 def pathname2url(pathname):
-    "Convert a RISC OS path name to a file url."
+    """OS-specific conversion from a file system path to a relative URL
+    of the 'file' scheme; not recommended for general use."""
     return urllib.quote('///' + pathname.translate(__slash_dot), "/$:")
 
 def test():
diff --git a/Lib/urllib.py b/Lib/urllib.py
index f700d71..802d9b7 100644
--- a/Lib/urllib.py
+++ b/Lib/urllib.py
@@ -50,8 +50,13 @@ elif os.name == 'riscos':
     from rourl2path import url2pathname, pathname2url
 else:
     def url2pathname(pathname):
+        """OS-specific conversion from a relative URL of the 'file' scheme
+        to a file system path; not recommended for general use."""
         return unquote(pathname)
+
     def pathname2url(pathname):
+        """OS-specific conversion from a file system path to a relative URL
+        of the 'file' scheme; not recommended for general use."""
         return quote(pathname)
 
 # This really consists of two pieces: