Fix documentation of browse-url browser-related functions

* lisp/net/browse-url.el (browse-url)
(browse-url-default-browser, browse-url-default-windows-browser)
(browse-url-default-macosx-browser, browse-url-chromium)
(browse-url-kde, browse-url-text-xterm): Clarify the usage of ARGS
and NEW-WINDOW arguments in these functions.  (Bug#19421)

1 files changed, 21 insertions, 9 deletions

diff --git a/lisp/net/browse-url.el b/lisp/net/browse-url.el
index feb0788db92..d232c8add13 100644
--- a/lisp/net/browse-url.el
+++ b/lisp/net/browse-url.el
@@ -762,12 +762,17 @@ narrowed."
 (defun browse-url (url &rest args)
   "Ask a WWW browser to load URL.
 Prompt for a URL, defaulting to the URL at or before point.
-The variable `browse-url-browser-function' says which browser to use.
-If the URL is a mailto: URL, consult `browse-url-mailto-function'
+Invokes a suitable browser function which does the actual job.
+The variable `browse-url-browser-function' says which browser function to
+use.  If the URL is a mailto: URL, consult `browse-url-mailto-function'
 first, if that exists.
 
-Passes any ARGS to the browser function.
-The default is to pass `browse-url-new-window-flag'."
+The additional ARGS are passed to the browser function.  See the doc
+strings of the actual functions, starting with `browse-url-browser-function',
+for information about the significance of ARGS (most of the functions
+ignore it).
+If ARGS are omitted, the default is to pass `browse-url-new-window-flag'
+as ARGS."
   (interactive (browse-url-interactive-arg "URL: "))
   (unless (called-interactively-p 'interactive)
     (setq args (or args (list browse-url-new-window-flag))))
@@ -836,6 +841,8 @@ says which browser to use."
 (declare-function w32-shell-execute "w32fns.c")    ;; Defined in C.
 
 (defun browse-url-default-windows-browser (url &optional _new-window)
+  "Invoke the MS-Windows system's default Web browser.
+The optional NEW-WINDOW argument is not used."
   (interactive (browse-url-interactive-arg "URL: "))
   (cond ((eq system-type 'ms-dos)
          (if dos-windows-version
@@ -846,6 +853,8 @@ says which browser to use."
         (t (w32-shell-execute "open" url))))
 
 (defun browse-url-default-macosx-browser (url &optional _new-window)
+  "Invoke the MacOS X system's default Web browser.
+The optional NEW-WINDOW argument is not used"
   (interactive (browse-url-interactive-arg "URL: "))
   (start-process (concat "open " url) nil "open" url))
 
@@ -880,8 +889,8 @@ non-nil, load the document in a new window, if possible, otherwise use
 a random existing one.  A non-nil interactive prefix argument reverses
 the effect of `browse-url-new-window-flag'.
 
-When called non-interactively, optional second argument NEW-WINDOW is
-used instead of `browse-url-new-window-flag'."
+When called non-interactively, optional second argument ARGS is used
+instead of `browse-url-new-window-flag'."
   (apply
    (cond
     ((memq system-type '(windows-nt ms-dos cygwin))
@@ -1103,7 +1112,8 @@ instead of `browse-url-new-window-flag'."
   "Ask the Chromium WWW browser to load URL.
 Default to the URL around or before point.  The strings in
 variable `browse-url-chromium-arguments' are also passed to
-Chromium."
+Chromium.
+The optional argument NEW-WINDOW is not used."
   (interactive (browse-url-interactive-arg "URL: "))
   (setq url (browse-url-encode-url url))
   (let* ((process-environment (browse-url-process-environment)))
@@ -1412,7 +1422,8 @@ The `browse-url-gnudoit-program' program is used with options given by
 URL defaults to the URL around or before point.
 This runs the text browser specified by `browse-url-text-browser'.
 in an Xterm window using the Xterm program named by `browse-url-xterm-program'
-with possible additional arguments `browse-url-xterm-args'."
+with possible additional arguments `browse-url-xterm-args'.
+The optional argument NEW-WINDOW is not used."
   (interactive (browse-url-interactive-arg "Text browser URL: "))
   (apply #'start-process `(,(concat browse-url-text-browser url)
                            nil ,browse-url-xterm-program
@@ -1560,7 +1571,8 @@ don't offer a form of remote control."
 ;;;###autoload
 (defun browse-url-kde (url &optional _new-window)
   "Ask the KDE WWW browser to load URL.
-Default to the URL around or before point."
+Default to the URL around or before point.
+The optional argument NEW-WINDOW is not used."
   (interactive (browse-url-interactive-arg "KDE URL: "))
   (message "Sending URL to KDE...")
   (apply #'start-process (concat "KDE " url) nil browse-url-kde-program