[Top][All Lists]

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

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

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.

reply via email to

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