[Emacs-diffs] trunk r116843: Include interactive-only information in describe-function output

[Glenn Morris]

------------------------------------------------------------
revno: 116843
revision-id: address@hidden
parent: address@hidden
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sat 2014-03-22 15:36:29 -0700
message:
  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.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/commands.texi      
commands.texi-20091113204419-o5vbwnq5f7feedwu-6165
  etc/NEWS                       news-20100311060928-aoit31wvzf25yr1z-1
  lisp/ChangeLog                 changelog-20091113204419-o5vbwnq5f7feedwu-1432
  lisp/bookmark.el               bookmark.el-20091113204419-o5vbwnq5f7feedwu-621
  lisp/epa-mail.el               epamail.el-20091113204419-o5vbwnq5f7feedwu-8555
  lisp/epa.el                    epa.el-20091113204419-o5vbwnq5f7feedwu-8557
  lisp/files.el                  files.el-20091113204419-o5vbwnq5f7feedwu-265
  lisp/help-fns.el               helpfns.el-20091113204419-o5vbwnq5f7feedwu-2354
  lisp/simple.el                 simple.el-20091113204419-o5vbwnq5f7feedwu-403

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-03-22 22:12:52 +0000
+++ b/doc/lispref/ChangeLog     2014-03-22 22:36:29 +0000
@@ -1,5 +1,8 @@
 2014-03-22  Glenn Morris  <address@hidden>
 
+       * 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.
 

=== modified file 'doc/lispref/commands.texi'
--- a/doc/lispref/commands.texi 2014-03-22 22:12:52 +0000
+++ b/doc/lispref/commands.texi 2014-03-22 22:36:29 +0000
@@ -128,12 +128,13 @@
 never directly from Lisp.  In that case, give the function a
 address@hidden @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}.

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2014-03-22 22:12:52 +0000
+++ b/etc/NEWS  2014-03-22 22:36:29 +0000
@@ -54,6 +54,7 @@
 
 +++
 ** 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

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2014-03-22 22:12:52 +0000
+++ b/lisp/ChangeLog    2014-03-22 22:36:29 +0000
@@ -1,5 +1,19 @@
 2014-03-22  Glenn Morris  <address@hidden>
 
+       * 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.

=== modified file 'lisp/bookmark.el'
--- a/lisp/bookmark.el  2014-01-01 07:43:34 +0000
+++ b/lisp/bookmark.el  2014-03-22 22:36:29 +0000
@@ -1298,8 +1298,8 @@
 
 ;;;###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))

=== modified file 'lisp/epa-mail.el'
--- a/lisp/epa-mail.el  2014-01-01 07:43:34 +0000
+++ b/lisp/epa-mail.el  2014-03-22 22:36:29 +0000
@@ -70,27 +70,24 @@
 ;;;###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 @@
 ;;;###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)))
 

=== modified file 'lisp/epa.el'
--- a/lisp/epa.el       2014-02-06 04:05:43 +0000
+++ b/lisp/epa.el       2014-03-22 22:36:29 +0000
@@ -834,6 +834,7 @@
 
 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 @@
   (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 @@
 
 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 @@
   (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 @@
     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 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

=== modified file 'lisp/files.el'
--- a/lisp/files.el     2014-03-22 22:12:52 +0000
+++ b/lisp/files.el     2014-03-22 22:36:29 +0000
@@ -4999,6 +4999,7 @@
 
 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"))

=== modified file 'lisp/help-fns.el'
--- a/lisp/help-fns.el  2014-03-14 00:32:41 +0000
+++ b/lisp/help-fns.el  2014-03-22 22:36:29 +0000
@@ -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: address@hidden
 ;; Keywords: help, internal
@@ -430,6 +430,28 @@
       (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 @@
 
 ;; 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)
 

=== modified file 'lisp/simple.el'
--- a/lisp/simple.el    2014-03-22 22:12:52 +0000
+++ b/lisp/simple.el    2014-03-22 22:36:29 +0000
@@ -870,10 +870,7 @@
 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 @@
 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 @@
 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 @@
 (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 @@
 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 @@
 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")