unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#19116: 25.0.50; doc string of `eval-expression'
@ 2014-11-20  3:06 Drew Adams
  2016-04-30 15:19 ` Lars Ingebrigtsen
  0 siblings, 1 reply; 7+ messages in thread
From: Drew Adams @ 2014-11-20  3:06 UTC (permalink / raw)
  To: 19116

The doc string says only what this function does "When called
interactively".  It says nothing about what it does when called from
Lisp.  Please complete the description of the function, to take care of
this.


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] 7+ messages in thread

* bug#19116: 25.0.50; doc string of `eval-expression'
  2014-11-20  3:06 bug#19116: 25.0.50; doc string of `eval-expression' Drew Adams
@ 2016-04-30 15:19 ` Lars Ingebrigtsen
  2016-04-30 17:04   ` Drew Adams
                     ` (2 more replies)
  0 siblings, 3 replies; 7+ messages in thread
From: Lars Ingebrigtsen @ 2016-04-30 15:19 UTC (permalink / raw)
  To: Drew Adams; +Cc: 19116

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

> The doc string says only what this function does "When called
> interactively".  It says nothing about what it does when called from
> Lisp.  Please complete the description of the function, to take care of
> this.

This is how the doc starts:

Evaluate EXP and print value in the echo area.
When called interactively, read an Emacs Lisp expression and evaluate it.

So I see no need to change anything here.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no





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

* bug#19116: 25.0.50; doc string of `eval-expression'
  2016-04-30 15:19 ` Lars Ingebrigtsen
@ 2016-04-30 17:04   ` Drew Adams
  2016-04-30 17:22     ` Eli Zaretskii
       [not found]   ` <<b30dc17d-8538-4aef-aa01-11b68cb8f845@default>
       [not found]   ` <<<b30dc17d-8538-4aef-aa01-11b68cb8f845@default>
  2 siblings, 1 reply; 7+ messages in thread
From: Drew Adams @ 2016-04-30 17:04 UTC (permalink / raw)
  To: Lars Ingebrigtsen; +Cc: 19116

> > The doc string says only what this function does "When called
> > interactively".  It says nothing about what it does when called from
> > Lisp.  Please complete the description of the function, to take care of
> > this.
> 
> This is how the doc starts:
> 
> Evaluate EXP and print value in the echo area.
> When called interactively, read an Emacs Lisp expression and evaluate it.
> 
> So I see no need to change anything here.

Doc for commands should present the behavior first in terms
of interactive use - as a command, for all users.

Only after that should it describe use of the command from
Lisp code.

The first line of the doc string should not be the first line
of the doc string.





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

* bug#19116: 25.0.50; doc string of `eval-expression'
  2016-04-30 17:04   ` Drew Adams
@ 2016-04-30 17:22     ` Eli Zaretskii
  0 siblings, 0 replies; 7+ messages in thread
From: Eli Zaretskii @ 2016-04-30 17:22 UTC (permalink / raw)
  To: Drew Adams; +Cc: larsi, 19116

> Date: Sat, 30 Apr 2016 09:04:12 -0800 (GMT-08:00)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 19116@debbugs.gnu.org
> 
> > > The doc string says only what this function does "When called
> > > interactively".  It says nothing about what it does when called from
> > > Lisp.  Please complete the description of the function, to take care of
> > > this.
> > 
> > This is how the doc starts:
> > 
> > Evaluate EXP and print value in the echo area.
> > When called interactively, read an Emacs Lisp expression and evaluate it.
> > 
> > So I see no need to change anything here.
> 
> Doc for commands should present the behavior first in terms
> of interactive use - as a command, for all users.

Which is what it does.

> Only after that should it describe use of the command from
> Lisp code.

Which is what it does.

> The first line of the doc string should not be the first line
> of the doc string.

You are contradicting yourself.





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

