Merge from origin/emacs-27

70fe552c61 ; xref-references-in-directory: Autoload as well
181f571651 Fix up requires
43f66c3368 Extract xref-matches-in-files from project--find-regexp-in...
65af18d86e Rename xref-collect-references and xref-collect-matches
98788bf976 ; Improve the docstring some more
c190e91a1e Improve docstrings
012c12a05e Fix when expose draws partially visible first glyph (bug#3...
d915b8c3f1 Don't require semantic/fw
50a0126402 Do some renames for clarity
74261ff301 Rearrange NEWS, add missing documentation
6c9571379e Fix interactive spec in netrc-parse
32222fb34c Fix documentation of define-obsolete-* functions

# Conflicts:
#	etc/NEWS

5 files changed, 92 insertions, 71 deletions

diff --git a/lisp/dired-aux.el b/lisp/dired-aux.el
index ce967b0735f..dbe69e54820 100644
--- a/lisp/dired-aux.el
+++ b/lisp/dired-aux.el
@@ -2958,7 +2958,6 @@ with the command \\[tags-loop-continue]."
 (declare-function xref--show-xrefs "xref")
 (declare-function xref-query-replace-in-results "xref")
 (declare-function project--files-in-directory "project")
-(declare-function project--find-regexp-in-files "project")
 
 ;;;###autoload
 (defun dired-do-find-regexp (regexp)
@@ -2994,7 +2993,7 @@ REGEXP should use constructs supported by your local `grep' command."
                    (push mark files)))
                (nreverse marks))
               (setq xrefs
-                    (project--find-regexp-in-files regexp files))
+                    (xref-matches-in-files regexp files))
               (unless xrefs
                 (user-error "No matches for: %s" regexp))
               xrefs))))
diff --git a/lisp/emacs-lisp/byte-run.el b/lisp/emacs-lisp/byte-run.el
index 1115c096679..3737473b63b 100644
--- a/lisp/emacs-lisp/byte-run.el
+++ b/lisp/emacs-lisp/byte-run.el
@@ -378,8 +378,8 @@ is equivalent to the following two lines of code:
 \(defalias \\='old-fun \\='new-fun \"old-fun's doc.\")
 \(make-obsolete \\='old-fun \\='new-fun \"22.1\")
 
-If provided, WHEN should be a string indicating when the function
-was first made obsolete, for example a date or a release number.
+WHEN should be a string indicating when the function was first
+made obsolete, for example a date or a release number.
 
 See the docstrings of `defalias' and `make-obsolete' for more details."
   (declare (doc-string 4)
@@ -423,8 +423,8 @@ dumped with Emacs).  This is so that any user customizations are
 applied before the defcustom tries to initialize the
 variable (this is due to the way `defvaralias' works).
 
-If provided, WHEN should be a string indicating when the variable
-was first made obsolete, for example a date or a release number.
+WHEN should be a string indicating when the variable was first
+made obsolete, for example a date or a release number.
 
 For the benefit of Customize, if OBSOLETE-NAME has
 any of the following properties, they are copied to
@@ -450,8 +450,8 @@ CURRENT-NAME, if it does not already have them:
 ;; It only really affects M-x describe-face output.
 (defmacro define-obsolete-face-alias (obsolete-face current-face when)
   "Make OBSOLETE-FACE a face alias for CURRENT-FACE and mark it obsolete.
-If provided, WHEN should be a string indicating when the face
-was first made obsolete, for example a date or a release number."
+WHEN should be a string indicating when the face was first made
+obsolete, for example a date or a release number."
   `(progn
      (put ,obsolete-face 'face-alias ,current-face)
      ;; Used by M-x describe-face.
diff --git a/lisp/net/netrc.el b/lisp/net/netrc.el
index 93152f4f2c4..cd351ed7e43 100644
--- a/lisp/net/netrc.el
+++ b/lisp/net/netrc.el
@@ -49,8 +49,8 @@
 (defvar netrc-cache nil)
 
 (defun netrc-parse (&optional file)
-  (interactive "fFile to Parse: ")
   "Parse FILE and return a list of all entries in the file."
+  (interactive "fFile to Parse: ")
   (unless file
     (setq file netrc-file))
   (if (listp file)
diff --git a/lisp/progmodes/project.el b/lisp/progmodes/project.el
index 74c2bf91c41..c96d0a6ee15 100644
--- a/lisp/progmodes/project.el
+++ b/lisp/progmodes/project.el
@@ -175,7 +175,6 @@ subset of the project roots and external roots.
 
 The default implementation uses `find-program'.  PROJECT is used
 to find the list of ignores for each directory."
-  (require 'xref)
   (cl-mapcan
    (lambda (dir)
      (project--files-in-directory dir
@@ -184,6 +183,7 @@ to find the list of ignores for each directory."
 
 (defun project--files-in-directory (dir ignores &optional files)
   (require 'find-dired)
+  (require 'xref)
   (defvar find-name-arg)
   (let ((default-directory dir)
         (command (format "%s %s %s -type f %s -print0"
@@ -425,8 +425,6 @@ DIRS must contain directory names."
 (declare-function grep-read-files "grep")
 (declare-function xref--show-xrefs "xref")
 (declare-function xref--find-ignores-arguments "xref")
-(declare-function xref--regexp-to-extended "xref")
-(declare-function xref--convert-hits "xref")
 
 ;;;###autoload
 (defun project-find-regexp (regexp)
@@ -438,6 +436,7 @@ e.g. entering `ch' is equivalent to `*.[ch]'.  As whitespace
 triggers completion when entering a pattern, including it
 requires quoting, e.g. `\\[quoted-insert]<space>'."
   (interactive (list (project--read-regexp)))
+  (require 'xref)
   (let* ((pr (project-current t))
          (files
           (if (not current-prefix-arg)
@@ -469,6 +468,7 @@ requires quoting, e.g. `\\[quoted-insert]<space>'."
 With \\[universal-argument] prefix, you can specify the file name
 pattern to search for."
   (interactive (list (project--read-regexp)))
+  (require 'xref)
   (let* ((pr (project-current t))
          (files
           (project-files pr (append
@@ -479,51 +479,7 @@ pattern to search for."
      nil)))
 
 (defun project--find-regexp-in-files (regexp files)
-  (pcase-let*
-      ((output (get-buffer-create " *project grep output*"))
-       (`(,grep-re ,file-group ,line-group . ,_) (car grep-regexp-alist))
-       (status nil)
-       (hits nil)
-       (xrefs nil)
-       ;; Support for remote files.  The assumption is that, if the
-       ;; first file is remote, they all are, and on the same host.
-       (dir (file-name-directory (car files)))
-       (remote-id (file-remote-p dir))
-       ;; 'git ls-files' can output broken symlinks.
-       (command (format "xargs -0 grep %s -snHE -e %s"
-                        (if (and case-fold-search
-                                 (isearch-no-upper-case-p regexp t))
-                            "-i"
-                          "")
-                        (shell-quote-argument (xref--regexp-to-extended regexp)))))
-    (when remote-id
-      (setq files (mapcar #'file-local-name files)))
-    (with-current-buffer output
-      (erase-buffer)
-      (with-temp-buffer
-        (insert (mapconcat #'identity files "\0"))
-        (setq default-directory dir)
-        (setq status
-              (project--process-file-region (point-min)
-                                            (point-max)
-                                            shell-file-name
-                                            output
-                                            nil
-                                            shell-command-switch
-                                            command)))
-      (goto-char (point-min))
-      (when (and (/= (point-min) (point-max))
-                 (not (looking-at grep-re))
-                 ;; TODO: Show these matches as well somehow?
-                 (not (looking-at "Binary file .* matches")))
-        (user-error "Search failed with status %d: %s" status
-                    (buffer-substring (point-min) (line-end-position))))
-      (while (re-search-forward grep-re nil t)
-        (push (list (string-to-number (match-string line-group))
-                    (match-string file-group)
-                    (buffer-substring-no-properties (point) (line-end-position)))
-              hits)))
-    (setq xrefs (xref--convert-hits (nreverse hits) regexp))
+  (let ((xrefs (xref-matches-in-files regexp files)))
     (unless xrefs
       (user-error "No matches for: %s" regexp))
     xrefs))
diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index 12f32b1cdf6..1f9e5fd2d4c 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -261,7 +261,7 @@ find a search tool; by default, this uses \"find | grep\" in the
 `project-current' roots."
   (cl-mapcan
    (lambda (dir)
-     (xref-collect-references identifier dir))
+     (xref-references-in-directory identifier dir))
    (let ((pr (project-current t)))
      (append
       (project-roots pr)
@@ -1129,8 +1129,11 @@ and just use etags."
 (declare-function grep-expand-template "grep")
 (defvar ede-minor-mode) ;; ede.el
 
-(defun xref-collect-references (symbol dir)
-  "Collect references to SYMBOL inside DIR.
+;;;###autoload
+(defun xref-references-in-directory (symbol dir)
+  "Find all references to SYMBOL in directory DIR.
+Return a list of xref values.
+
 This function uses the Semantic Symbol Reference API, see
 `semantic-symref-tool-alist' for details on which tools are used,
 and when."
@@ -1158,13 +1161,19 @@ and when."
     (xref--convert-hits (semantic-symref-perform-search inst)
                         (format "\\_<%s\\_>" (regexp-quote symbol)))))
 
+(define-obsolete-function-alias
+  'xref-collect-references
+  #'xref-references-in-directory
+  "27.1")
+
 ;;;###autoload
-(defun xref-collect-matches (regexp files dir ignores)
-  "Collect matches for REGEXP inside FILES in DIR.
+(defun xref-matches-in-directory (regexp files dir ignores)
+  "Find all matches for REGEXP in directory DIR.
+Return a list of xref values.
+Only files matching some of FILES and none of IGNORES are searched.
 FILES is a string with glob patterns separated by spaces.
-IGNORES is a list of glob patterns."
+IGNORES is a list of glob patterns for files to ignore."
   ;; DIR can also be a regular file for now; let's not advertise that.
-  (require 'semantic/fw)
   (grep-compute-defaults)
   (defvar grep-find-template)
   (defvar grep-highlight-matches)
@@ -1204,6 +1213,61 @@ IGNORES is a list of glob patterns."
               hits)))
     (xref--convert-hits (nreverse hits) regexp)))
 
+(define-obsolete-function-alias
+  'xref-collect-matches
+  #'xref-matches-in-directory
+  "27.1")
+
+;;;###autoload
+(defun xref-matches-in-files (regexp files)
+  "Find all matches for REGEXP in FILES.
+Return a list of xref values.
+FILES must be a list of absolute file names."
+  (pcase-let*
+      ((output (get-buffer-create " *project grep output*"))
+       (`(,grep-re ,file-group ,line-group . ,_) (car grep-regexp-alist))
+       (status nil)
+       (hits nil)
+       ;; Support for remote files.  The assumption is that, if the
+       ;; first file is remote, they all are, and on the same host.
+       (dir (file-name-directory (car files)))
+       (remote-id (file-remote-p dir))
+       ;; 'git ls-files' can output broken symlinks.
+       (command (format "xargs -0 grep %s -snHE -e %s"
+                        (if (and case-fold-search
+                                 (isearch-no-upper-case-p regexp t))
+                            "-i"
+                          "")
+                        (shell-quote-argument (xref--regexp-to-extended regexp)))))
+    (when remote-id
+      (setq files (mapcar #'file-local-name files)))
+    (with-current-buffer output
+      (erase-buffer)
+      (with-temp-buffer
+        (insert (mapconcat #'identity files "\0"))
+        (setq default-directory dir)
+        (setq status
+              (project--process-file-region (point-min)
+                                            (point-max)
+                                            shell-file-name
+                                            output
+                                            nil
+                                            shell-command-switch
+                                            command)))
+      (goto-char (point-min))
+      (when (and (/= (point-min) (point-max))
+                 (not (looking-at grep-re))
+                 ;; TODO: Show these matches as well somehow?
+                 (not (looking-at "Binary file .* matches")))
+        (user-error "Search failed with status %d: %s" status
+                    (buffer-substring (point-min) (line-end-position))))
+      (while (re-search-forward grep-re nil t)
+        (push (list (string-to-number (match-string line-group))
+                    (match-string file-group)
+                    (buffer-substring-no-properties (point) (line-end-position)))
+              hits)))
+    (xref--convert-hits (nreverse hits) regexp)))
+
 (defun xref--rgrep-command (regexp files dir ignores)
   (require 'find-dired)      ; for `find-name-arg'
   (defvar grep-find-template)
@@ -1278,11 +1342,11 @@ Such as the current syntax table and the applied syntax properties."
                      (in ?b ?B ?< ?> ?w ?W ?_ ?s ?S))
                     str)))
 
-(defvar xref--last-visiting-buffer nil)
+(defvar xref--last-file-buffer nil)
 (defvar xref--temp-buffer-file-name nil)
 
 (defun xref--convert-hits (hits regexp)
-  (let (xref--last-visiting-buffer
+  (let (xref--last-file-buffer
         (tmp-buffer (generate-new-buffer " *xref-temp*")))
     (unwind-protect
         (cl-mapcan (lambda (hit) (xref--collect-matches hit regexp tmp-buffer))
@@ -1293,7 +1357,7 @@ Such as the current syntax table and the applied syntax properties."
   (pcase-let* ((`(,line ,file ,text) hit)
                (remote-id (file-remote-p default-directory))
                (file (and file (concat remote-id file)))
-               (buf (xref--find-buffer-visiting file))
+               (buf (xref--find-file-buffer file))
                (syntax-needed (xref--regexp-syntax-dependent-p regexp)))
     (if buf
         (with-current-buffer buf
@@ -1349,11 +1413,13 @@ Such as the current syntax table and the applied syntax properties."
               matches)))
     (nreverse matches)))
 
-(defun xref--find-buffer-visiting (file)
-  (unless (equal (car xref--last-visiting-buffer) file)
-    (setq xref--last-visiting-buffer
+(defun xref--find-file-buffer (file)
+  (unless (equal (car xref--last-file-buffer) file)
+    (setq xref--last-file-buffer
+          ;; `find-buffer-visiting' is considerably slower,
+          ;; especially on remote files.
           (cons file (get-file-buffer file))))
-  (cdr xref--last-visiting-buffer))
+  (cdr xref--last-file-buffer))
 
 (provide 'xref)