[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Opaque objects and Emacs documentation

From: tomas
Subject: Re: Opaque objects and Emacs documentation
Date: Tue, 21 Jul 2020 12:29:11 +0200
User-agent: Mutt/1.5.21 (2010-09-15)

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

-- t

Attachment: signature.asc
Description: Digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]