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

[Richard Stallman <rms@gnu.org>]

[[[ 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.

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.

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.)

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.

So please help people document this in comments.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)