[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: |
Tue, 21 Jul 2020 21:56:11 +0300 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0 |
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? I'd like to see where we stand now.
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?
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.
Or at least there shouldn't be any until we're reasonably certain we
want to support it as a public function, and we understand in what
circumstances it might be called.
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.
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.
- Re: Opaque objects and Emacs documentation, (continued)
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/19
- Re: Opaque objects and Emacs documentation, Richard Stallman, 2020/07/19
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/20
- Re: Opaque objects and Emacs documentation, tomas, 2020/07/21
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/21
- Re: Opaque objects and Emacs documentation, tomas, 2020/07/21
- Re: Opaque objects and Emacs documentation, Eli Zaretskii, 2020/07/21
- Re: Opaque objects and Emacs documentation,
Dmitry Gutov <=
- Re: Opaque objects and Emacs documentation, Eli Zaretskii, 2020/07/21
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/21
- Re: Opaque objects and Emacs documentation, Eli Zaretskii, 2020/07/22
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/22
- Re: Opaque objects and Emacs documentation, Eli Zaretskii, 2020/07/22
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/22
- Re: Opaque objects and Emacs documentation, Alan Mackenzie, 2020/07/21
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/21
- Edebug (was: Opaque objects and Emacs documentation), Stefan Monnier, 2020/07/21
- Re: Opaque objects and Emacs documentation, Eli Zaretskii, 2020/07/22