bug#19116: 25.0.50; doc string of `eval-expression'

bug#19116: 25.0.50; doc string of `eval-expression'

[Drew Adams]

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'

bug#19116: 25.0.50; doc string of `eval-expression'

[Lars Ingebrigtsen]

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

bug#19116: 25.0.50; doc string of `eval-expression'

[Drew Adams]

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

bug#19116: 25.0.50; doc string of `eval-expression'

[Eli Zaretskii]

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

bug#19116: 25.0.50; doc string of `eval-expression'

[Drew Adams]

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

bug#19116: 25.0.50; doc string of `eval-expression'

[Eli Zaretskii]

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

bug#19116: 25.0.50; doc string of `eval-expression'

[Drew Adams]

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