Re: master 1e3b0f2: Improve doc strings of project.el

[Dmitry Gutov <dgutov@yandex.ru>]

On 19.07.2020 05:27, 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. ]]]
> 
> A Unix file descriptor is a datatype which is semantically opaque and
> has a representation which is literally opaque.  There is nothing
> inside it that a user program can make sense of.  Once the developer
> of the user program knows this much, there is nothing more to say
> about it.

But there are reasons behind this state of affairs. It's a man-made 
design, not a force of nature.

My point is, having semantically opaque datatypes can be good for us, in 
certain applications.

> The package data structure is a very different case.  It is made up of
> Lisp data structures which any Lisp program, and any Emacs user, could
> look inside.
> 
> I gather that package.el provides a complete API of functions to do
> everything anyone would wish, with this data structure.  If so, people
> and programs invoking package.el don't need to know how that data
> structure is made up.  There is no need to describe it in doc strings.

This discussion is about project.el, not package.el.

But I think we agree on the general point: as long as people and 
programs provide an adequate API (which is our goal anyway), we don't 
need to describe in detail how its data structures (plural, in this 
case) are made up.

> But people working on package.el in the future, and people trying to
> understand it, do need to know its structure.  So it should have
> comments which explain.  (I expect Linux has comments describing the
> meaning of file descriptor data structures.)

I have nothing against comments, but in this case the data structures 
are pretty trivial and obvious from the functions that create them.

So I don't immediately see anything in there that would need 
clarification in comments, but would not stop people from doing so.

> We shouldn't wait to document that data structure, because any one of
> us (and that includes you) might, at any moment, suddenly be unable to
> continue working on Emacs.  With luck, you won't have to stop this
> year -- but it will surely happen some day.

Indeed.