Re: Opaque objects and Emacs documentation

[Basil L. Contovounesios]

Eli Zaretskii <eliz@gnu.org> writes:

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

FWIW, I think Emacs documentation is one of the best things since pita
bread, and always hate to see it intentionally omitted.

There is nothing wrong with saying "the following are internal details
that shouldn't be relied on, but nevertheless here are their structure
and semantics".  In fact, I think it is infinitely better to do so.
There is little point or benefit in Emacs following conventions of other
communities, such as the aforementioned OO community.

With the exception of certain sensitive pieces of information such as
passwords in memory, I think Emacs benefits from being as open and
documented as reasonably possible.  There is nothing wrong with authors
not having the time, energy, or willingness to document everything they
write from the outset, but if other volunteers offer to complete the
documentation then I don't see why that should cause friction.

Multimethods are a very useful and powerful idiom, but the slight
increase in both source- and application-level complexity they add makes
it all the more important to document interfaces and intermediate
representations, even internal ones, for the benefit of users and
programmers alike.  Tooling can only go so far.

Thanks,

-- 
Basil