procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve docstring of cl-defstruct accessors

Browse source 
* 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.
This commit is contained in:
Stefan Kangas 2025-03-24 00:33:37 +01:00
parent 9e005e9da0
commit 1b56e0f169
2 changed files with 15 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
lisp/emacs-lisp/cl-macs.el
View file

@ -3229,7 +3229,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
@ -3246,15 +3247,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

4
lisp/help-fns.el
View file

@ -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)