bug#35433: 27.0.50; 'function' docstring: tell more about advantages?

bug#35433: 27.0.50; 'function' docstring: tell more about advantages?

[Michael Heerdegen]

Hello,

I wonder if we should add to the docstring of `function' that when the
argument is a symbol, several checks are performed: it is checked
whether the function will be defined at run-time and whether the
function is obsolete, for example.

The current docstring doesn't suggest that function-quoting symbols has
any advantages, but these warnings are also useful for users' init
files, people that are not always informed what "argument is byte
compiled" implies.


Thanks,

Michael.




In GNU Emacs 27.0.50 (build 38, x86_64-pc-linux-gnu, GTK+ Version 3.24.5)
 of 2019-04-26 built on drachen
Repository revision: a43eea1bc82acce627d489a32f706572b27e6f7f
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12003000
System Description: Debian GNU/Linux buster/sid

bug#35433: 27.0.50; 'function' docstring: tell more about advantages?

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Date: Fri, 26 Apr 2019 05:40:42 +0200
> 
> I wonder if we should add to the docstring of `function' that when the
> argument is a symbol, several checks are performed: it is checked
> whether the function will be defined at run-time and whether the
> function is obsolete, for example.
> 
> The current docstring doesn't suggest that function-quoting symbols has
> any advantages, but these warnings are also useful for users' init
> files, people that are not always informed what "argument is byte
> compiled" implies.

I think these details belong first and foremost to the ELisp manual.
We could also add a shortened version to the doc string, but I'd like
first to see the full version in the manual.

Thanks.

bug#35433: 27.0.50; 'function' docstring: tell more about advantages?

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> I think these details belong first and foremost to the ELisp manual.
> We could also add a shortened version to the doc string, but I'd like
> first to see the full version in the manual.

Maybe we could just change the wording in the docstring to something
like

  "In byte compilation, `function' causes its argument to be handled by
  the by compiler."

and tell the rest in the manual.  Currently it only says "compiling the
argument" which only covers the lambda-form case, and this is even the
less interesting case, because lambda function-quotes itself nowadays.

Michael.

bug#35433: 27.0.50; 'function' docstring: tell more about advantages?

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: 35433@debbugs.gnu.org
> Date: Sat, 27 Apr 2019 10:30:28 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I think these details belong first and foremost to the ELisp manual.
> > We could also add a shortened version to the doc string, but I'd like
> > first to see the full version in the manual.
> 
> Maybe we could just change the wording in the docstring to something
> like
> 
>   "In byte compilation, `function' causes its argument to be handled by
>   the by compiler."
> 
> and tell the rest in the manual.

