[Emacs-diffs] master b342815: Improve define-function omitted-arg documentation

[Paul Eggert]

branch: master
commit b342815c0a9af8d94d4290d17882de73f6fd9373
Author: Paul Eggert <address@hidden>
Commit: Paul Eggert <address@hidden>

    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.
---
 doc/lispref/functions.texi |   41 +++++++++++++++++++++++------------------
 lisp/subr.el               |   18 ++++++++----------
 2 files changed, 31 insertions(+), 28 deletions(-)

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index ff21abb..7513adf 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
address@hidden, 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
address@hidden(require 'shell)} before calling @code{shell-mode}, so
address@hidden 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
address@hidden  In this case, it takes no arguments
address@hidden  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.
 
address@hidden 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} address@hidden means only check that
address@hidden 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 @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
 @var{file} exists, not that it actually defines @var{function}.
 @end defmac
 
diff --git a/lisp/subr.el b/lisp/subr.el
index 44d7eac..239bdc0 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.