[Emacs-diffs] master f90e0c5 1/2: Clarify error and user-error docstrings

[Paul Eggert]

branch: master
commit f90e0c5661b921528e41fe2404689a7e90c16895
Author: Stefan Kangas <address@hidden>
Commit: Paul Eggert <address@hidden>

    Clarify error and user-error docstrings
    
    * lisp/subr.el (error, user-error)
    * lisp/net/tramp.el (tramp-user-error): Change "pilot error" to "user
    error" and improve documentation.
---
 lisp/net/tramp.el |  2 +-
 lisp/subr.el      | 15 ++++++++++-----
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/lisp/net/tramp.el b/lisp/net/tramp.el
index 4c9b67b..1abed4e 100644
--- a/lisp/net/tramp.el
+++ b/lisp/net/tramp.el
@@ -1860,7 +1860,7 @@ an input event arrives.  The other arguments are passed 
to `tramp-error'."
 
 ;; We must make it a defun, because it is used earlier already.
 (defun tramp-user-error (vec-or-proc fmt-string &rest arguments)
-  "Signal a pilot error."
+  "Signal a user error."
   (unwind-protect
       (apply
        #'tramp-error vec-or-proc
diff --git a/lisp/subr.el b/lisp/subr.el
index b981af6..fcad2cc 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -324,10 +324,12 @@ This function accepts any number of arguments, but 
ignores them."
 
 ;; Signal a compile-error if the first arg is missing.
 (defun error (&rest args)
-  "Signal an error, making a message by passing args to `format-message'.
+  "Signal an error, making a message by passing ARGS to `format-message'.
 In Emacs, the convention is that error messages start with a capital
 letter but *do not* end with a period.  Please follow this convention
 for the sake of consistency.
+Errors cause entry to the debugger when `debug-on-error' is
+non-nil.  This can be overridden by `debug-ignored-errors'.
 
 Note: (error \"%s\" VALUE) makes the message VALUE without
 interpreting format characters like `%', `\\=`', and `\\=''."
@@ -335,13 +337,16 @@ interpreting format characters like `%', `\\=`', and 
`\\=''."
   (signal 'error (list (apply #'format-message args))))
 
 (defun user-error (format &rest args)
-  "Signal a pilot error, making a message by passing args to `format-message'.
-In Emacs, the convention is that error messages start with a capital
-letter but *do not* end with a period.  Please follow this convention
-for the sake of consistency.
+  "Signal a user error, making a message by passing ARGS to `format-message'.
 This is just like `error' except that `user-error's are expected to be the
 result of an incorrect manipulation on the part of the user, rather than the
 result of an actual problem.
+In Emacs, the convention is that error messages start with a capital
+letter but *do not* end with a period.  Please follow this convention
+for the sake of consistency.
+In contrast with other errors, user errors normally do not cause
+entry to the debugger, even when `debug-on-error' is non-nil.
+This can be overridden by `debug-ignored-errors'.
 
 Note: (user-error \"%s\" VALUE) makes the message VALUE without
 interpreting format characters like `%', `\\=`', and `\\=''."