Commit f90e0c56 authored by Stefan Kangas's avatar Stefan Kangas Committed by Paul Eggert
Browse files

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.
parent ee757886
......@@ -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
......
......@@ -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 `\\=''."
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment