procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Include interactive-only information in describe-function output

Browse source 
* 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.
This commit is contained in:
Glenn Morris 2014-03-22 15:36:29 -07:00
parent 5076d27513
commit f9c81e7b48
10 changed files with 73 additions and 44 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
doc/lispref/ChangeLog
View file

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

13
doc/lispref/commands.texi
View file

@ -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}.

1
etc/NEWS
View file

@ -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

14
lisp/ChangeLog
View file

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

4
lisp/bookmark.el
View file

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

20
lisp/epa-mail.el
View file

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

6
lisp/epa.el
View file

@ -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

1
lisp/files.el
View file

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

27
lisp/help-fns.el
View file

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

28
lisp/simple.el
View file

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