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

Don’t document declare-function internals

Browse source 
Suggested by Stefan Monnier in:
http://lists.gnu.org/archive/html/emacs-devel/2016-05/msg00618.html
* doc/lispref/functions.texi (Declaring Functions):
* lisp/subr.el (declare-function):
* lisp/emacs-lisp/bytecomp.el:
(byte-compile-macroexpand-declare-function):
Document as (fn file &optional arglist fileonly)
even though it is really (fn file &rest args).
This commit is contained in:
Paul Eggert 2016-05-27 18:16:24 -07:00
parent 4ce68f8f0f
commit 66cd9187e3
3 changed files with 21 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
doc/lispref/functions.texi
View file

@ -2204,17 +2204,16 @@ cases, this might be something like @code{(file &optional overwrite)}.
You don't have to specify the argument list, but if you do the
byte compiler can check that the calls match the declaration.
@defmac declare-function function file &rest args
@defmac declare-function function file &optional arglist fileonly
Tell the byte compiler to assume that @var{function} is defined in the
file @var{file}. The trailing arguments @var{args} can contain one or
two optional arguments. The first optional argument @var{arglist} is
either @code{t}, meaning the argument list is unspecified, or a list
of formal parameters in the same style as @code{defun}.@footnote{An
omitted @var{arglist} defaults to @code{t}, not @code{nil}; this
atypical behavior is why @code{declare-function} is defined to have
the formal parameters @code{(function file &rest args)}, not
@code{(function file &optional arglist fileonly)}.} The second
optional argument @var{fileonly} non-@code{nil} means only check that
file @var{file}. The optional third argument @var{arglist} is either
@code{t}, meaning the argument list is unspecified, or a list of
formal parameters in the same style as @code{defun}. An omitted
@var{arglist} defaults to @code{t}, not @code{nil}; this is atypical
behavior for omitted arguments, and it means that to supply a fourth
but not third argument one must specify @code{t} for the third-argument
placeholder instead of the usual @code{nil}. The optional fourth
argument @var{fileonly} non-@code{nil} means check only that
@var{file} exists, not that it actually defines @var{function}.
@end defmac

2
lisp/emacs-lisp/bytecomp.el
View file

@ -2959,6 +2959,8 @@ for symbols generated by the byte compiler itself."
;; Special macro-expander used during byte-compilation.
(defun byte-compile-macroexpand-declare-function (fn file &rest args)
(declare (advertised-calling-convention
(fn file &optional arglist fileonly) nil))
(let ((gotargs (and (consp args) (listp (car args))))
(unresolved (assq fn byte-compile-unresolved-functions)))
(when unresolved ; function was called before declaration

19
lisp/subr.el
View file

@ -33,8 +33,7 @@
"Tell the byte-compiler that function FN is defined, in FILE.
The FILE argument is not used by the byte-compiler, but by the
`check-declare' package, which checks that FILE contains a
definition for FN. Remaining ARGS are used by both the
byte-compiler and `check-declare' to check for consistency.
definition for FN.
FILE can be either a Lisp file (in which case the \".el\"
extension is optional), or a C file. C files are expanded
@ -45,20 +44,22 @@ declaration. A FILE with an \"ext:\" prefix is an external file.
`check-declare' will check such files if they are found, and skip
them without error if they are not.
ARGS can contain one or two optional args. First optional arg
ARGLIST specifies FN's arguments, or is t to not specify FN's
arguments. An omitted ARGLIST defaults to t, not nil: a nil
Optional ARGLIST specifies FN's arguments, or is t to not specify
FN's arguments. An omitted ARGLIST defaults to t, not nil: a nil
ARGLIST specifies an empty argument list, and an explicit t
ARGLIST is a placeholder that allows supplying a later arg.
Second optional arg FILEONLY non-nil means that `check-declare'
will check only that FILE exists, not that it defines FN. This
is intended for function definitions that `check-declare' does
not recognize, e.g., `defstruct'.
Optional FILEONLY non-nil means that `check-declare' will check
only that FILE exists, not that it defines FN. This is intended
for function definitions that `check-declare' does not recognize,
e.g., `defstruct'.
Note that for the purposes of `check-declare', this statement
must be the first non-whitespace on a line.
For more information, see Info node `(elisp)Declaring Functions'."
(declare (advertised-calling-convention
(fn file &optional arglist fileonly) nil))
;; Does nothing - byte-compile-declare-function does the work.
nil)