Improve docstring of cl-defstruct accessors

* lisp/emacs-lisp/cl-macs.el (cl-defstruct): Improve generated
docstring by not leaking the internal CL-X argument name, preferring X
instead.  Set property 'document-generalized-variable', used below.
* lisp/help-fns.el (help-fns--generalized-variable): When function has
non-nil property 'document-generalized-variable', document it as a
generalized variable.

(cherry picked from commit 1b56e0f1694650c3c567b90e1ae3caa0bfea209e)

diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
index c2815133a347e2794b1e15fea9bd385e805b6d06..9d45816309478a3b03d0952ad4f6de5cd1e02742 100644 (file)
--- a/lisp/emacs-lisp/cl-macs.el
+++ b/lisp/emacs-lisp/cl-macs.el
@@ -3179,7 +3179,8 @@ To see the documentation for a defined struct type, use
              ;; and pred-check, so changing it is not straightforward.
              (push `(,defsym ,accessor (cl-x)
                        ,(let ((long-docstring
-                               (format "Access slot \"%s\" of `%s' struct CL-X." slot name)))
+                               (format "Access slot \"%s\" of `%s' struct X."
+                                       slot name)))
                           (concat
                            ;; NB.  This will produce incorrect results
                            ;; in some cases, as our coding conventions
@@ -3196,15 +3197,22 @@ To see the documentation for a defined struct type, use
                                        80))
                                (concat
                                 (internal--format-docstring-line
-                                 "Access slot \"%s\" of CL-X." slot)
+                                 "Access slot \"%s\" of X." slot)
                                 "\n"
                                 (internal--format-docstring-line
-                                 "Struct CL-X is a `%s'." name))
+                                 "Struct X is a `%s'." name))
                              (internal--format-docstring-line long-docstring))
-                           (if doc (concat "\n" doc) "")))
+                           (if doc (concat "\n" doc) "")
+                           "\n"
+                           (format "\n\n(fn %s X)" accessor)))
                        (declare (side-effect-free t))
                        ,access-body)
                     forms)
+              ;; FIXME: This hack is to document this as a generalized
+              ;; variable, despite it not having the `gv-expander'
+              ;; property.  See `help-fns--generalized-variable'.
+              (push `(function-put ',accessor 'document-generalized-variable t)
+                    forms)
               (when (oddp (length desc))
                 (push
                  (macroexp-warn-and-return

diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 9d978a4572dcf109101010f1e98d97f8e6bce78d..78fb1b444b3af856a6a14f7140df912a44982bd8 100644 (file)
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -1262,7 +1262,9 @@ Returns a list of the form (REAL-FUNCTION DEF ALIASED REAL-DEF)."
 
 (defun help-fns--generalized-variable (function)
   (when (and (symbolp function)
-             (get function 'gv-expander)
+             (or (get function 'gv-expander)
+                 ;; This is a hack, see cl-macs.el:
+                 (get function 'document-generalized-variable))
              ;; Don't mention obsolete generalized variables.
              (not (get function 'byte-obsolete-generalized-variable)))
     (insert (format-message "  `%s' is also a " function)