[Top][All Lists]

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

Re: Opaque objects and Emacs documentation

From: Dmitry Gutov
Subject: Re: Opaque objects and Emacs documentation
Date: Tue, 21 Jul 2020 13:14:16 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0

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.

reply via email to

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