bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'

bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'

[Drew Adams]

.. 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@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'

[Dmitry Gutov]

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.

bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'

[Drew Adams]

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

bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'

[Stefan Monnier]

> Maybe it should just be undocumented. It's a private function, and it
> duplicates the docstring of its only caller.

Agreed,


        Stefan

bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'

[Nicolas Richard]

Dmitry Gutov <dgutov@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

bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'

[Dmitry Gutov]

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?

bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'

[Nicolas Richard]

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

Dmitry Gutov <dgutov@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.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-progmodes-elisp-mode.el-elisp-eval-last-sexp-Do.patch --]
[-- Type: text/x-diff, Size: 1679 bytes --]

From 31d11bc29fd5157f2ff0f41e6d5d39b1115fcf8f Mon Sep 17 00:00:00 2001
From: Nicolas Richard <theonewiththeevillook@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@yahoo.fr>
+
+	* progmodes/elisp-mode.el (elisp--eval-last-sexp): Document argument.
+
 2014-12-23  Nicolas Richard  <theonewiththeevillook@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


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


-- 
Nicolas Richard

bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'

[Dmitry Gutov]

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.

bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'

[Nicolas Richard]

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.

bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'

[Drew Adams]

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

bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'

[Drew Adams]

> >> .. 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++. ;-)

bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'

[Dmitry Gutov]

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.

bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'

[Drew Adams]

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

bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'

[Nicolas Richard]

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.

bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'

[Drew Adams]

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