symbol properties

[Drew Adams]

Let me know if I'm missing something, but it seems to me that it's not easy
to find out what a particular name in a symbol's property list means or
does. This info isn't kept with the symbol (many symbols might use the same
property name, possibly in different ways); it is potentially spread among
all Lisp and C code, and it exists only in source-code form, not as
documentation. Even when you have available the libraries whose code more or
less (implicitly) defines a given property, it's not always clear what's
going on. Example: the various properties used by widget and customize.

With C-h you can easily find what a variable is for or what a function does,
and you can even follow a link to the source definition. I don't know of any
comparable way to track down what a symbol property might mean. Apropos
gives you the property names for the plist of a symbol, and you can click
the Plist link to get the full list showing the values as well as the names,
but nothing tells you what a given name or value means or is for. There is
no way to find the code whose use of it really defines what it means, short
of grepping (and then studying).

Here's an example from skeleton.el: (put ',command 'no-self-insert t). The
code contains a comment that says that this tells `self-insert-command' that
this function, if called by `abbrev', should cause the self-insert to be
skipped. It is `abbrev' that presumably controls and defines this behavior.

Without that comment, a reader of the code would be lost, because the
"definition" of `no-self-insert' is not local to the point of use - there is
no easily located "definition" - it means whatever any Lisp code decides to
use it for. And a user who doesn't read the source code misses that comment.
In fact, grepping the lisp directory for `no-self-insert' shows only one
other use of this property, and that location is not the "defining instance"
either. You must grep the src directory to find that abbrev.c establishes
the "definition" of `no-self-insert' (implicitly, by its intended use of
that property).

Would it be feasible (after the release) to provide some user help in this
regard?

Obviously, there is no definitive solution here, because the property
"names" in a plist, like their "values", can be any Lisp objects. But in
most cases the names are symbols, and in most cases the names have the same
intended "meaning" at all of their points of use.

Help on properties seems like it would be a general problem in Lisp - I
don't know if something has been done in the past in other Lisps to help in
this regard. I don't recall being aware of anything.

I'm thinking that we might introduce some construct that would let
programmers associate documentation (a sort of definition) and type
information (:type) with a plist property. Again, this wouldn't be
appropriate for all property names, because in some cases they are created
on the fly - but it would help in most cases, I think.

Currently, there is no notion of "defining" a property, other than creating
it as the property-cell value for a symbol. That is, `setplist' and `put'
are the closest things we have to plist and property definitions. We
wouldn't want to introduce the doc facility at the level of application of
these functions, because there can be any number of such applications spread
over any number of libraries. You wouldn't want to add a doc string or a
list of doc strings each time you used `put' or `setplist', and that would
be inappropriate anyway.

One possibility would be to allow definition of plist properties a la
`defcustom' (as an option, not a requirement):

 (defprop SYMBOL DOC &optional CLOSED-P &rest ARGS)

(Another name could be chosen, besides `defprop', since that has a Lisp
history with a different meaning - essentially `put' without arg
evaluation.)

Here's the analogous `defcustom': (defcustom SYMBOL VALUE DOC &rest ARGS).
There would be no need for a default VALUE as in `defcustom'. SYMBOL would
be the property name. DOC and ARGS would be just as for `defcustom' (but
this would not be associated with Customize in any way). :type, if specified
in ARGS, would control the permissible values of the property (I'm not sure
how).

CLOSED-P non-nil would mean that the definition was closed; IOW, the value
of property SYMBOL must then always respect the :type spec. By default, any
value would be allowed, instead - `defprop' would provide the possibility of
centralized type control and doc, but it would not limit use of property
lists in any way (unless CLOSED-P were non-nil). I'm not sure how or if
respect of :type could be controlled for property values - if that's
infeasible, then forget about adding CLOSED-P. CLOSED-P is orthogonal to the
proposal of providing doc definitions for properties.

I'm not sure where the defining info for a property would be stored (that
is, how `defprop' would be implemented). Perhaps a particular property on
the plist of SYMBOL could be used for this.

The actual plist for any given symbol could of course include name-value
pairs from any properties, whether or not they were defined by `defprop'.

We could define a user command `describe-property', analogous to
`describe-function' and `describe-variable'. It would prompt for a property
name (defaulting to the name at point - e.g. in an apropos Plist list) and
would display the property's doc string and a link to the defining
`defprop'.

The use of :type would be in Lisp programs that tried to set the property
value. With nil CLOSED-P (the default), there would be no limit on the
value; with non-nil CLOSED-P, an error could be raised if the value's type
didn't match. Again, I don't know how feasible it would be to try to control
respect of :type - if that's unrealistic, then forget this part (CLOSED-P).

[As a side note, we might also generate an English description of the :type,
for automatic addition to the doc string by `describe-property'. That could
apply also to `defcustom': automatically add an English description of the
:type to the doc string for `describe-variable'. The English description
could use, for example, :tag strings. The English description is already
available in the Customize buffer, but it is not used by
`describe-variable'. In many cases this info would be redundant wrt the doc
string, currently. But in the future, if this were implemented, then
programmers would be encouraged to put this info into :tag and not in the
`defcustom' doc string itself.]

Don't know if I was clear. Would this be useful? Feasible? Worth the effort?
Has something like this already been done for some other Lisp?