Re: Poor quality documentation in edebug.el, and recursive documentation.

[Alan Mackenzie]

Hello, Eli.

On Sat, May 09, 2020 at 08:53:14 +0300, Eli Zaretskii wrote:
> > Date: Fri, 8 May 2020 19:59:08 +0000
> > From: Alan Mackenzie <address@hidden>
> > Cc: Clément Pit-Claudel <address@hidden>,
> >  address@hidden

> > > Any objection to the patch below?

> > Quite the opposite.  :-)  Please commit it.

> Once again: "Return value" doesn't sound right to me, since it implies
> read-only access to the value, something that AFAIU is inaccurate.  It
> actually returns a settable "place", doesn't it?

I don't know precisely what a "place" is.  I think it just means
"a form you can use setf on".  I read about it in the Elisp manual this
afternoon, but didn't get a strong impression from that.  I don't think
you can talk about a "place" as though it were a value.

So "(car foo)" (the form) could be considered a "place", since you can
use setf on it.  However that "place" is not the return value of
evaluating that form.  Or something like that.  I find it confusing.

The point about the documentation in question is that it currently
doesn't define what a function returns, and "to access" something, on
its own, is frustratingly vague.  it is on a par with defining zerop as
"Compare a number.".

So, I think the doc string in question _needs_ to use the phrase "return
value", and I think it is an accurate description of the result of
(read) "accessing" the slot.

-- 
Alan Mackenzie (Nuremberg, Germany).