[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] master 75361be: * lisp/emacs-lisp/cl-macs.el (cl-defstruct
From: |
Stefan Monnier |
Subject: |
[Emacs-diffs] master 75361be: * lisp/emacs-lisp/cl-macs.el (cl-defstruct): Add slot option :documentation |
Date: |
Mon, 29 Jul 2019 11:56:16 -0400 (EDT) |
branch: master
commit 75361be63fcd42497dd1eb93cab3255833334475
Author: Stefan Monnier <address@hidden>
Commit: Stefan Monnier <address@hidden>
* lisp/emacs-lisp/cl-macs.el (cl-defstruct): Add slot option :documentation
Use it to improve the docstring of the accessor functions.
* doc/misc/cl.texi: Rename menu entry to "CL-Lib".
(Structures): Add ':documentation' and mention ':type' as well,
which we don't completely ignore any more.
---
doc/misc/cl.texi | 26 ++++++++++++++++++--------
etc/NEWS | 3 +++
lisp/emacs-lisp/cl-macs.el | 17 +++++++++++------
3 files changed, 32 insertions(+), 14 deletions(-)
diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index a919760..afe8f01 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -24,7 +24,7 @@ modify this GNU manual.''
@dircategory Emacs lisp libraries
@direntry
-* CL: (cl). Partial Common Lisp support for Emacs Lisp.
+* CL-Lib: (cl). Partial Common Lisp support for Emacs Lisp.
@end direntry
@finalout
@@ -4036,12 +4036,6 @@ is either a slot symbol or a list of the form
@samp{(@var{slot-name}
is a Lisp form that is evaluated any time an instance of the
structure type is created without specifying that slot's value.
-Common Lisp defines several slot options, but the only one
-implemented in this package is @code{:read-only}. A non-@code{nil}
-value for this option means the slot should not be @code{setf}-able;
-the slot's value is determined when the object is created and does
-not change afterward.
-
@example
(cl-defstruct person
(name nil :read-only t)
@@ -4049,7 +4043,23 @@ not change afterward.
(sex 'unknown))
@end example
-Any slot options other than @code{:read-only} are ignored.
+@var{slot-options} is a list of keyword-value pairs, where the
+following keywords can be used:
+
+@table @code
+@item :read-only
+A non-nil value means the slot should not be @code{setf}-able;
+the slot's value is determined when the object is created and does
+not change afterward.
+
+@item :type
+The expected type of the values held in this slot.
+
+@item :documentation
+A documentation string describing the slot.
+@end table
+
+Other slot options are currently ignored.
For obscure historical reasons, structure options take a different
form than slot options. A structure option is either a keyword
diff --git a/etc/NEWS b/etc/NEWS
index 7c21cc7..1587eab 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -535,6 +535,9 @@ be functions.
*** 'cl-defstruct' has a new ':noinline' argument to prevent inlining
its functions.
++++
+*** `cl-defstruct' slots accept a ':documentation' property
+
---
*** 'cl-values-list' will now signal an error if its argument isn't a list.
diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
index 8b9224b..1ae7266 100644
--- a/lisp/emacs-lisp/cl-macs.el
+++ b/lisp/emacs-lisp/cl-macs.el
@@ -2722,8 +2722,10 @@ node `(cl)Structures' for the description of the options.
Each SLOT may instead take the form (SNAME SDEFAULT SOPTIONS...), where
SDEFAULT is the default value of that slot and SOPTIONS are keyword-value
pairs for that slot.
-Currently, only one keyword is supported, `:read-only'. If this has a
-non-nil value, that slot cannot be set via `setf'.
+Supported keywords for slots are:
+- `:read-only': If this has a non-nil value, that slot cannot be set via
`setf'.
+- `:documentation': this is a docstring describing the slot.
+- `:type': the type of the field; currently unused.
\(fn NAME &optional DOCSTRING &rest SLOTS)"
(declare (doc-string 2) (indent 1)
@@ -2902,14 +2904,17 @@ non-nil value, that slot cannot be set via `setf'.
defaults))
(if (assq slot descp)
(error "Duplicate slots named %s in %s" slot name))
- (let ((accessor (intern (format "%s%s" conc-name slot))))
+ (let ((accessor (intern (format "%s%s" conc-name slot)))
+ (default-value (pop desc))
+ (doc (plist-get desc :documentation)))
(push slot slots)
- (push (pop desc) defaults)
+ (push default-value defaults)
;; The arg "cl-x" is referenced by name in eg pred-form
;; and pred-check, so changing it is not straightforward.
(push `(,defsym ,accessor (cl-x)
- ,(format "Access slot \"%s\" of `%s' struct CL-X."
- slot name)
+ ,(format "Access slot \"%s\" of `%s' struct CL-X.%s"
+ slot name
+ (if doc (concat "\n" doc) ""))
(declare (side-effect-free t))
,@(and pred-check
(list `(or ,pred-check
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] master 75361be: * lisp/emacs-lisp/cl-macs.el (cl-defstruct): Add slot option :documentation,
Stefan Monnier <=