Re: Opaque objects and Emacs documentation

[Dmitry Gutov]

On 22.07.2020 17:28, Eli Zaretskii wrote:

> > > > If you say that, could you give an example of something that *would* be
> > > > an impediment to extensibility?
> > >
> > > 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.

Perhaps you can read my description and learn something new from 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.

> > > If those are the rules of the game, yes.  IOW, if it's not okay to
> > > describe the possible forms of the object in the doc string of
> > > project-find-functions, but okay to describe them in the individual
> > > doc strings of each hook that can be put there, then it could be an
> > > acceptable compromise, at least from my POV.
> >
> > Very well. The "transient" project is not on the hook, though.
>
> Yes, but the code which returns it is a kind of "default
> implementation" for bootstrapping projects.  So it is definitely in
> the same class of objects as the vc project.

Yes. If the same class as "shouldn't be documented in too much detail in 
project-current or project-find-functions".

> > > > Right. But there won't be any third-party callers of project-try-vc,
> > > > this function's only purpose is to be inside project-find-functions.
> > >
> > > I'm thinking about additional "authors" who'd like to add
> > > functionality to existing project backends.
> >
> > They won't call it either. If they do, the function is likely to have
> > changed significantly from its current state.
>
> 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?

> > > > No disagreement there, as long as we're talking about public functions.
> > >
> > > Are we still under the rule that any function without 2 dashes in its
> > > name is public?  If so, then I think we have only discussed public
> > > functions in this and related threads.
> >
> > OK, I have a question then. Does every built-in member of a public hook
> > need to be public?
>
> The main point here is that the particular types of objects the
> existing backends produce should be documented somewhere.

Check out 'M-x describe-function RET project-root RET', the 
"Implementations:" section.