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

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

[Glenn Morris]

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.

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

[Glenn Morris]

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.

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

[Paul Eggert]

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

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

[Eli Zaretskii]

> 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,

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

[Stefan Monnier]

> -@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)
 

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

[Paul Eggert]

[-- 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