Re: Opaque objects and Emacs documentation

[Eli Zaretskii <eliz@gnu.org>]

> Cc: emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Fri, 17 Jul 2020 01:40:59 +0300
> 
> > 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.

Basically, you are saying that in your opinion this is as it should
be, and cannot be helped.

Which I think is against long-time Emacs tradition for documenting its
interfaces, and by that facilitating extensibility.  It is IMO wrong
to fill Emacs application levels with opaque objects which cannot be
usefully described; they should be a rare exception, but definitely
not the rule.

Therefore, we will most probably have many disputes in the future on
related issues which all boil down to this basic disagreement.

I wonder who else around here agrees with you on this, and invite
people who have an opinion to please speak up.  I've changed the
Subject to make it more descriptive.