From 861d1100784ad2f4c7285a7afdc21e0ce216682c Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 22 Dec 2017 12:04:23 +0200 Subject: [PATCH] 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 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. -- 2.39.2