Re: Opaque objects and Emacs documentation

[tomas]

On Tue, Jul 21, 2020 at 01:14:16PM +0300, Dmitry Gutov wrote:
> 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.

Yes, and I do feel your pain. Don't take this as a personal attack,
that'd the last thing I wish for. It's just that I do understand
also Eli's position, and I feel that it has merit -- it is unfair
to depict it as "just Eli's thoughts".

Cheers
-- t

signature.asc
Description: Digital signature