Access to documentation strings

[David A. Moon <Moon at SCRC-TENEX at MIT-MC>]

I think I was supposed to make a proposal about this.

Rather than using some specific property, documentation strings should
be stored in an implementation-dependent way and there should be a
function to access them.  There are many reasons for this, including
multiple documented objects with the same name, documented objects whose
name is not a symbol, and implementations where the documentation is not
a Lisp string until you ask for it (it might reside in the compiled code
in a special machine-dependent format, or it might be retrieved from a
separate documentation file, hopefully in a speedy fashion.)

I don't think we need a separate function to get the brief
documentation, it's just (SUBSEQ doc 0 (POSITION #\Return doc)).  I
suggest the present Lisp machine function DOCUMENTATION, extended to be
similar to GET-SOURCE-FILE-NAME.  The latter function could exist in
Common Lisp as well, although perhaps not all implementations want to
remember source files for each function.

Details:
DOCUMENTATION name &OPTIONAL type
  (VALUES string type)

Accesses the documentation string for a named object.  name is the name
of an object, usually a symbol.  type is a symbol for the type of object
(see below), or NIL meaning take any type that is there, preferring a
function if there is one.  There can be multiple objects of different
types with the same name.

The first value returned is the documentation string, and the second value
is the type of object; this is only useful when the type argument was
NIL or unspecified.  If there is no documentation recorded, or no object
known with this name and type, both values are NIL.  This is not an error.

[Here I do not use "object" in the Smalltalk sense.  Would "definition"
be a better word, or does it imply "function" too strongly?]

Names of objects are usually symbols, although any Lisp object (compared
with EQUAL) is allowed.  Function names can be lists when function specs
exist.  User-defined objects could have almost anything as their name.

By special dispensation, the first argument may be a function (interpreted
or compiled) which is equivalent to supplying the name of the function.

The pre-defined object types are DEFUN for a function, special form, or
macro; DEFVAR for a global variable, parameter, or constant; DEFSTRUCT
for a structure.  There are other implementation-dependent types, and
user programs may freely add their own types.  As you can see the naming
convention is to use the name of the principle defining special form,
if there is one.  Object type symbols are deliberately not keywords,
since user-defined types may need to be protected from each other by the
package mechanism.

There is a companion function:
RECORD-DOCUMENTATION name type string

string can be NIL, which means to forget the documentation.  In some
implementations documentation for some types (especially DEFUN) is
not recorded by calling this function, but is stored some other way,
however the user can always call RECORD-DOCUMENTATION.

If people prefer, (SETF (DOCUMENTATION name type) string) would be
acceptable for this.  Note that type should not be optional when setting.