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 13:53:35 +0300
> 
> It shouldn't come as a surprise that I think there is no better 
> technological choice. Otherwise I would have used it.

??? You are saying that the _only_ way to design project.el is to use
generics at that high level?  Just because sometimes a "project
instance" is a cons cell and sometimes some other Lisp structure?  I'm
surprised to hear that.

> What should help is coming up with a better, consistent way to document 
> these things.

I tried to find one, but couldn't.  If someone wants to propose a way,
I'm all ears.  I wrote those comments which started this thread
because it surprised me how difficult it was to try to keep the
limitations you impose on what should and what shouldn't be divulged,
and yet produce useful documentation of what the various public
functions do.  In all my 40 years of experience with Emacs, I have
never bumped into such a brick wall, with no way around it.

Later it became apparent that you are doing this on purpose, because
you have decided that certain directions of developing the package
should be made as hard as possible, something that I think is
completely against the spirit of Emacs development.  Readers of this
thread are invited to read

  https://lists.gnu.org/archive/html/emacs-devel/2020-07/msg00288.html

especially under "Here are things we want third-party code to be able
to do" and "Here are, on the other hand, things that people generally
shouldn't do".  Again, I'm interested to know how many of us here
share those views.

> > 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.
> 
> The problem here is that even if you document a particular value, it's 
> _not useful_. It doesn't show you what you can or should do with it.

It was very useful for me, and so I presume it could be useful for
others.  Even if you think it is not useful for you, the fact that
fellow developers tell you the contrary should be a reason to revisit
your views, and maybe allow for other views as well, even if you
disagree.

Documentation should strive to serve different ways of studying and
developing Emacs, not just a single way that you personally think is
The (only) Right Thing.

> The main thing thing the user can do with that value is misuse it, by 
> relying on its shape in the client code.

Once again: concealing information because someone could be silly
enough to misuse it punishes many valid uses on behalf of a few
invalid ones.  We should treat our users as responsible adults, even
if some of them aren't.  Those who aren't will eventually be amply
punished, or will recognize their mistakes and get their act together.