[Top][All Lists]

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

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

From: Dmitry Gutov
Subject: Re: master 1e3b0f2: Improve doc strings of project.el
Date: Mon, 20 Jul 2020 00:59:07 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0

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.


reply via email to

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