Update documentation for type semantics of records.

* objects.texi (Record Type): improve description of what
`type-of' returns for records.
(Type Descriptors): new section.
* elisp.texi: reference it.
* records.texi (Records): reference it.  Document behaviour when type
slot is a record.

* alloc.c (Fmake_record, Frecord): mention type desciptors.

1 files changed, 15 insertions, 1 deletions

diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 90cafbef642..cc9320987f2 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -156,6 +156,7 @@ latter are unique to Emacs Lisp.
 * Primitive Function Type::     A function written in C, callable from Lisp.
 * Byte-Code Type::      A function written in Lisp, then compiled.
 * Record Type::         Compound objects with programmer-defined types.
+* Type Descriptors::    Objects holding information about types.
 * Autoload Type::       A type used for automatically loading seldom-used
                         functions.
 * Finalizer Type::      Runs code when no longer reachable.
@@ -1359,6 +1360,18 @@ types that are not built into Emacs.
 
   @xref{Records}, for functions that work with records.
 
+@node Type Descriptors
+@subsection Type Descriptors
+
+  A @dfn{type decriptor} is a @code{record} which holds information
+about a type.  Slot 1 in the record must be a symbol naming the type.
+@code{type-of} relies on this to return the type of @code{record}
+objects.  No other type descriptor slot is used by Emacs; they are
+free for use by Lisp extensions.
+
+An example of a type descriptor is any instance of
+@code{cl-structure-class}.
+
 @node Autoload Type
 @subsection Autoload Type
 
@@ -2037,7 +2050,8 @@ This function returns a symbol naming the primitive type of
 @code{marker}, @code{mutex}, @code{overlay}, @code{process},
 @code{string}, @code{subr}, @code{symbol}, @code{thread},
 @code{vector}, @code{window}, or @code{window-configuration}.
-However, if @var{object} is a record, its first slot is returned.
+However, if @var{object} is a record, the type specified by its first
+slot is returned; @ref{Records}.
 
 @example
 (type-of 1)