From: Paul Eggert <eggert@cs.ucla.edu>
To: Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org
Subject: Re: master b342815: Improve define-function omitted-arg documentation
Date: Fri, 27 May 2016 18:19:15 -0700 [thread overview]
Message-ID: <5748F213.3040707@cs.ucla.edu> (raw)
In-Reply-To: <jwva8jbthld.fsf-monnier+gmane.emacs.devel@gnu.org>
[-- 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
prev parent reply other threads:[~2016-05-28 1:19 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <20160527164722.20278.19217@vcs.savannah.gnu.org>
[not found] ` <20160527164723.4A992220156@vcs.savannah.gnu.org>
2016-05-27 16:58 ` master b342815: Improve define-function omitted-arg documentation Glenn Morris
2016-05-27 17:02 ` Glenn Morris
2016-05-27 17:52 ` Paul Eggert
2016-05-27 18:51 ` Eli Zaretskii
2016-05-27 19:48 ` Stefan Monnier
2016-05-28 1:19 ` Paul Eggert [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=5748F213.3040707@cs.ucla.edu \
--to=eggert@cs.ucla.edu \
--cc=emacs-devel@gnu.org \
--cc=monnier@iro.umontreal.ca \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).