[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 18:44:18 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0

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

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

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.

reply via email to

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