bug#29367: 27.0.50; State and doc of `inline'

bug#29367: 27.0.50; State and doc of `inline'

[Michael Heerdegen]

C-h f inline gives you

| inline is an alias for `progn'.
| 
| (inline BODY...)
| 
| Eval BODY forms sequentially and return value of last one.

`inline' is quite widely used in the Emacs sources - in Gnus, for
example.  But obviously not because it is such a handy alias for
`progn'.  The byte compiler treats it very specially.

I think it is obvious that `inline' needs a real documentation, and
should not be defined as an alias, because this is very confusing.

If `inline' should not be used in new code because it is obsoleted by
better alternatives (inline.el, maybe?  I don't know), we can declare it
obsolete.  Still, as long as it is used in Emacs a lot, and developers
need to work with this code base, they need to know what `inline' is.


TIA,

Michael.


In GNU Emacs 27.0.50 (build 5, x86_64-pc-linux-gnu, GTK+ Version 3.22.24)
 of 2017-11-18 built on drachen
Repository revision: 4da48312a230909a12d63987f865f25d45760773
Windowing system distributor 'The X.Org Foundation', version 11.0.11905000
System Description:	Debian GNU/Linux testing (buster)

bug#29367: 27.0.50; State and doc of `inline'

[Glenn Morris]

Michael Heerdegen wrote:

> `inline' is quite widely used in the Emacs sources - in Gnus, for
> example.

I see a small number (~ 30) of (20-year old) uses in a few Gnus files,
and ~ 0 elsewhere.

bug#29367: 27.0.50; State and doc of `inline'

[Eric Abrahamsen]

Glenn Morris <rgm@gnu.org> writes:

> Michael Heerdegen wrote:
>
>> `inline' is quite widely used in the Emacs sources - in Gnus, for
>> example.
>
> I see a small number (~ 30) of (20-year old) uses in a few Gnus files,
> and ~ 0 elsewhere.

If that's the case, it would probably be fine to drop `inline'
altogether, and use `define-inline' for the Gnus functions where it
would help.

bug#29367: 27.0.50; State and doc of `inline'

[Michael Heerdegen]

Glenn Morris <rgm@gnu.org> writes:

> > `inline' is quite widely used in the Emacs sources - in Gnus, for
> > example.
>
> I see a small number (~ 30) of (20-year old) uses in a few Gnus files,
> and ~ 0 elsewhere.

If `inline' had a documentation, maybe there would have been more uses
in the last 20 years?

I see ~57 uses in the Elisp sources.  That's quite a lot for an
undocumented macro.  If all functions that appear < 100 times in the
code base would be undocumented, oh my god.

For every function in Emacs, it should be possible to find out what it
is doing in a reasonable amount of time, because we all want to have
readable code.


Michael.

bug#29367: 27.0.50; State and doc of `inline'

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

What is the purpose of 'inline'?
'inline' appears to be an alias for 'progn'.
Does it have some magic difference?

-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)
Skype: No way! See https://stallman.org/skype.html.

bug#29367: 27.0.50; State and doc of `inline'

[Drew Adams]

> What is the purpose of 'inline'?
> 'inline' appears to be an alias for 'progn'.
> Does it have some magic difference?

From the discussion in help-gnu-emacs it seems
it might have some magic indifference. ;-)

bug#29367: 27.0.50; State and doc of `inline'

[Andreas Schwab]

On Nov 21 2017, Richard Stallman <rms@gnu.org> wrote:

> What is the purpose of 'inline'?
> 'inline' appears to be an alias for 'progn'.
> Does it have some magic difference?

It has a byte-optimizer property.

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

bug#29367: 27.0.50; State and doc of `inline'

[Michael Heerdegen]

Richard Stallman <rms@gnu.org> writes:

> What is the purpose of 'inline'?
> 'inline' appears to be an alias for 'progn'.
> Does it have some magic difference?

The purpose seems to be to let the byte compiler inline function calls
for efficiency reasons.


Michael.

bug#29367: 27.0.50; State and doc of `inline'

[Glenn Morris]

Version: 26.1

Doc added in 8d450453fa.

bug#29367: 27.0.50; State and doc of `inline'

[Drew Adams]

> > What is the purpose of 'inline'?
> > 'inline' appears to be an alias for 'progn'.
> > Does it have some magic difference?
> 
> The purpose seems to be to let the byte compiler inline
> function calls for efficiency reasons.

In that case, it would seem to correspond to what, in
Common Lisp, would be a declaration (`declare').

In Common Lisp, declarations are supposed to be
documented, even when implementation-specific.  They
are something a user provides, so users need to know
about them.

bug#29367: 27.0.50; State and doc of `inline'

[Michael Heerdegen]

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

Drew Adams <drew.adams@oracle.com> writes:

> In that case, it would seem to correspond to what, in
> Common Lisp, would be a declaration (`declare').
>
> In Common Lisp, declarations are supposed to be documented, even when
> implementation-specific.  They are something a user provides, so users
> need to know about them.

Glenn has already fixed it like this:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-emacs-lisp-byte-run.el-inline-Give-it-a-doc.patch --]
[-- Type: text/x-diff, Size: 935 bytes --]

From 8d450453fae4518f79f7f951d8c70e11f887a934 Mon Sep 17 00:00:00 2001
From: Glenn Morris <rgm@gnu.org>
Date: Tue, 21 Nov 2017 08:53:31 -0800
Subject: [PATCH] * lisp/emacs-lisp/byte-run.el (inline): Give it a doc.

---
 lisp/emacs-lisp/byte-run.el | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/lisp/emacs-lisp/byte-run.el b/lisp/emacs-lisp/byte-run.el
index abfcdb347a..e4f21c9d6d 100644
--- a/lisp/emacs-lisp/byte-run.el
+++ b/lisp/emacs-lisp/byte-run.el
@@ -286,8 +286,12 @@ defun
 
 \f
 ;; Redefined in byte-opt.el.
-;; This is not documented--it's not clear that we should promote it.
-(fset 'inline 'progn)
+;; This was undocumented and unused for decades.
+(defalias 'inline 'progn
+  "Like `progn', but when compiled inline top-level function calls in body.
+You don't need this.  (See bytecomp.el commentary for more details.)
+
+\(fn BODY...)")
 
 ;;; Interface to inline functions.
 
-- 
2.15.0


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


Given that it apparently should not be used in new code, I'm ok with it.


Michael.

bug#29367: 27.0.50; State and doc of `inline'

[Andreas Schwab]

On Nov 21 2017, Drew Adams <drew.adams@oracle.com> wrote:

> In that case, it would seem to correspond to what, in
> Common Lisp, would be a declaration (`declare').

It's not a function property, but something you add to the call site.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."