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

[Drew Adams <drew.adams@oracle.com>]

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