From: Paul Eggert Date: Fri, 27 May 2016 16:46:44 +0000 (-0700) Subject: Improve define-function omitted-arg documentation X-Git-Tag: emacs-26.0.90~1880 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=b342815c0a9af8d94d4290d17882de73f6fd9373;p=emacs.git Improve define-function omitted-arg documentation * doc/lispref/functions.texi (Declaring Functions): * lisp/subr.el (declare-function): Be clearer when documenting omitted args for define-function. --- diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index ff21abba61e..7513adfbbef 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -2172,44 +2172,49 @@ Byte-compiling a file often produces warnings about functions that the compiler doesn't know about (@pxref{Compiler Errors}). Sometimes this indicates a real problem, but usually the functions in question are defined in other files which would be loaded if that code is run. For -example, byte-compiling @file{fortran.el} used to warn: +example, byte-compiling @file{simple.el} used to warn: @example -In end of data: -fortran.el:2152:1:Warning: the function ‘gud-find-c-expr’ is not - known to be defined. +simple.el:8727:1:Warning: the function ‘shell-mode’ is not known to be + defined. @end example -In fact, @code{gud-find-c-expr} is only used in the function that -Fortran mode uses for the local value of -@code{gud-find-expr-function}, which is a callback from GUD; if it is -called, the GUD functions will be loaded. When you know that such a -warning does not indicate a real problem, it is good to suppress the -warning. That makes new warnings which might mean real problems more -visible. You do that with @code{declare-function}. +In fact, @code{shell-mode} is used only in a function that executes +@code{(require 'shell)} before calling @code{shell-mode}, so +@code{shell-mode} will be defined properly at run-time. When you know +that such a warning does not indicate a real problem, it is good to +suppress the warning. That makes new warnings which might mean real +problems more visible. You do that with @code{declare-function}. All you need to do is add a @code{declare-function} statement before the first use of the function in question: @example -(declare-function gud-find-c-expr "gud.el" nil) +(declare-function shell-mode "shell" ()) @end example -This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the +This says that @code{shell-mode} is defined in @file{shell.el} (the @samp{.el} can be omitted). The compiler takes for granted that that file really defines the function, and does not check. The optional third argument specifies the argument list of -@code{gud-find-c-expr}. In this case, it takes no arguments +@code{shell-mode}. In this case, it takes no arguments (@code{nil} is different from not specifying a value). In other 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 &optional arglist fileonly -Tell the byte compiler to assume that @var{function} is defined, with -arguments @var{arglist}, and that the definition should come from the -file @var{file}. @var{fileonly} non-@code{nil} means only check that +@defmac declare-function function file &rest args +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 @var{file} exists, not that it actually defines @var{function}. @end defmac diff --git a/lisp/subr.el b/lisp/subr.el index 44d7eaccf02..239bdc08d6b 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -31,7 +31,6 @@ (defmacro declare-function (_fn _file &rest _args) "Tell the byte-compiler that function FN is defined, in FILE. -Optional ARGLIST is the argument list used by the function. 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 @@ -47,15 +46,14 @@ declaration. A FILE with an \"ext:\" prefix is an external file. them without error if they are not. ARGS can contain one or two optional args. First optional arg -ARGLIST specifies the function arguments. Second optional arg -FILEONLY non-nil means that `check-declare' will only check that -FILE exists, not that it defines FN. This is intended for -function-definitions that `check-declare' does not recognize, e.g. -`defstruct'. - -To specify a value for FILEONLY without passing an argument list, -set ARGLIST to t. This is necessary because nil means an -empty argument list, rather than an unspecified one. +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'. Note that for the purposes of `check-declare', this statement must be the first non-whitespace on a line.