[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Opaque objects and Emacs documentation

From: Dmitry Gutov
Subject: Re: Opaque objects and Emacs documentation
Date: Wed, 22 Jul 2020 00:31:04 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0

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

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?

reply via email to

[Prev in Thread] Current Thread [Next in Thread]