Re: Opaque objects and Emacs documentation

[Eli Zaretskii]

> Cc: rms@gnu.org, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Wed, 22 Jul 2020 18:44:18 +0300
> 
> >>> What you said: describing what generics returns, or what
> >>> project-current returns in general.
> >>
> >> No, describing "in general" is good. What is bad is describing "in
> >> particular" when a function is "general" and can return values that are
> >> different from the examples. project-current is "general".
> > 
> > That's because "general" is overloaded, and you understand it in a
> > sense different from the one in which I used it.  Just drop "in
> > general" from what I wrote, and you will have a much better
> > approximation to what I meant.
> 
> If I drop both instances of the word "general" from the sentence I 
> quoted, there will be nothing left.

In _my_ sentence above there's only one "general".  the other one is
"generics", a different word.

> Perhaps you can read my description and learn something new from it?

I thought we could keep this discussion civilized for a change?

> >> And speaking of "transient", it's not helpful to say it returns a cons
> >> (transient . root) because that doesn't say anything about the project
> >> behavior anyway (which is the important part).
> > 
> > A backend that receives such an object will need to be prepared for
> > it.
> 
> The backend returned that value, so it is surely prepared.

No, it's project-current that did.

> > Even if they don't call it (and I'm unconvinced), they will need to
> > deal with the return value, so some documentation about it will be
> > useful.
> 
> The function ends with (cons 'vc root).
> 
> Is there really much uncertainty about what kind of value is returns?

Didn't we agree that understanding what an interface does shouldn't
require reading the code?

Anyway, it sounds like this discussion again veered in directions I
don't want to follow, so I will stop here.