The proper way to refer and document types in docstrings?

Johann 'Myrkraverk' Oskarsson writes: (1) There should be a <type>-p function, which indicates that <type> is indeed a type. The docstring is typically trivial (eg, facep). (2) If the type is intended to be more or less immutable, *my preference* is for the standard properties of the type to all be initializable and documented in a make-<type> function. In the case of something like a network database, you might automatically create an instance with a "connect" function, for example. You should still have a make-<type> function to create the object that represents a connection. You express the fact that the connect function is the primary interface by autoloading it, but not the make-<type> function. However, the common practice for things like database connections seems to be to omit the make-<type> function and initialize all the properties in the connect function. I don't have a strong objection to this; use it if you prefer it. However, *all* Lisp-visible standard properties (even those that are created internally, not set from arguments) must be documented in this function. If there are *multiple* "open" or "connect" functions, I do strongly recommend a single make-<type> function as the appropriate place to document properties and behavior of the type. (3) If the type is intended to be generally mutable, the standard properties of the type should be settable and documented in the set-<type>-property function. Again, *all* Lisp-visible standard properties must be documented in this function. Note that most such objects also support user-defined properties. When this is true, the fact should be mentioned, but of course you can't document their meaning here. The query function <type>-property should refer to the function providing the documentation. Some types don't have a specific query function; recent practice has permitted overloading `get' and `put' to work on any object with properties. (In this case there won't be a set-<type>-property, so the standard properties should be documented in the make-<type> function.) No. Not that I know of. M-< C-h C-f should do the trick in most cases. Steve _______________________________________________ XEmacs-Beta mailing list XEmacs-Beta(a)xemacs.org http://lists.xemacs.org/mailman/listinfo/xemacs-beta