Re: Opaque objects and Emacs documentation

[Eli Zaretskii]

> Cc: rms@gnu.org, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Tue, 21 Jul 2020 21:56:11 +0300
> 
> On 21.07.2020 17:34, Eli Zaretskii wrote:
> > So the type returned by each hook could
> > be documented in the doc string of that hook in terms suggested by
> > Richard (or something similar).
> 
> It could. It would not be a significant problem.
> 
> > 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.

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

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

> So as things currently stand, the responsibility for it being correct 
> and accepting the right argument lies on its author, and not on any 
> third-party developers.

Yes, but "its author" doesn't have to be a single person, and doesn't
have to be the same person who wrote the initial implementations.

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