Re: Opaque objects and Emacs documentation

[Dmitry Gutov]

On 21.07.2020 22:33, Eli Zaretskii wrote:

> > > Similarly, the "transient" project instance returned by
> > > project-current itself, when a project doesn't yet exist, is also
> > > known, and its structure could be similarly documented without
> > > impediment to extensibility.
> >
> > 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".

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

> > > Whether the structure is obvious from the implementation may or may
> > > not be true (and the author of the code is usually not the best judge
> > > of that), but doesn't solve the issue at hand, IMO.
> >
> > So have we moved on from trying to document the examples in the
> > docstrings of project-find-functions or project-current?
>
> 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.

> > > A good
> > > documentation of an interface should allow a developer to write code
> > > that uses the interface without looking at the interface's
> > > implementation.
> >
> > 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.

> > > If it is necessary to consult the implementation,
> > > that is an indication of some deficiency in the docs, and we should
> > > try to avoid that as much as possible.
> >
> > 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?