GNU bug report logs -
#19932
25.0.50; doc string of `elisp--eval-last-sexp'
Previous Next
Reported by: Drew Adams <drew.adams <at> oracle.com>
Date: Mon, 23 Feb 2015 21:21:02 UTC
Severity: minor
Found in version 25.0.50
Done: Nicolas Richard <theonewiththeevillook <at> yahoo.fr>
Bug is archived. No further changes may be made.
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 19932 in the body.
You can then email your comments to 19932 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#19932; Package
emacs.
(Mon, 23 Feb 2015 21:21:02 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
Drew Adams <drew.adams <at> oracle.com>:
New bug report received and forwarded. Copy sent to
bug-gnu-emacs <at> gnu.org.
(Mon, 23 Feb 2015 21:21:02 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
.. should not mention the prefix arg. This is not a command, and the
function code does not access `current-prefix-arg'.
The doc string should say that if `prefix-numeric-value' applied to the
argument to the function is 0 then...
In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
of 2014-10-20 on LEG570
Bzr revision: 118168 rgm <at> gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
`configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#19932; Package
emacs.
(Tue, 24 Feb 2015 21:03:02 GMT)
Full text and
rfc822 format available.
Message #8 received at 19932 <at> debbugs.gnu.org (full text, mbox):
On 02/23/2015 11:20 PM, Drew Adams wrote:
> .. should not mention the prefix arg. This is not a command, and the
> function code does not access `current-prefix-arg'.
Maybe it should just be undocumented. It's a private function, and it
duplicates the docstring of its only caller.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#19932; Package
emacs.
(Tue, 24 Feb 2015 21:27:02 GMT)
Full text and
rfc822 format available.
Message #11 received at 19932 <at> debbugs.gnu.org (full text, mbox):
> > .. should not mention the prefix arg. This is not a command, and the
> > function code does not access `current-prefix-arg'.
>
> Maybe it should just be undocumented. It's a private function, and it
> duplicates the docstring of its only caller.
Maybe it should be documented properly. Emacs is the self-documenting
editor. Maybe developers should drop the bad habit of thinking of
documentation as only a chore and as only for others.
There is nothing "private" in Emacs Lisp - this is not Java or C++.
And even Emacs "internal" developers deserve to take advantage of
the self-documentation Emacs is intended to provide.
The duplication of its caller's docstring is the bug - it should
have its own documentation.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#19932; Package
emacs.
(Wed, 25 Feb 2015 04:07:02 GMT)
Full text and
rfc822 format available.
Message #14 received at 19932 <at> debbugs.gnu.org (full text, mbox):
> Maybe it should just be undocumented. It's a private function, and it
> duplicates the docstring of its only caller.
Agreed,
Stefan
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#19932; Package
emacs.
(Wed, 25 Feb 2015 10:53:02 GMT)
Full text and
rfc822 format available.
Message #17 received at 19932 <at> debbugs.gnu.org (full text, mbox):
Dmitry Gutov <dgutov <at> yandex.ru> writes:
> On 02/23/2015 11:20 PM, Drew Adams wrote:
>> .. should not mention the prefix arg. This is not a command, and the
>> function code does not access `current-prefix-arg'.
>
> Maybe it should just be undocumented. It's a private function, and it
> duplicates the docstring of its only caller.
FWIW, I like when functions are documented, even private ones.
--
Nicolas Richard
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#19932; Package
emacs.
(Wed, 25 Feb 2015 11:18:01 GMT)
Full text and
rfc822 format available.
Message #20 received at 19932 <at> debbugs.gnu.org (full text, mbox):
On 02/25/2015 12:52 PM, Nicolas Richard wrote:
> FWIW, I like when functions are documented, even private ones.
Would you like to enforce your preference and provide a patch that
improves on the discussed drawbacks in that docstring?
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#19932; Package
emacs.
(Wed, 25 Feb 2015 12:12:02 GMT)
Full text and
rfc822 format available.
Message #23 received at 19932 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
Dmitry Gutov <dgutov <at> yandex.ru> writes:
> On 02/25/2015 12:52 PM, Nicolas Richard wrote:
>
>> FWIW, I like when functions are documented, even private ones.
>
> Would you like to enforce your preference and provide a patch that
> improves on the discussed drawbacks in that docstring?
Would the following fit ? (I should be able to push it, if it turns out
to be ok.)
It's not as precise as what Drew suggested, but I didn't feel like being
too verbose.
[0001-lisp-progmodes-elisp-mode.el-elisp-eval-last-sexp-Do.patch (text/x-diff, inline)]
From 31d11bc29fd5157f2ff0f41e6d5d39b1115fcf8f Mon Sep 17 00:00:00 2001
From: Nicolas Richard <theonewiththeevillook <at> yahoo.fr>
Date: Wed, 25 Feb 2015 13:07:43 +0100
Subject: [PATCH] lisp/progmodes/elisp-mode.el (elisp--eval-last-sexp):
Document argument.
Fixes: 19932
---
lisp/ChangeLog | 4 ++++
lisp/progmodes/elisp-mode.el | 4 ++--
2 files changed, 6 insertions(+), 2 deletions(-)
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index e32dab0..f4f6097 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2015-02-25 Nicolas Richard <theonewiththeevillook <at> yahoo.fr>
+
+ * progmodes/elisp-mode.el (elisp--eval-last-sexp): Document argument.
+
2014-12-23 Nicolas Richard <theonewiththeevillook <at> yahoo.fr>
* simple.el (count-words-region): Act on buffer if there is no region.
diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el
index b2c5fbf..42e946c 100644
--- a/lisp/progmodes/elisp-mode.el
+++ b/lisp/progmodes/elisp-mode.el
@@ -883,8 +883,8 @@ (define-obsolete-function-alias 'preceding-sexp 'elisp--preceding-sexp "25.1")
(defun elisp--eval-last-sexp (eval-last-sexp-arg-internal)
"Evaluate sexp before point; print value in the echo area.
-With argument, print output into current buffer.
-With a zero prefix arg, print output with no limit on the length
+If EVAL-LAST-SEXP-ARG-INTERNAL is non-nil, print output into current buffer.
+If EVAL-LAST-SEXP-ARG-INTERNAL is `0', print output with no limit on the length
and level of lists, and include additional formats for integers
\(octal, hexadecimal, and character)."
(let ((standard-output (if eval-last-sexp-arg-internal (current-buffer) t)))
--
2.1.4
[Message part 3 (text/plain, inline)]
--
Nicolas Richard
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#19932; Package
emacs.
(Wed, 25 Feb 2015 12:45:02 GMT)
Full text and
rfc822 format available.
Message #26 received at 19932 <at> debbugs.gnu.org (full text, mbox):
On 02/25/2015 02:12 PM, Nicolas Richard wrote:
> Would the following fit ? (I should be able to push it, if it turns out
> to be ok.)
Looks fine to me. You might want to reflow it a bit, to adhere to
emacs-lisp-docstring-fill-column.
Reply sent
to
Nicolas Richard <theonewiththeevillook <at> yahoo.fr>:
You have taken responsibility.
(Wed, 25 Feb 2015 15:19:02 GMT)
Full text and
rfc822 format available.
Notification sent
to
Drew Adams <drew.adams <at> oracle.com>:
bug acknowledged by developer.
(Wed, 25 Feb 2015 15:19:03 GMT)
Full text and
rfc822 format available.
Message #31 received at 19932-done <at> debbugs.gnu.org (full text, mbox):
Le 25/02/2015 13:44, Dmitry Gutov a écrit :
> On 02/25/2015 02:12 PM, Nicolas Richard wrote:
>
>> Would the following fit ? (I should be able to push it, if it turns out
>> to be ok.)
>
> Looks fine to me. You might want to reflow it a bit, to adhere to emacs-lisp-docstring-fill-column.
Ok, done.
Nico.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#19932; Package
emacs.
(Wed, 25 Feb 2015 16:37:01 GMT)
Full text and
rfc822 format available.
Message #34 received at 19932 <at> debbugs.gnu.org (full text, mbox):
> >> .. should not mention the prefix arg. This is not a command, and the
> >> function code does not access `current-prefix-arg'.
> >
> > Maybe it should just be undocumented. It's a private function, and it
> > duplicates the docstring of its only caller.
>
> FWIW, I like when functions are documented, even private ones.
Of course. And "private" means nothing in the context of Emacs Lisp.
But perhaps some have dreams of turning it into C++. ;-)
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#19932; Package
emacs.
(Wed, 25 Feb 2015 16:40:02 GMT)
Full text and
rfc822 format available.
Message #37 received at 19932 <at> debbugs.gnu.org (full text, mbox):
On 02/25/2015 06:36 PM, Drew Adams wrote:
> And "private" means nothing in the context of Emacs Lisp.
It means plenty, even if you choose to ignore it. For instance,
third-party code mustn't call private functions, thus it's considerably
less important to document them.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#19932; Package
emacs.
(Wed, 25 Feb 2015 16:41:01 GMT)
Full text and
rfc822 format available.
Message #40 received at 19932 <at> debbugs.gnu.org (full text, mbox):
> >> FWIW, I like when functions are documented, even private ones.
> >
> > Would you like to enforce your preference and provide a patch that
> > improves on the discussed drawbacks in that docstring?
>
> Would the following fit ? (I should be able to push it, if it turns out
> to be ok.)
>
> It's not as precise as what Drew suggested, but I didn't feel like being
> too verbose.
Looks good. Thanks.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#19932; Package
emacs.
(Wed, 25 Feb 2015 16:46:02 GMT)
Full text and
rfc822 format available.
Message #43 received at 19932 <at> debbugs.gnu.org (full text, mbox):
> > And "private" means nothing in the context of Emacs Lisp.
>
> It means plenty, even if you choose to ignore it. For instance,
> third-party code mustn't call private functions, thus it's considerably
> less important to document them.
There is nothing in Emacs Lisp that 3rd-party code "mustn't call".
There may be things that code should not call, without inflicting
pain somewhere. But that is exactly true and just much true of
"core" (aka delivered-with-Emacs) Lisp code as it is true of
3rd-party Lisp code.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#19932; Package
emacs.
(Wed, 25 Feb 2015 16:49:02 GMT)
Full text and
rfc822 format available.
Message #46 received at 19932 <at> debbugs.gnu.org (full text, mbox):
Le 25/02/2015 17:36, Drew Adams a écrit :
> Of course. And "private" means nothing in the context of Emacs Lisp.
It means whatever we want it to mean when we use the word. I think we
all (more or less) understand what it means in the current context, don't we ?
Nico.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#19932; Package
emacs.
(Wed, 25 Feb 2015 17:06:02 GMT)
Full text and
rfc822 format available.
Message #49 received at 19932 <at> debbugs.gnu.org (full text, mbox):
> > Of course. And "private" means nothing in the context of Emacs Lisp.
>
> It means whatever we want it to mean when we use the word. I think we
> all (more or less) understand what it means in the current context,
> don't we ?
Nope. You won't find it anywhere in the Emacs or Elisp doc, I'll bet.
Or even in the source code (unless perhaps in some C code somewhere,
as a comment).
Use of the term here, by Dmitry, is new in the context of Emacs, AFAIK.
I'll bet that even if you search bug reports and emacs-devel threads you
won't find that term used.
(And "internal" (also nebulous/dubious in the context of Emacs) is not
the same as "private".)
"Private", for software, is typically about encapsulation/visibility
and modules. You could make a case that a notion of such privacy
(importing, exporting etc.) exists in Common Lisp, wrt its packages.
But no such module system exists for Elisp.
If/when we add a module system to Elisp, then we can perhaps speak of
things being "private". And even then the notion would no doubt be
relative, as it is in, say, Common Lisp.
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org.
(Thu, 26 Mar 2015 11:24:03 GMT)
Full text and
rfc822 format available.
This bug report was last modified 10 years and 180 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.