From: Stefan Monnier <monnier@iro.umontreal.ca>
Date: Mon, 29 Jul 2019 15:56:11 +0000 (-0400)
Subject: * lisp/emacs-lisp/cl-macs.el (cl-defstruct): Add slot option :documentation
X-Git-Tag: emacs-27.0.90~1817^2~33
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=75361be63fcd42497dd1eb93cab3255833334475;p=emacs.git

* 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.
---

diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index a9197602634..afe8f01f596 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 7c21cc79307..1587eab1e29 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 8b9224bd1b7..1ae72666244 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