Merge from origin/emacs-28

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

diff --cc lisp/net/shr.el
Simple merge

diff --cc lisp/progmodes/xref.el
index ca3594d253babb6b1c23ebab753fd11d6417c7b2,fd59a7b98c8db9f319d0079cc4bdd65f1195d18e..c1981cc1ce075561468be232155347e2022a3896
--- 1/lisp/progmodes/xref.el
--- 2/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@@ -195,23 -195,28 +195,35 @@@ is not known.
  \f
  ;;; 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)