Re: Opaque objects and Emacs documentation

[Stefan Monnier]

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

I believe in this specific case, the issue is that the shape can and
will change and not only over time.  The only thing defined is an
interface and any code which relies on more than this interface
(e.g. a function which relies on completion-tables being lists of
strings) will break sooner or later.

Of course, that doesn't prevent the doc from giving *examples* to show
the intended behavior.


        Stefan