Johann 'Myrkraverk' Oskarsson writes:
Is there a convention to refer to and document types in docstrings?
(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
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
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.)
If I put something like `my-type' in a docstring, do people
be able to find a docstring with something like C-h v ?
And related; is there something people typically use to jump from a
docstring to a related info manual?
Not that I know of. M-< C-h C-f should do the trick in most cases.
XEmacs-Beta mailing list