[Emacs-diffs] master 4753f3f: Update documentation for type semantics of records.

[Lars Brinkhoff]

branch: master
commit 4753f3f0af33c5defe3a340f82265db6a6863030
Author: Lars Brinkhoff <address@hidden>
Commit: Lars Brinkhoff <address@hidden>

    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.
---
 doc/lispref/elisp.texi   |  1 +
 doc/lispref/objects.texi | 16 +++++++++++++++-
 doc/lispref/records.texi |  4 ++++
 src/alloc.c              | 10 ++++++----
 4 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 3a348aa..bff3112 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -316,6 +316,7 @@ Programming Types
 * 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.
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 90cafbe..cc93209 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.
 
address@hidden Type Descriptors
address@hidden 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.
address@hidden 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
address@hidden
+
 @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)
diff --git a/doc/lispref/records.texi b/doc/lispref/records.texi
index a6c560c..a924baf 100644
--- a/doc/lispref/records.texi
+++ b/doc/lispref/records.texi
@@ -19,6 +19,10 @@ implementation records can have at most 4096 slots, whereas 
vectors
 can be much larger.  Like arrays, records use zero-origin indexing:
 the first slot has index 0.
 
+  The type slot should be a symbol or a type descriptor.  If it's a
+type descriptor, the symbol naming its type will be returned;
address@hidden Descriptors}.  Any other kind of object is returned as-is.
+
   The printed representation of records is @samp{#s} followed by a
 list specifying the contents.  The first list element must be the
 record type.  The following elements are the record slots.
diff --git a/src/alloc.c b/src/alloc.c
index a58824f..fad84b8 100644
--- a/src/alloc.c
+++ b/src/alloc.c
@@ -3411,8 +3411,9 @@ allocate_record (EMACS_INT count)
 
 DEFUN ("make-record", Fmake_record, Smake_record, 3, 3, 0,
        doc: /* Create a new record.
-TYPE is its type as returned by `type-of'.  SLOTS is the number of
-non-type slots, each initialized to INIT.  */)
+TYPE is its type as returned by `type-of'; it should be either a
+symbol or a type descriptor.  SLOTS is the number of non-type slots,
+each initialized to INIT.  */)
   (Lisp_Object type, Lisp_Object slots, Lisp_Object init)
 {
   CHECK_NATNUM (slots);
@@ -3427,8 +3428,9 @@ non-type slots, each initialized to INIT.  */)
 
 DEFUN ("record", Frecord, Srecord, 1, MANY, 0,
        doc: /* Create a new record.
-TYPE is its type as returned by `type-of'.  SLOTS is used to
-initialize the record slots with shallow copies of the arguments.
+TYPE is its type as returned by `type-of'; it should be either a
+symbol or a type descriptor.  SLOTS is used to initialize the record
+slots with shallow copies of the arguments.
 usage: (record TYPE &rest SLOTS) */)
   (ptrdiff_t nargs, Lisp_Object *args)
 {