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.

3 files changed, 13 insertions, 1 deletions

diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in
index 9fa5901a1ac..50d6d161ef6 100644
--- 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 7cc36f14068..cae0f31f273 100644
--- 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 ccd819077ea..692c28a7210 100644
--- 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.