[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: master 0339325: ; * lisp/progmodes/project.el (project-current): Doc
From: |
Dmitry Gutov |
Subject: |
Re: master 0339325: ; * lisp/progmodes/project.el (project-current): Doc fix. |
Date: |
Fri, 17 Jul 2020 01:40:59 +0300 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0 |
I'll try to keep this short.
On 13.07.2020 16:21, Eli Zaretskii wrote:
Btw, your implementation style makes it unusually hard to write good
doc strings. I'm not quite sure why, but one possible reason is that
IMO you bring the generics too high, too close to the application
level, where doc strings should be more and more user-oriented.
The recent packages where you see this problem (and I agree that it's
not ideal) are those which offer the possibility to customize complex
behaviors. To an unprecedented degree, if we compare to older Emacs
features.
Before xref and project.el, I think the closest one was minibuffer.el
with its "completion tables" which can are often represented by
anonymous functions. Which is another type of an opaque value.
Both xref and project.el could have used functions this way as well (a
version doing that was initially proposed for xref). But any impression
that such values would be easier to understand is illusory.
When
this is coupled with your reluctance, to say the least, to disclose
details of what you consider to be opaque objects, it becomes hard to
say anything useful about many functions, because describing what
functions do usually involves talking about their inputs and outputs,
and how the former are processed into the latter.
We're using cl-generic as an implementation technique. It's a more
general implementation of dynamic dispatch, more commonly known to a lot
of programmers from OOP.
The "for example"
method that I tried to use was about the only technique I could think
of to overcome those difficulties, and you reject even that.
If we use the OOP analogy, you are trying to describe "object instances"
in full detail, beyond the public interface, together with their
"private fields", so to speak. It's a definite anti-pattern in OO community.
Whether one agrees with your coding style or not, the difficulties it
presents to documenting our code are real, and I suggest that you
consider this disadvantage seriously, because it basically flies in
the face of long-standing traditions of Emacs self-documenting
features.
We could discuss alternative implementation approaches, but I think you
will find none will fit the basic requirements of these packages.
Or at least that the possible options will require the client to treat
the values as "opaque" exactly the same way.
- Re: master 0339325: ; * lisp/progmodes/project.el (project-current): Doc fix., Dmitry Gutov, 2020/07/12
- Re: master 0339325: ; * lisp/progmodes/project.el (project-current): Doc fix., Eli Zaretskii, 2020/07/12
- Re: master 0339325: ; * lisp/progmodes/project.el (project-current): Doc fix., Dmitry Gutov, 2020/07/13
- Re: master 0339325: ; * lisp/progmodes/project.el (project-current): Doc fix., Eli Zaretskii, 2020/07/13
- Re: master 0339325: ; * lisp/progmodes/project.el (project-current): Doc fix., Dmitry Gutov, 2020/07/13
- Re: master 0339325: ; * lisp/progmodes/project.el (project-current): Doc fix.,
Dmitry Gutov <=
- Re: Opaque objects and Emacs documentation, Eli Zaretskii, 2020/07/17
- Re: Opaque objects and Emacs documentation, tomas, 2020/07/17
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/17
- Re: Opaque objects and Emacs documentation, tomas, 2020/07/17
- Re: Opaque objects and Emacs documentation, Basil L. Contovounesios, 2020/07/17
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/17
- Re: Opaque objects and Emacs documentation, Basil L. Contovounesios, 2020/07/17
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/17
- Re: Opaque objects and Emacs documentation, Eli Zaretskii, 2020/07/17
- Re: Opaque objects and Emacs documentation, Noam Postavsky, 2020/07/17