Improve documentation of records

* doc/lispref/Makefile.in (srcs): Add the forgotten records.texi.
* doc/lispref/records.texi (Records): Recommend that record type
names use package-naming conventions.

* etc/NEWS: Add the naming convention recommendation for record
types.

diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in
index 9fa5901a1ac2a894fd507e38ca3ef5295c7a948e..50d6d161ef6341abed864e4d0afdc01fa00178db 100644 (file)
--- a/doc/lispref/Makefile.in
+++ b/doc/lispref/Makefile.in
@@ -118,6 +118,7 @@ srcs = \
   $(srcdir)/package.texi \
   $(srcdir)/positions.texi \
   $(srcdir)/processes.texi \
+  $(srcdir)/records.texi \
   $(srcdir)/searching.texi \
   $(srcdir)/sequences.texi \
   $(srcdir)/streams.texi \

diff --git a/doc/lispref/records.texi b/doc/lispref/records.texi
index 7cc36f14068f78a542b6b41614f118af7bbd02bc..cae0f31f273e3b86e02125c1b368f09f75234fe6 100644 (file)
--- a/doc/lispref/records.texi
+++ b/doc/lispref/records.texi
@@ -5,7 +5,7 @@
 @c See the file elisp.texi for copying conditions.
 @node Records
 @chapter Records
-@cindex record
+@cindex records
 
   The purpose of records is to allow programmers to create objects
 with new types that are not built into Emacs.  They are used as the
@@ -28,6 +28,13 @@ type descriptor, the symbol naming its type will be returned;
 list specifying the contents.  The first list element must be the
 record type.  The following elements are the record slots.
 
+  To avoid conflicts with other type names, Lisp programs that define
+new types of records should normally use the naming conventions of the
+package where these record types are introduced for the names of the
+types.  Note that the names of the types which could possibly conflict
+might not be known at the time the package defining a record type is
+loaded; they could be loaded at some future point in time.
+
   A record is considered a constant for evaluation: the result of
 evaluating it is the same record.  This does not evaluate or even
 examine the slots.  @xref{Self-Evaluating Forms}.

diff --git a/etc/NEWS b/etc/NEWS
index ccd819077ea02d61feaf94100e5de9564bd9001f..692c28a7210a90f1bbdbc6fd970995f42ace8014 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1584,6 +1584,10 @@ functions 'make-record', 'record', and 'recordp'.  Records are now
 used internally to represent cl-defstruct and defclass instances, for
 example.
 
+If your program defines new record types, you should use
+package-naming conventions for naming those types.  This is so any
+potential conflicts with other types are avoided.
+
 +++
 ** 'save-some-buffers' now uses 'save-some-buffers-default-predicate'
 to decide which buffers to ask about, if the PRED argument is nil.