* Re: master b342815: Improve define-function omitted-arg documentation [not found] ` <20160527164723.4A992220156@vcs.savannah.gnu.org> @ 2016-05-27 16:58 ` Glenn Morris 2016-05-27 17:02 ` Glenn Morris 2016-05-27 19:48 ` Stefan Monnier 1 sibling, 1 reply; 6+ messages in thread From: Glenn Morris @ 2016-05-27 16:58 UTC (permalink / raw) To: emacs-devel; +Cc: Paul Eggert Paul Eggert wrote: > -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. Prejudiced against Fortran, are we? ;) > +@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 IMO all the stuff about t is an internal implementation detail that has no place in the documentation. I will note that AFAICS you only need these doc changes because you've made the macro's arglist less clear, for the sake of one compiler warning that we lived with for years. We previously decided against doing this: http://debbugs.gnu.org/8646 I found the previous doc quite clear, but obviously I'm biased. > +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. Again, t has no place being documented. ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: master b342815: Improve define-function omitted-arg documentation 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 0 siblings, 2 replies; 6+ messages in thread From: Glenn Morris @ 2016-05-27 17:02 UTC (permalink / raw) To: emacs-devel; +Cc: Paul Eggert Glenn Morris wrote: > IMO all the stuff about t is an internal implementation detail that has > no place in the documentation. Ach, blast, I see it was mentioned briefly before. ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: master b342815: Improve define-function omitted-arg documentation 2016-05-27 17:02 ` Glenn Morris @ 2016-05-27 17:52 ` Paul Eggert 2016-05-27 18:51 ` Eli Zaretskii 1 sibling, 0 replies; 6+ messages in thread From: Paul Eggert @ 2016-05-27 17:52 UTC (permalink / raw) To: Glenn Morris, emacs-devel On 05/27/2016 10:02 AM, Glenn Morris wrote: > >> IMO all the stuff about t is an internal implementation detail that has >> no place in the documentation. > Ach, blast, I see it was mentioned briefly before. Yes, and I'm afraid the topic needs to be covered in the documentation. I was confused by the old, terser doc, and Eli was I think right in suggesting that define-function's atypical design be covered more clearly. Alternatively, I suppose we could improve define-function's design.... > Prejudiced against Fortran, are we? Guilty as charged. :-) Though there were other reasons for that part of the change: the old Fortrannish documentation mentioned gud-find-c-expr, a function that is no longer in GNU Emacs. Plus, the old doc had a complicated song-and-dance about hooks, whereas the new simple.el example is, well, simpler. > We previously decided against doing this: http://debbugs.gnu.org/8646 Sorry, I wasn't aware of that old decision. I made the change because of a more-recent statement by the current maintainer that we should strive to eliminate warnings rather than continue to live with the current chatter, which too often leads developers to ignore warnings. See: https://lists.gnu.org/archive/html/bug-gnu-emacs/2015-11/msg00902.html ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: master b342815: Improve define-function omitted-arg documentation 2016-05-27 17:02 ` Glenn Morris 2016-05-27 17:52 ` Paul Eggert @ 2016-05-27 18:51 ` Eli Zaretskii 1 sibling, 0 replies; 6+ messages in thread From: Eli Zaretskii @ 2016-05-27 18:51 UTC (permalink / raw) To: Glenn Morris; +Cc: eggert, emacs-devel > From: Glenn Morris <rgm@gnu.org> > Date: Fri, 27 May 2016 13:02:29 -0400 > Cc: Paul Eggert <eggert@cs.ucla.edu> > > Glenn Morris wrote: > > > IMO all the stuff about t is an internal implementation detail that has > > no place in the documentation. > > Ach, blast, I see it was mentioned briefly before. Not only mentioned, it also needs to be used when you want to specify FILEONLY, but leave the argument least unspecified. So we cannot hide that, I think. I agree that the special meaning of omitting ARGLIST could be described differently, but I find the text that Paul installed clear and definitely adequate, ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: master b342815: Improve define-function omitted-arg documentation [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 19:48 ` Stefan Monnier 2016-05-28 1:19 ` Paul Eggert 1 sibling, 1 reply; 6+ messages in thread From: Stefan Monnier @ 2016-05-27 19:48 UTC (permalink / raw) To: emacs-devel > -@defmac declare-function function file &optional arglist fileonly > +@defmac declare-function function file &rest args 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. Stefan diff --git a/lisp/subr.el b/lisp/subr.el index 239bdc0..52e82e7 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -59,6 +59,8 @@ declare-function 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) ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: master b342815: Improve define-function omitted-arg documentation 2016-05-27 19:48 ` Stefan Monnier @ 2016-05-28 1:19 ` Paul Eggert 0 siblings, 0 replies; 6+ messages in thread From: Paul Eggert @ 2016-05-28 1:19 UTC (permalink / raw) To: Stefan Monnier, emacs-devel [-- 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 ^ permalink raw reply related [flat|nested] 6+ messages in thread
end of thread, other threads:[~2016-05-28 1:19 UTC | newest] Thread overview: 6+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- [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
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).