From f90e0c5661b921528e41fe2404689a7e90c16895 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Thu, 27 Jun 2019 02:33:10 -0700 Subject: [PATCH] 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 4c9b67b13b4..1abed4e717a 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 b981af6afe6..fcad2ccf0a2 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 `\\=''." -- 2.39.2