Fine with me (but you probably meant "byte compiler", not "by
compiler").

bug#35433: 27.0.50; 'function' docstring: tell more about advantages?

[Michael Heerdegen]

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

Eli Zaretskii <eliz@gnu.org> writes:

> Fine with me (but you probably meant "byte compiler", not "by
> compiler").

Ehm - maybe.

Ok, is this ok and are all conventions respected?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Improve-documentation-of-the-function-special-form.patch --]
[-- Type: text/x-diff, Size: 1696 bytes --]

From 5ac1f0de47720a19225d71e83b906192940a6917 Mon Sep 17 00:00:00 2001
From: Michael Heerdegen <michael_heerdegen@web.de>
Date: Sat, 27 Apr 2019 09:40:10 +0200
Subject: [PATCH] Improve documentation of the 'function' special form

Point out that 'function' quoting is beneficial also for symbols.

* src/eval.c (function): Enhance docstring.
* doc/lispref/functions.texi (Anonymous Functions): Improve
documentation.
---
 doc/lispref/functions.texi | 4 ++++
 src/eval.c                 | 4 ++--
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 97f7fb9f79..09844318d9 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -1122,6 +1122,10 @@ Anonymous Functions
 When lexical binding is enabled, @var{function-object} is converted
 into a closure.  @xref{Closures}.
 @end itemize
+
+When @var{function-object} is a symbol and the code is byte compiled,
+the byte-compiler will warn should that function be undefined or may
+be unknown at run-time.
 @end defspec

 @cindex @samp{#'} syntax
diff --git a/src/eval.c b/src/eval.c
index 567c32e0d7..5bba876637 100644
--- a/src/eval.c
+++ b/src/eval.c
@@ -544,8 +544,8 @@ usage: (quote ARG)  */)

 DEFUN ("function", Ffunction, Sfunction, 1, UNEVALLED, 0,
        doc: /* Like `quote', but preferred for objects which are functions.
-In byte compilation, `function' causes its argument to be compiled.
-`quote' cannot do that.
+In byte compilation, `function' causes its argument to be handled by
+the byte compiler.  `quote' cannot do that.
 usage: (function ARG)  */)
   (Lisp_Object args)
 {
--
2.20.1


[-- Attachment #3: Type: text/plain, Size: 20 bytes --]



Thanks,

Michael.

bug#35433: 27.0.50; 'function' docstring: tell more about advantages?

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: 35433@debbugs.gnu.org
> Date: Thu, 23 May 2019 01:39:49 +0200
> 
> +When @var{function-object} is a symbol and the code is byte compiled,
> +the byte-compiler will warn should that function be undefined or may
> +be unknown at run-time.

I'd say "... will warn if that function is not defined, which means
it might not be known at run time" instead.  "Undefined" and "unknown"
sound vague and more ominous to me.

Otherwise, fine with me, thanks.

bug#35433: 27.0.50; 'function' docstring: tell more about advantages?

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> > From: Michael Heerdegen <michael_heerdegen@web.de>
> > Cc: 35433@debbugs.gnu.org
> > Date: Thu, 23 May 2019 01:39:49 +0200
> >
> > +When @var{function-object} is a symbol and the code is byte compiled,
> > +the byte-compiler will warn should that function be undefined or may
> > +be unknown at run-time.
>
> I'd say "... will warn if that function is not defined, which means
> it might not be known at run time" instead.

No, these are two different cases: (1) function not known when
compiling, and (2) known to the compiler but function may still be
unknown when the compiled code is run, because the compiled file misses
`require' statements, for example.

> "Undefined" and "unknown" sound vague and more ominous to me.

Well, I tried to reuse the words from the actual compiler warnings - see
`byte-compile-warn-about-unresolved-functions'.  I may change "may be
unknown" to "may not be known" - unless you have a better idea:

+When @var{function-object} is a symbol and the code is byte compiled,
+the byte-compiler will warn should that function be undefined or may
+not be known at run-time.


Thanks,

Michael.

bug#35433: 27.0.50; 'function' docstring: tell more about advantages?

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: 35433@debbugs.gnu.org
> Date: Thu, 23 May 2019 18:55:08 +0200
> 
> > I'd say "... will warn if that function is not defined, which means
> > it might not be known at run time" instead.
> 
> No, these are two different cases: (1) function not known when
> compiling, and (2) known to the compiler but function may still be
> unknown when the compiled code is run, because the compiled file misses
> `require' statements, for example.

Then replace "which means it" with "or".

> > "Undefined" and "unknown" sound vague and more ominous to me.
> 
> Well, I tried to reuse the words from the actual compiler warnings - see
> `byte-compile-warn-about-unresolved-functions'.

The warnings there say

    "the function `%s' might not be defined at runtime."
    "the function `%s' is not known to be defined."

They don't say "undefined" and "unknown".

> I may change "may be unknown" to "may not be known" - unless you
> have a better idea:
> 
> +When @var{function-object} is a symbol and the code is byte compiled,
> +the byte-compiler will warn should that function be undefined or may
> +not be known at run-time.

The phrase "should that function be ..." is usually interpreted as
something that may or may happen in the future, which AFAIU is not
what you mean.  That's why I proposed a different wording, which
doesn't have that problem.  Or maybe I'm misunderstanding your intent.

bug#35433: 27.0.50; 'function' docstring: tell more about advantages?

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> Then replace "which means it" with "or".

Ok, I just did that in 84a3da15e9 and close the report - thanks for your
assistance (will probably not be the last time I need help with
wording).

BTW, what I found a bit inconsistent in that manual node was that
sometimes the verb and the noun are sometimes called
"byte-compile"/"byte-compiler" (with hyphen) and sometimes "byte
compile"/"byte compiler" (without).  Dunno if it matters and that should
be more consistent.


Thanks,

Michael.

bug#35433: 27.0.50; 'function' docstring: tell more about advantages?

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: 35433-done@debbugs.gnu.org
> Date: Fri, 24 May 2019 01:18:40 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Then replace "which means it" with "or".
> 
> Ok, I just did that in 84a3da15e9 and close the report

Thanks.

> thanks for your assistance

You are welcome.

> (will probably not be the last time I need help with wording).

Nothing wrong with that.

> BTW, what I found a bit inconsistent in that manual node was that
> sometimes the verb and the noun are sometimes called
> "byte-compile"/"byte-compiler" (with hyphen) and sometimes "byte
> compile"/"byte compiler" (without).  Dunno if it matters and that should
> be more consistent.

I think "byte-compile" should use a hyphen, whereas "byte-compiler"
should not.