Re: Opaque objects and Emacs documentation

[Dmitry Gutov]

On 21.07.2020 11:57, tomas@tuxteam.de wrote:

> I don't think it's intentional, but please reconsider this:

Reconsider the phrasing?

> > [...] The core of the dispute is whether
> > project-current's docstring should document the return value in
> > detail (giving an example of built-in project instances's
> > structure). Eli is insisting on it because (AFAICT) that suits his
> > thought process and he thinks that will help users/clients to make
> > sense of how things work.
>
> in a few words: Eli's thought process vs...

That's how I understand it. And there is nothing bad in documenting code 
along the lines of someone's thoughts. It's generally a good thing. But 
not when it defeats the purpose of how the code is written.

> > I am adamantly against this because it's against the design (clients
> > should program against the public interface, not against the
> > implementation), and is likely to encourage incorrect programs.
>
> ... The Right Way To Do It (TM).
>
> It comes across as a little... biased. Which is understandable,
> but not a good position when bargaining, nevertheless ;-)

The whole situation is biased, in multiple respects.