* bug#19116: 25.0.50; doc string of `eval-expression'
       [not found]     ` <<83lh3vnh8z.fsf@gnu.org>
@ 2016-04-30 17:55       ` Drew Adams
  2016-04-30 18:25         ` Eli Zaretskii
  0 siblings, 1 reply; 7+ messages in thread
From: Drew Adams @ 2016-04-30 17:55 UTC (permalink / raw)
  To: Eli Zaretskii, Drew Adams; +Cc: larsi, 19116

> > > > The doc string says only what this function does "When called
> > > > interactively".  It says nothing about what it does when called from
> > > > Lisp.  Please complete the description of the function, to take care
> > > > of this.
> > >
> > > This is how the doc starts:
> > >
> > > Evaluate EXP and print value in the echo area.
> > > When called interactively, read an Emacs Lisp expression and evaluate
> > > it.
> > >
> > > So I see no need to change anything here.
> >
> > Doc for commands should present the behavior first in terms
> > of interactive use - as a command, for all users.
> 
> Which is what it does.

Nope.

> > Only after that should it describe use of the command from
> > Lisp code.
> 
> Which is what it does.
> 
> > The first line of the doc string should not be the first line
> > of the doc string.
> 
> You are contradicting yourself.

You are playing word games.

The first doc-string line should say what the command does interactively:

  Read a Lisp expression, evaluate it, and print the value in the echo area.
  ^^^^                    ^^^^             ^^^^^

Subsequent lines can describe the behavior (if different) when called
from Lisp, and they can (and usually should) describe the arguments.







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

* bug#19116: 25.0.50; doc string of `eval-expression'
  2016-04-30 17:55       ` Drew Adams
@ 2016-04-30 18:25         ` Eli Zaretskii
  0 siblings, 0 replies; 7+ messages in thread
From: Eli Zaretskii @ 2016-04-30 18:25 UTC (permalink / raw)
  To: Drew Adams; +Cc: larsi, 19116

> Date: Sat, 30 Apr 2016 09:55:08 -0800 (GMT-08:00)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: larsi@gnus.org, 19116@debbugs.gnu.org
> 
> The first doc-string line should say what the command does interactively:
> 
>   Read a Lisp expression, evaluate it, and print the value in the echo area.
>   ^^^^                    ^^^^             ^^^^^

That's exactly what it says, just in fewer words.





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

* bug#19116: 25.0.50; doc string of `eval-expression'
       [not found]         ` <<83eg9nneco.fsf@gnu.org>
@ 2016-04-30 18:38           ` Drew Adams
  0 siblings, 0 replies; 7+ messages in thread
From: Drew Adams @ 2016-04-30 18:38 UTC (permalink / raw)
  To: Eli Zaretskii, Drew Adams; +Cc: larsi, 19116

> > The first doc-string line should say what the command does
> > interactively:
> >
> >   Read a Lisp expression, evaluate it, and print the value in the echo area.
> >   ^^^^                    ^^^^             ^^^^^
> 
> That's exactly what it says, just in fewer words.

Nope.  2 out of 3.

It does not tell you that you are asked to input
an expression to evaluate.

I'm not inventing anything here, and it seems like you are
just being defensive about this.  This is the way we document
commands, as I'm sure you know.  We tell users that they will
be prompted for this and that, and we tell them what the
command does with what they enter.

I'm done with this.





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

end of thread, other threads:[~2016-04-30 18:38 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2014-11-20  3:06 bug#19116: 25.0.50; doc string of `eval-expression' Drew Adams
2016-04-30 15:19 ` Lars Ingebrigtsen
2016-04-30 17:04   ` Drew Adams
2016-04-30 17:22     ` Eli Zaretskii
     [not found]   ` <<b30dc17d-8538-4aef-aa01-11b68cb8f845@default>
     [not found]     ` <<83lh3vnh8z.fsf@gnu.org>
2016-04-30 17:55       ` Drew Adams
2016-04-30 18:25         ` Eli Zaretskii
     [not found]   ` <<<b30dc17d-8538-4aef-aa01-11b68cb8f845@default>
     [not found]     ` <<<83lh3vnh8z.fsf@gnu.org>
     [not found]       ` <<f8488fbe-4e7b-4bab-b91d-7751acf610ab@default>
     [not found]         ` <<83eg9nneco.fsf@gnu.org>
2016-04-30 18:38           ` 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).