Re: master b342815: Improve define-function omitted-arg documentation

[Paul Eggert <eggert@cs.ucla.edu>]

[-- Attachment #1: Type: text/plain, Size: 306 bytes --]

Stefan Monnier wrote:
> I'm OK with using &rest in the implementation, but it's probably best
> not to document this implementation choice in the manual.
>
> Similarly we should probably do something like the patch below.

Nice, I didn't know about advertised-calling-convention. I installed the attached.

[-- Attachment #2: 0001-Don-t-document-declare-function-internals.txt --]
[-- Type: text/plain, Size: 5282 bytes --]

From 5d3c6ca0fdb9402f9bdb0ea10a8c8585024de1f2 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
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.
 
-@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
 
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