Include interactive-only information in describe-function output

* 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.

7 files changed, 62 insertions, 38 deletions

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")