Clarify url-http and url-retrieve-internal docstrings

* lisp/url/url-http.el (url-http): Same. 

* lisp/url/url.el (url-retrieve-internal): Clarify the docstring.

Fixes: debbugs:18116

3 files changed, 10 insertions, 4 deletions

diff --git a/lisp/url/ChangeLog b/lisp/url/ChangeLog
index 4880bfea30b..dfaf6f8c529 100644
--- a/lisp/url/ChangeLog
+++ b/lisp/url/ChangeLog
@@ -1,3 +1,9 @@
+2014-09-19  Dmitry  <dgutov@yandex.ru>
+
+        * url.el (url-retrieve-internal): Clarify the docstring.
+
+        * url-http.el (url-http): Same.  (Bug#18116)
+
 2014-06-26  Leo Liu  <sdl.web@gmail.com>
 
         * url-http.el (url-http-end-of-headers): Remove duplicate defvar.
diff --git a/lisp/url/url-http.el b/lisp/url/url-http.el
index dcb86689ca9..b0a3b688a55 100644
--- a/lisp/url/url-http.el
+++ b/lisp/url/url-http.el
@@ -1170,8 +1170,8 @@ the end of the document."
   "Retrieve URL via HTTP asynchronously.
 URL must be a parsed URL.  See `url-generic-parse-url' for details.
 
-When retrieval is completed, execute the function CALLBACK, using
-the arguments listed in CBARGS.  The first element in CBARGS
+When retrieval is completed, execute the function CALLBACK, passing it
+an updated value of CBARGS as arguments.  The first element in CBARGS
 should be a plist describing what has happened so far during the
 request, as described in the docstring of `url-retrieve' (if in
 doubt, specify nil).
diff --git a/lisp/url/url.el b/lisp/url/url.el
index cbbcfd4f18b..ca18d718dcb 100644
--- a/lisp/url/url.el
+++ b/lisp/url/url.el
@@ -170,8 +170,8 @@ URL-encoded before it's used."
 (defun url-retrieve-internal (url callback cbargs &optional silent
                                   inhibit-cookies)
   "Internal function; external interface is `url-retrieve'.
-CBARGS is the list of arguments that the callback function will
-receive; its first element should be a plist specifying what has
+The callback function will receive an updated value of CBARGS as
+arguments; its first element should be a plist specifying what has
 happened so far during the request, as described in the docstring
 of `url-retrieve' (if in doubt, specify nil).