cp.get_url: write more verbose docstring

salt/modules/cp.py

@@ -307,21 +307,32 @@ def get_dir(path, dest, saltenv='base', template=None, gzip=None, env=None, **kw
     return _client().get_dir(path, dest, saltenv, gzip)
 
 
-def get_url(path, dest, saltenv='base', env=None):
+def get_url(path, dest='', saltenv='base', env=None):
     '''
     Used to get a single file from a URL
 
-    The default behaviour is to write the fetched file to the given
-    destination path. To simply return the file contents instead, set
-    destination to ``None``.
+    path
+        A URL to download a file from. Supported URL schemes are: ``salt://``,
+        ``http://``, ``https://``, ``ftp://``, ``s3://`` and ``swift://``.
+        The function returns ``False`` if Salt was unable to fetch a file from
+        a ``salt://`` URL.
 
-    Returns ``False`` if Salt was unable to fetch a file from a URL.
+    dest
+        The default behaviour is to write the fetched file to the given
+        destination path. If this parameter is omitted or set as empty string
+        (``''``), the function places the file on the local filesystem inside
+        the Minion cache directory and will return the path to that file.
+        To simply return the file contents instead, set destination to ``None``.
+
+    saltenv : base
+        Salt fileserver envrionment from which to retrieve the file. Ignored if
+        ``path`` is not a ``salt://`` URL.
 
     CLI Example:
 
     .. code-block:: bash
 
-        salt '*' cp.get_url salt://my/file /tmp/mine
+        salt '*' cp.get_url salt://my/file /tmp/this_file_is_mine
         salt '*' cp.get_url http://www.slashdot.org /tmp/index.html
     '''
     if env is not None:

tests/integration/modules/cp.py

@@ -146,7 +146,7 @@ class CPModuleTest(integration.ModuleCase):
 
     def test_get_url(self):
         '''
-        cp.get_url with salt:// source
+        cp.get_url with salt:// source given
         '''
         tgt = os.path.join(integration.TMP, 'scene33')
         self.run_function(
@@ -162,14 +162,12 @@ class CPModuleTest(integration.ModuleCase):
 
     def test_get_url_dest_empty(self):
         '''
-        cp.get_url with salt:// source and destination set as empty string: ''
+        cp.get_url with salt:// source given and destination omitted.
         '''
-        tgt = ''
         ret = self.run_function(
             'cp.get_url',
             [
                 'salt://grail/scene33',
-                tgt,
             ])
         with salt.utils.fopen(ret, 'r') as scene:
             data = scene.read()
@@ -180,7 +178,7 @@ class CPModuleTest(integration.ModuleCase):
 
     def test_get_url_no_dest(self):
         '''
-        cp.get_url with salt:// source and destination set as None
+        cp.get_url with salt:// source given and destination set as None
         '''
         tgt = None
         ret = self.run_function(
@@ -193,7 +191,7 @@ class CPModuleTest(integration.ModuleCase):
 
     def test_get_url_nonexistent_source(self):
         '''
-        cp.get_url with nonexistent salt:// source
+        cp.get_url with nonexistent salt:// source given
         '''
         tgt = None
         ret = self.run_function(
@@ -206,7 +204,7 @@ class CPModuleTest(integration.ModuleCase):
 
     def test_get_url_https(self):
         '''
-        cp.get_url with https:// source
+        cp.get_url with https:// source given
         '''
         tgt = os.path.join(integration.TMP, 'test_get_url_https')
         self.run_function(