unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'
@ 2015-02-23 21:20 Drew Adams
  2015-02-24 21:01 ` Dmitry Gutov
  0 siblings, 1 reply; 15+ messages in thread
From: Drew Adams @ 2015-02-23 21:20 UTC (permalink / raw)
  To: 19932

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





^ permalink raw reply	[flat|nested] 15+ messages in thread

* bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'
  2015-02-23 21:20 bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp' Drew Adams
@ 2015-02-24 21:01 ` Dmitry Gutov
  2015-02-24 21:26   ` Drew Adams
                     ` (2 more replies)
  0 siblings, 3 replies; 15+ messages in thread
From: Dmitry Gutov @ 2015-02-24 21:01 UTC (permalink / raw)
  To: Drew Adams, 19932

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.





^ permalink raw reply	[flat|nested] 15+ messages in thread

* bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'
  2015-02-24 21:01 ` Dmitry Gutov
@ 2015-02-24 21:26   ` Drew Adams
  2015-02-25  4:06   ` Stefan Monnier
  2015-02-25 10:52   ` Nicolas Richard
  2 siblings, 0 replies; 15+ messages in thread
From: Drew Adams @ 2015-02-24 21:26 UTC (permalink / raw)
  To: Dmitry Gutov, 19932

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





^ permalink raw reply	[flat|nested] 15+ messages in thread

* bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'
  2015-02-24 21:01 ` Dmitry Gutov
  2015-02-24 21:26   ` Drew Adams
@ 2015-02-25  4:06   ` Stefan Monnier
  2015-02-25 10:52   ` Nicolas Richard
  2 siblings, 0 replies; 15+ messages in thread
From: Stefan Monnier @ 2015-02-25  4:06 UTC (permalink / raw)
  To: Dmitry Gutov; +Cc: 19932

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

Agreed,


        Stefan





^ permalink raw reply	[flat|nested] 15+ messages in thread

* bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'
  2015-02-24 21:01 ` Dmitry Gutov
  2015-02-24 21:26   ` Drew Adams
  2015-02-25  4:06   ` Stefan Monnier
@ 2015-02-25 10:52   ` Nicolas Richard
  2015-02-25 11:17     ` Dmitry Gutov
  2015-02-25 16:36     ` Drew Adams
  2 siblings, 2 replies; 15+ messages in thread
From: Nicolas Richard @ 2015-02-25 10:52 UTC (permalink / raw)
  To: Dmitry Gutov; +Cc: 19932

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





^ permalink raw reply	[flat|nested] 15+ messages in thread

* bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'
  2015-02-25 10:52   ` Nicolas Richard
@ 2015-02-25 11:17     ` Dmitry Gutov
  2015-02-25 12:12       ` Nicolas Richard
  2015-02-25 16:36     ` Drew Adams
  1 sibling, 1 reply; 15+ messages in thread
From: Dmitry Gutov @ 2015-02-25 11:17 UTC (permalink / raw)
  To: Nicolas Richard; +Cc: 19932

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?





^ permalink raw reply	[flat|nested] 15+ messages in thread

* bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'
  2015-02-25 11:17     ` Dmitry Gutov
@ 2015-02-25 12:12       ` Nicolas Richard
  2015-02-25 12:44         ` Dmitry Gutov
  2015-02-25 16:39         ` Drew Adams
  0 siblings, 2 replies; 15+ messages in thread
From: Nicolas Richard @ 2015-02-25 12:12 UTC (permalink / raw)
  To: Dmitry Gutov; +Cc: Nicolas Richard, 19932

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

^ permalink raw reply related	[flat|nested] 15+ messages in thread

* bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'
  2015-02-25 12:12       ` Nicolas Richard
@ 2015-02-25 12:44         ` Dmitry Gutov
  2015-02-25 15:18           ` Nicolas Richard
  2015-02-25 16:39         ` Drew Adams
  1 sibling, 1 reply; 15+ messages in thread
From: Dmitry Gutov @ 2015-02-25 12:44 UTC (permalink / raw)
  To: Nicolas Richard; +Cc: 19932

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.





^ permalink raw reply	[flat|nested] 15+ messages in thread

* bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'
  2015-02-25 12:44         ` Dmitry Gutov
@ 2015-02-25 15:18           ` Nicolas Richard
  0 siblings, 0 replies; 15+ messages in thread
