From 5d3c6ca0fdb9402f9bdb0ea10a8c8585024de1f2 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Fri, 27 May 2016 18:16:24 -0700 Subject: [PATCH] =?UTF-8?q?Don=E2=80=99t=20document=20declare-function=20i?= =?UTF-8?q?nternals?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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). --- doc/lispref/functions.texi | 19 +++++++++---------- lisp/emacs-lisp/bytecomp.el | 2 ++ lisp/subr.el | 19 ++++++++++--------- 3 files changed, 21 insertions(+), 19 deletions(-) diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 7513adf..fff4ac0 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -2204,17 +2204,16 @@ Declaring Functions You don't have to specify the argument list, but if you do the byte compiler can check that the calls match the declaration. address@hidden declare-function function file &rest args address@hidden 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 @address@hidden -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 address@hidden(function file &optional arglist fileonly)}.} The second -optional argument @var{fileonly} address@hidden means only check that +file @var{file}. The optional third argument @var{arglist} is either address@hidden, meaning the argument list is unspecified, or a list of +formal parameters in the same style as @code{defun}. An omitted address@hidden 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} address@hidden means check only that @var{file} exists, not that it actually defines @var{function}. @end defmac diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el index 11eb44c..dc7574e 100644 --- a/lisp/emacs-lisp/bytecomp.el +++ b/lisp/emacs-lisp/bytecomp.el @@ -2959,6 +2959,8 @@ byte-compile-top-level-body ;; 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 diff --git a/lisp/subr.el b/lisp/subr.el index 97cde68..6e679e7 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -33,8 +33,7 @@ declare-function "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 @@ declare-function `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) -- 2.5.5