Re: master 0339325: ; * lisp/progmodes/project.el (project-current): Doc fix.

[Dmitry Gutov <dgutov@yandex.ru>]

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.