* lisp/help-fns.el (help-fns--interactive-only): New function.
(help-fns-describe-function-functions): Add the above function.
* lisp/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.
* lisp/bookmark.el (bookmark-write):
* lisp/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.
* lisp/epa.el (epa-decrypt-armor-in-region, epa-verify-region)
(epa-verify-cleartext-in-region, epa-sign-region, epa-encrypt-region):
* lisp/files.el (not-modified):
* lisp/simple.el (mark-whole-buffer): Mark interactive-only.
* doc/lispref/commands.texi (Defining Commands):
Mention that interactive-only also affects describe-function.
* etc/NEWS: Mention this.
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.
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}.
+++
** You can specify a function's interactive-only property via `declare'.
+However you specify it, the property affects `describe-function' output.
\f
* Changes in Emacs 24.5 on Non-Free Operating Systems
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.
;;;###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))
;;;###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))
;;;###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)))
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
(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)
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
(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
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))
;; 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
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"))
;;; 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
(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)
;; 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)
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)
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))
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)
(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
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))
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")