[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 04:09:18 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0

On 20.07.2020 05:44, Richard Stallman wrote:
[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

   > Consider the docstring of said constructor function. What should it say
   > its return value is?

One natural possibility:

   Return an empty project object.  You need to store values in it with ...


   Return a project object with name MAME and containing files FILES.

I am guessing here.  I don't know what these projects do.
I don't know what data a project object should have.

Okay, see, neither option is going to work.

We have a "factory" function (called 'project-current') which delegates project instance creation to a hook. Which is what makes it extensible. The only argument is DIRECTORY, meaning the current directory. The functions in the hook get called in turn, and the first one that returns non-nil is going to be used. Its return value must be a "project instance" which satisfies a certain protocol defined by several cl-generic methods (think "interface" in Java, or "typeclass" in Haskell, or "protocol" in Clojure, or multimethods elsewhere). One method is mandatory to be defined for all project implementations, the rest have default implementations.

Thanks to the cl-generic infrastructure, the datatype representing the current project can be almost anything, and the structure of the fields inside can be arbitrary. This is sorted out by each individual backend which knows how to access fields inside "project instances" belonging to it, and which implements the aforementioned protocol for that instance type.

The two built-in backends use very simple structures (right now: conses like (TYPE-TAG . PROJECT-ROOT)), which is very obvious from their implementations. 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.

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.

Of course, we can add this information elsewhere, e.g. in the comments of the "backend" functions (which are the elements of the hook I mentioned above). I haven't done so because, well, the implementations are fairly transparent and the structures are trivial. But I wouldn't object against somebody doing that.

> It is important to document the meaning of each slot -- that may not
> be obvious.  Which values are valid?

The space of possible structures of valid project instances is theoretically infinite.

reply via email to

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