[Emacs-diffs] emacs-26 861d110: Improve documentation of records

[Eli Zaretskii]

branch: emacs-26
commit 861d1100784ad2f4c7285a7afdc21e0ce216682c
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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.
---
 doc/lispref/Makefile.in  | 1 +
 doc/lispref/records.texi | 9 ++++++++-
 etc/NEWS                 | 4 ++++
 3 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in
index 9fa5901..50d6d16 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 7cc36f1..cae0f31 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
address@hidden record
address@hidden 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 ccd8190..692c28a 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.