Re: Opaque objects and Emacs documentation

[Dmitry Gutov]

On 22.07.2020 19:30, Eli Zaretskii wrote:

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

Same root, similar purpose.

Describing what generics return is fine, the project-current's docstring 
already does that, actually. The issue is in the manner of the 
description. You insist on describing the data structure (as opposed to 
describing associated behaviors), but the callers of that function 
should never need it.

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

project-current received it from the backend and returned it to the caller.