From: Stefan Kangas <stefan@marxist.se>
Date: Fri, 24 Dec 2021 05:30:41 +0000 (+0100)
Subject: Merge from origin/emacs-28
X-Git-Tag: emacs-29.0.90~3480
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=6a17bb48798bf88458d43e7417e64d2efd74494b;p=emacs.git

Merge from origin/emacs-28

04be23f19f Improve Xref documentation
edb1d491d9 * lisp/net/shr.el (shr-expand-url): Also strip trailing wh...
---

6a17bb48798bf88458d43e7417e64d2efd74494b
diff --cc lisp/progmodes/xref.el
index ca3594d253b,fd59a7b98c8..c1981cc1ce0
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@@ -195,23 -195,28 +195,35 @@@ is not known.
  
  ;;; Cross-reference
  
 -(cl-defstruct (xref-item
 -               (:constructor xref-make (summary location))
 -               (:noinline t))
 +(defmacro xref--defstruct (name &rest fields)
 +  (declare (indent 1))
 +  `(cl-defstruct ,(if (>= emacs-major-version 27)
 +                      name
 +                    (remq (assq :noinline name) name))
 +     ,@fields))
 +
 +(xref--defstruct (xref-item
 +                  (: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)
 -               (:constructor xref-make-match (summary location length))
 -               (:noinline t))
 +(xref--defstruct (xref-match-item
 +                  (:include xref-item)
 +                  (:constructor xref-make-match (summary location length))
 +                  (:noinline t))
    "A match xref item describes a search result."
    length)