[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#19116: 25.0.50; doc string of `eval-expression'
From: |
Drew Adams |
Subject: |
bug#19116: 25.0.50; doc string of `eval-expression' |
Date: |
Sat, 30 Apr 2016 09:55:08 -0800 (GMT-08:00) |
> > > > 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.