From: Nicolas Richard @ 2015-02-25 15:18 UTC (permalink / raw)
  To: Dmitry Gutov; +Cc: 19932-done

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.







^ permalink raw reply	[flat|nested] 15+ messages in thread

* bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'
  2015-02-25 10:52   ` Nicolas Richard
  2015-02-25 11:17     ` Dmitry Gutov
@ 2015-02-25 16:36     ` Drew Adams
  2015-02-25 16:39       ` Dmitry Gutov
  2015-02-25 16:49       ` Nicolas Richard
  1 sibling, 2 replies; 15+ messages in thread
From: Drew Adams @ 2015-02-25 16:36 UTC (permalink / raw)
  To: Nicolas Richard, Dmitry Gutov; +Cc: 19932

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





^ permalink raw reply	[flat|nested] 15+ messages in thread

* bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'
  2015-02-25 16:36     ` Drew Adams
@ 2015-02-25 16:39       ` Dmitry Gutov
  2015-02-25 16:45         ` Drew Adams
  2015-02-25 16:49       ` Nicolas Richard
  1 sibling, 1 reply; 15+ messages in thread
From: Dmitry Gutov @ 2015-02-25 16:39 UTC (permalink / raw)
  To: Drew Adams, Nicolas Richard; +Cc: 19932

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.





^ permalink raw reply	[flat|nested] 15+ messages in thread

* bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'
  2015-02-25 12:12       ` Nicolas Richard
  2015-02-25 12:44         ` Dmitry Gutov
@ 2015-02-25 16:39         ` Drew Adams
  1 sibling, 0 replies; 15+ messages in thread
From: Drew Adams @ 2015-02-25 16:39 UTC (permalink / raw)
  To: Nicolas Richard, Dmitry Gutov; +Cc: 19932

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





^ permalink raw reply	[flat|nested] 15+ messages in thread

* bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'
  2015-02-25 16:39       ` Dmitry Gutov
@ 2015-02-25 16:45         ` Drew Adams
  0 siblings, 0 replies; 15+ messages in thread
From: Drew Adams @ 2015-02-25 16:45 UTC (permalink / raw)
  To: Dmitry Gutov, Nicolas Richard; +Cc: 19932

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






^ permalink raw reply	[flat|nested] 15+ messages in thread

* bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'
  2015-02-25 16:36     ` Drew Adams
  2015-02-25 16:39       ` Dmitry Gutov
@ 2015-02-25 16:49       ` Nicolas Richard
  2015-02-25 17:05         ` Drew Adams
  1 sibling, 1 reply; 15+ messages in thread
From: Nicolas Richard @ 2015-02-25 16:49 UTC (permalink / raw)
  To: Drew Adams; +Cc: 19932

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.





^ permalink raw reply	[flat|nested] 15+ messages in thread

* bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp'
  2015-02-25 16:49       ` Nicolas Richard
@ 2015-02-25 17:05         ` Drew Adams
  0 siblings, 0 replies; 15+ messages in thread
From: Drew Adams @ 2015-02-25 17:05 UTC (permalink / raw)
  To: Nicolas Richard; +Cc: 19932

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





^ permalink raw reply	[flat|nested] 15+ messages in thread

end of thread, other threads:[~2015-02-25 17:05 UTC | newest]

Thread overview: 15+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2015-02-23 21:20 bug#19932: 25.0.50; doc string of `elisp--eval-last-sexp' Drew Adams
2015-02-24 21:01 ` Dmitry Gutov
2015-02-24 21:26   ` Drew Adams
2015-02-25  4:06   ` Stefan Monnier
2015-02-25 10:52   ` Nicolas Richard
2015-02-25 11:17     ` Dmitry Gutov
2015-02-25 12:12       ` Nicolas Richard
2015-02-25 12:44         ` Dmitry Gutov
2015-02-25 15:18           ` Nicolas Richard
2015-02-25 16:39         ` Drew Adams
2015-02-25 16:36     ` Drew Adams
2015-02-25 16:39       ` Dmitry Gutov
2015-02-25 16:45         ` Drew Adams
2015-02-25 16:49       ` Nicolas Richard
2015-02-25 17:05         ` Drew Adams

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).