summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDmitry Gutov <dgutov@yandex.ru>2021-12-24 03:24:52 +0200
committerDmitry Gutov <dgutov@yandex.ru>2021-12-24 03:25:22 +0200
commit04be23f19f6d1290906d2a392a05c58703ea76c5 (patch)
tree380e5149168e8a03dc727c6a89e8381137ae0ba3
parentedb1d491d968144c4b3a0d0efe0afc22448c4684 (diff)
downloademacs-04be23f19f6d1290906d2a392a05c58703ea76c5.tar.gz
Improve Xref documentation
* lisp/progmodes/xref.el (xref-item): Add docstring for 'summary'. Fix typo in the header Commentary.
-rw-r--r--lisp/progmodes/xref.el16
1 files changed, 14 insertions, 2 deletions
diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index 492be9a104d..fd59a7b98c8 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -44,7 +44,7 @@
;;
;; The last three methods operate with "xref" and "location" values.
;;
-;; One would usually call `make-xref' and `xref-make-file-location',
+;; One would usually call `xref-make' and `xref-make-file-location',
;; `xref-make-buffer-location' or `xref-make-bogus-location' to create
;; them. More generally, a location must be an instance of a type for
;; which methods `xref-location-group' and `xref-location-marker' are
@@ -199,7 +199,19 @@ is not known."
(:constructor xref-make (summary location))
(:noinline t))
"An xref item describes a reference to a location somewhere."
- summary location)
+ (summary nil :documentation "String which describes the location.
+
+When `xref-location-line' returns non-nil (a number), the summary
+is implied to be the contents of a file or buffer line containing
+the location. When multiple locations in a row report the same
+line, in the same group (corresponding to the case of multiple
+locations on one line), the summaries are concatenated in the
+Xref output buffer. Consequently, any code that creates xref
+values should take care to slice the summary values when several
+locations point to the same line.
+
+This behavior is new in Emacs 28.")
+ location)
(cl-defstruct (xref-match-item
(:include xref-item)