Re: Opaque objects and Emacs documentation

[Eli Zaretskii]

> Cc: eliz@gnu.org, npostavs@gmail.com, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Tue, 21 Jul 2020 04:09:18 +0300
> 
> 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 type of "project" returned by project-current can indeed be
anything, but each hook function returns a specific type, or maybe a
small set of specific types.  So the type returned by each hook could
be documented in the doc string of that hook in terms suggested by
Richard (or something similar).  For example, project-try-vc could
have a doc string describing that for the project instance it returns.
Similarly, the "transient" project instance returned by
project-current itself, when a project doesn't yet exist, is also
known, and its structure could be similarly documented without
impediment to extensibility.

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

Whether the structure is obvious from the implementation may or may
not be true (and the author of the code is usually not the best judge
of that), but doesn't solve the issue at hand, IMO.  A good
documentation of an interface should allow a developer to write code
that uses the interface without looking at the interface's
implementation.  If it is necessary to consult the implementation,
that is an indication of some deficiency in the docs, and we should
try to avoid that as much as possible.