diff options
| -rw-r--r-- | doc/lispref/ChangeLog | 3 | ||||
| -rw-r--r-- | doc/lispref/commands.texi | 13 | ||||
| -rw-r--r-- | etc/NEWS | 1 | ||||
| -rw-r--r-- | lisp/ChangeLog | 14 | ||||
| -rw-r--r-- | lisp/bookmark.el | 4 | ||||
| -rw-r--r-- | lisp/epa-mail.el | 20 | ||||
| -rw-r--r-- | lisp/epa.el | 6 | ||||
| -rw-r--r-- | lisp/files.el | 1 | ||||
| -rw-r--r-- | lisp/help-fns.el | 27 | ||||
| -rw-r--r-- | lisp/simple.el | 28 |
10 files changed, 73 insertions, 44 deletions
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index becce3eea60..870d2dd5d37 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,5 +1,8 @@ 2014-03-22 Glenn Morris <rgm@gnu.org> + * commands.texi (Defining Commands): + Mention that interactive-only also affects describe-function. + * functions.texi (Declare Form): Add interactive-only. * commands.texi (Defining Commands) Mention declare. diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 2b1423101a7..721a485382e 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -128,12 +128,13 @@ form in the function body itself. This feature is seldom used. never directly from Lisp. In that case, give the function a non-@code{nil} @code{interactive-only} property, either directly or via @code{declare} (@pxref{Declare Form}). This causes the -byte compiler to warn if the command is called from Lisp. The value -of the property can be: a string, which the byte-compiler will -use directly in its warning (it should end with a period, -and not start with a capital, e.g. ``use @dots{} instead.''); @code{t}; -any other symbol, which should be an alternative function to use in -Lisp code. +byte compiler to warn if the command is called from Lisp. The output +of @code{describe-function} will include similar information. +The value of the property can be: a string, which the byte-compiler +will use directly in its warning (it should end with a period, and not +start with a capital, e.g. ``use @dots{} instead.''); @code{t}; any +other symbol, which should be an alternative function to use in Lisp +code. @menu * Using Interactive:: General rules for @code{interactive}. @@ -54,6 +54,7 @@ to delete or undelete multiple messages. +++ ** You can specify a function's interactive-only property via `declare'. +However you specify it, the property affects `describe-function' output. * Changes in Emacs 24.5 on Non-Free Operating Systems diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 0854e9d3e57..554f1df5884 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,5 +1,19 @@ 2014-03-22 Glenn Morris <rgm@gnu.org> + * help-fns.el (help-fns--interactive-only): New function. + (help-fns-describe-function-functions): Add the above function. + * simple.el (beginning-of-buffer, end-of-buffer, insert-buffer) + (next-line, previous-line): Remove hand-written interactive-only + information from doc strings, it is auto-generated now. + * bookmark.el (bookmark-write): + * epa-mail.el (epa-mail-decrypt, epa-mail-verify, epa-mail-sign) + (epa-mail-import-keys): Mark interactive-only, + and remove hand-written interactive-only information from doc strings. + * epa.el (epa-decrypt-armor-in-region, epa-verify-region) + (epa-verify-cleartext-in-region, epa-sign-region, epa-encrypt-region): + * files.el (not-modified): + * simple.el (mark-whole-buffer): Mark interactive-only. + * emacs-lisp/byte-run.el (defun-declarations-alist): Add interactive-only. Doc tweak. (macro-declarations-alist): Doc tweak. diff --git a/lisp/bookmark.el b/lisp/bookmark.el index 5307cada0ac..e4e4ed9afcb 100644 --- a/lisp/bookmark.el +++ b/lisp/bookmark.el @@ -1298,8 +1298,8 @@ is greater than `bookmark-alist-modification-count'." ;;;###autoload (defun bookmark-write () - "Write bookmarks to a file (reading the file name with the minibuffer). -Don't use this in Lisp programs; use `bookmark-save' instead." + "Write bookmarks to a file (reading the file name with the minibuffer)." + (declare (interactive-only bookmark-save)) (interactive) (bookmark-maybe-load-default-file) (bookmark-save t)) diff --git a/lisp/epa-mail.el b/lisp/epa-mail.el index 9a096a0a709..d1ed679c0f1 100644 --- a/lisp/epa-mail.el +++ b/lisp/epa-mail.el @@ -70,27 +70,24 @@ USAGE would be `sign' or `encrypt'." ;;;###autoload (defun epa-mail-decrypt () "Decrypt OpenPGP armors in the current buffer. -The buffer is expected to contain a mail message. - -Don't use this command in Lisp programs!" +The buffer is expected to contain a mail message." + (declare (interactive-only t)) (interactive) (epa-decrypt-armor-in-region (point-min) (point-max))) ;;;###autoload (defun epa-mail-verify () "Verify OpenPGP cleartext signed messages in the current buffer. -The buffer is expected to contain a mail message. - -Don't use this command in Lisp programs!" +The buffer is expected to contain a mail message." + (declare (interactive-only t)) (interactive) (epa-verify-cleartext-in-region (point-min) (point-max))) ;;;###autoload (defun epa-mail-sign (start end signers mode) "Sign the current buffer. -The buffer is expected to contain a mail message. - -Don't use this command in Lisp programs!" +The buffer is expected to contain a mail message." + (declare (interactive-only t)) (interactive (save-excursion (goto-char (point-min)) @@ -234,9 +231,8 @@ If no one is selected, symmetric encryption will be performed. " ;;;###autoload (defun epa-mail-import-keys () "Import keys in the OpenPGP armor format in the current buffer. -The buffer is expected to contain a mail message. - -Don't use this command in Lisp programs!" +The buffer is expected to contain a mail message." + (declare (interactive-only t)) (interactive) (epa-import-armor-in-region (point-min) (point-max))) diff --git a/lisp/epa.el b/lisp/epa.el index be439ef241d..0c833ab84d6 100644 --- a/lisp/epa.el +++ b/lisp/epa.el @@ -834,6 +834,7 @@ For example: Don't use this command in Lisp programs! See the reason described in the `epa-decrypt-region' documentation." + (declare (interactive-only t)) (interactive "r") (save-excursion (save-restriction @@ -873,6 +874,7 @@ For example: (decode-coding-string (epg-verify-string context (buffer-substring start end)) 'utf-8))" + (declare (interactive-only t)) (interactive "r") (let ((context (epg-make-context epa-protocol)) plain) @@ -914,6 +916,7 @@ between START and END. Don't use this command in Lisp programs! See the reason described in the `epa-verify-region' documentation." + (declare (interactive-only t)) (interactive "r") (save-excursion (save-restriction @@ -956,6 +959,7 @@ For example: (epg-sign-string context (encode-coding-string (buffer-substring start end) 'utf-8)))" + (declare (interactive-only t)) (interactive (let ((verbose current-prefix-arg)) (setq epa-last-coding-system-specified @@ -1037,6 +1041,7 @@ For example: context (encode-coding-string (buffer-substring start end) 'utf-8) nil))" + (declare (interactive-only t)) (interactive (let ((verbose current-prefix-arg) (context (epg-make-context epa-protocol)) @@ -1205,6 +1210,7 @@ If no one is selected, default public key is exported. "))) ;; If a prefix-arg is specified, the signature is marked as non exportable. ;; Don't use this command in Lisp programs!" +;; (declare (interactive-only t)) ;; (interactive ;; (let ((keys (epa--marked-keys))) ;; (unless keys diff --git a/lisp/files.el b/lisp/files.el index 0bb670bf384..a17677b564d 100644 --- a/lisp/files.el +++ b/lisp/files.el @@ -4999,6 +4999,7 @@ With prefix ARG, mark buffer as modified, so \\[save-buffer] will save. It is not a good idea to use this function in Lisp programs, because it prints a message in the minibuffer. Instead, use `set-buffer-modified-p'." + (declare (interactive-only set-buffer-modified-p)) (interactive "P") (message (if arg "Modification-flag set" "Modification-flag cleared")) diff --git a/lisp/help-fns.el b/lisp/help-fns.el index a186254123d..da4a230468c 100644 --- a/lisp/help-fns.el +++ b/lisp/help-fns.el @@ -1,7 +1,7 @@ ;;; help-fns.el --- Complex help functions -*- lexical-binding: t -*- -;; Copyright (C) 1985-1986, 1993-1994, 1998-2014 Free Software -;; Foundation, Inc. +;; Copyright (C) 1985-1986, 1993-1994, 1998-2014 +;; Free Software Foundation, Inc. ;; Maintainer: emacs-devel@gnu.org ;; Keywords: help, internal @@ -430,6 +430,28 @@ FILE is the file where FUNCTION was probably defined." (setq load-hist (cdr load-hist))) found)) +(defun help-fns--interactive-only (function) + "Insert some help blurb if FUNCTION should only be used interactively." + ;; Ignore lambda constructs, keyboard macros, etc. + (and (symbolp function) + (not (eq (car-safe (symbol-function function)) 'macro)) + (let* ((interactive-only + (or (get function 'interactive-only) + (if (boundp 'byte-compile-interactive-only-functions) + (memq function + byte-compile-interactive-only-functions))))) + (when interactive-only + (insert "\nThis function is for interactive use only" + ;; Cf byte-compile-form. + (cond ((stringp interactive-only) + (format ";\nin Lisp code %s" interactive-only)) + ((and (symbolp 'interactive-only) + (not (eq interactive-only t))) + (format ";\nin Lisp code use `%s' instead." + interactive-only)) + (t ".")) + "\n"))))) + ;;;###autoload (defun describe-function-1 (function) (let* ((advised (and (symbolp function) @@ -554,6 +576,7 @@ FILE is the file where FUNCTION was probably defined." ;; Add defaults to `help-fns-describe-function-functions'. (add-hook 'help-fns-describe-function-functions #'help-fns--obsolete) +(add-hook 'help-fns-describe-function-functions #'help-fns--interactive-only) (add-hook 'help-fns-describe-function-functions #'help-fns--parent-mode) (add-hook 'help-fns-describe-function-functions #'help-fns--compiler-macro) diff --git a/lisp/simple.el b/lisp/simple.el index a41133bada2..453259475f6 100644 --- a/lisp/simple.el +++ b/lisp/simple.el @@ -870,10 +870,7 @@ If the buffer is narrowed, this command uses the beginning of the accessible part of the buffer. If Transient Mark mode is disabled, leave mark at previous -position, unless a \\[universal-argument] prefix is supplied. - -Don't use this command in Lisp programs! -\(goto-char (point-min)) is faster." +position, unless a \\[universal-argument] prefix is supplied." (declare (interactive-only "use `(goto-char (point-min))' instead.")) (interactive "^P") (or (consp arg) @@ -897,10 +894,7 @@ If the buffer is narrowed, this command uses the end of the accessible part of the buffer. If Transient Mark mode is disabled, leave mark at previous -position, unless a \\[universal-argument] prefix is supplied. - -Don't use this command in Lisp programs! -\(goto-char (point-max)) is faster." +position, unless a \\[universal-argument] prefix is supplied." (declare (interactive-only "use `(goto-char (point-max))' instead.")) (interactive "^P") (or (consp arg) (region-active-p) (push-mark)) @@ -1016,6 +1010,7 @@ If narrowing is in effect, only uses the accessible part of the buffer. You probably should not use this function in Lisp programs; it is usually a mistake for a Lisp function to use any subroutine that uses or sets the mark." + (declare (interactive-only t)) (interactive) (push-mark (point)) (push-mark (point-max) nil t) @@ -4240,10 +4235,7 @@ If ARG is zero, move to the beginning of the current line." (defun insert-buffer (buffer) "Insert after point the contents of BUFFER. Puts mark after the inserted text. -BUFFER may be a buffer or a buffer name. - -This function is meant for the user to run interactively. -Don't call it from programs: use `insert-buffer-substring' instead!" +BUFFER may be a buffer or a buffer name." (declare (interactive-only insert-buffer-substring)) (interactive (list @@ -4841,11 +4833,7 @@ this command moves to the specified goal column (or as close as possible). The goal column is stored in the variable `goal-column', which is nil when there is no goal column. Note that setting `goal-column' overrides `line-move-visual' and causes this command to move by buffer -lines rather than by display lines. - -If you are thinking of using this in a Lisp program, consider -using `forward-line' instead. It is usually easier to use -and more reliable (no dependence on goal column, etc.)." +lines rather than by display lines." (declare (interactive-only forward-line)) (interactive "^p\np") (or arg (setq arg 1)) @@ -4888,11 +4876,7 @@ this command moves to the specified goal column (or as close as possible). The goal column is stored in the variable `goal-column', which is nil when there is no goal column. Note that setting `goal-column' overrides `line-move-visual' and causes this command to move by buffer -lines rather than by display lines. - -If you are thinking of using this in a Lisp program, consider using -`forward-line' with a negative argument instead. It is usually easier -to use and more reliable (no dependence on goal column, etc.)." +lines rather than by display lines." (declare (interactive-only "use `forward-line' with negative argument instead.")) (interactive "^p\np") |