emacs-29 a4a9ffdd80a: Fix the documentation of various aspects of adding Xref history

[Eli Zaretskii]

branch: emacs-29
commit a4a9ffdd80a2b8ccd2e6705887d3cae0876a50ab
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Fix the documentation of various aspects of adding Xref history
    
    * lisp/progmodes/xref.el (xref-marker-ring-length)
    (xref-set-marker-ring-length):
    * lisp/progmodes/etags.el (tags-location-ring-length)
    (find-tag-marker-ring): Add doc strings saying the variables are
    unused.
    
    * etc/NEWS: Enhance the description of the change which made Xref
    marker stack unlimited in its length.
    
    * doc/emacs/maintaining.texi (Looking Up Identifiers): Add back
    text lost when xref forward history was added in bug#38797.
    Explain the difference between 'C-M-,' and 'M-.'.  Improve
    wording (Bug#62229)
---
 doc/emacs/maintaining.texi | 19 ++++++++++++++-----
 etc/NEWS                   | 12 ++++++++++--
 lisp/progmodes/etags.el    | 10 +++++++---
 lisp/progmodes/xref.el     | 14 +++++++++-----
 4 files changed, 40 insertions(+), 15 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index f5bbc4d65c0..7d49e28d11f 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -2283,16 +2283,25 @@ buffer, but doesn't select any of them.
 
 @kindex M-,
 @findex xref-go-back
-  To go back to places @emph{from where} you've displayed the definition,
-use @kbd{M-,} (@code{xref-go-back}).  It jumps back to the
+  To go back to places @emph{from where} you've displayed the
+definition, use @kbd{M-,} (@code{xref-go-back}).  It jumps back to the
 point of the last invocation of @kbd{M-.}.  Thus you can find and
 examine the definition of something with @kbd{M-.} and then return to
-where you were with @kbd{M-,}.
+where you were with @kbd{M-,}.  @kbd{M-,} allows you to retrace the
+steps you made forward in the history of places, all the way to the
+first place in history, where you first invoked @kbd{M-.}, or to any
+place in-between.
 
 @kindex C-M-,
 @findex xref-go-forward
-  If you previously went back too far with @kbd{M-,}, @kbd{C-M-,}
-(@code{xref-go-forward}) can be used to go forward again.
+  If you previously went back too far with @kbd{M-,}, or want to
+re-examine a place from which you went back, you can use @kbd{C-M-,}
+(@code{xref-go-forward}) to go forward again.  This is similar to
+using @kbd{M-.}, except that you don't need on each step to move point
+to the identifier whose definition you want to look up.  @kbd{C-M-,}
+allows you to retrace all the steps you made back in the history of
+places, all the way to the last place in history, where you invoked
+@kbd{M-,}, or to any place in-between.
 
 @findex xref-etags-mode
   Some major modes install @code{xref} support facilities that might
diff --git a/etc/NEWS b/etc/NEWS
index a5f9f8c6ec1..0b651f7a519 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2540,8 +2540,16 @@ the project by a VC project based on that VCS.
 
 +++
 *** New command 'xref-go-forward'.
-It is bound to 'C-M-,' and jumps to the location where 'xref-go-back'
-('M-,', also known as 'xref-pop-marker-stack') was invoked previously.
+It is bound to 'C-M-,' and jumps to the location where you previously
+invoked 'xref-go-back' ('M-,', also known as 'xref-pop-marker-stack').
+
++++
+*** The depth of the Xref marker stack is now infinite.
+The implementation of the Xref marker stack was changed in a way that
+allows as many places to be saved on the stack as needed, limited only
+by the available memory.  Therefore, the variables
+'find-tag-marker-ring-length' and 'xref-marker-ring-length' are now
+obsolete and unused; setting them has no effect.
 
 +++
 *** 'xref-query-replace-in-results' prompting change.
diff --git a/lisp/progmodes/etags.el b/lisp/progmodes/etags.el
index 8efdae6060f..cb95f29b5fe 100644
--- a/lisp/progmodes/etags.el
+++ b/lisp/progmodes/etags.el
@@ -146,7 +146,10 @@ Otherwise, `find-tag-default' is used."
 (define-obsolete-variable-alias 'find-tag-marker-ring-length
   'tags-location-ring-length "25.1")
 
-(defvar tags-location-ring-length 16)
+(defvar tags-location-ring-length 16
+  "Size of the find-tag marker ring.
+This variable has no effect, and is kept only for backward compatibility.
+The actual size of the find-tag marker ring is unlimited.")
 
 (defcustom tags-tag-face 'default
   "Face for tags in the output of `tags-apropos'."
@@ -181,8 +184,9 @@ Example value:
                       (sexp :tag "Tags to search")))
   :version "21.1")
 
-;; Obsolete variable kept for compatibility. We don't use it in any way.
-(defvar find-tag-marker-ring (make-ring 16))
+(defvar find-tag-marker-ring (make-ring 16)
+  "Find-tag marker ring.
+Obsolete variable kept for compatibility.  It is not used in any way.")
 (make-obsolete-variable
  'find-tag-marker-ring
  "use `xref-push-marker-stack' or `xref-go-back' instead."
diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index d4e34f7e55a..ee4253960c5 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -355,8 +355,10 @@ backward."
           (t (goto-char start) nil))))
 
 
-;; Dummy variable retained for compatibility.
-(defvar xref-marker-ring-length 16)
+(defvar xref-marker-ring-length 16
+  "Xref marker ring length.
+This is a dummy variable retained for backward compatibility, and
+otherwise unused.")
 (make-obsolete-variable 'xref-marker-ring-length nil "29.1")
 
 (defcustom xref-prompt-for-identifier '(not xref-find-definitions
@@ -453,7 +455,9 @@ are predefined:
 (make-obsolete-variable 'xref--marker-ring 'xref--history "29.1")
 
 (defun xref-set-marker-ring-length (_var _val)
-  (declare (obsolete nil "29.1"))
+  (declare (obsolete
+            "this function has no effect: Xref marker ring is now unlimited in 
size"
+            "29.1"))
   nil)
 
 (defun xref--make-xref-history ()
@@ -499,7 +503,7 @@ Override existing value with NEW-VALUE if NEW-VALUE is set."
 
 (defun xref-push-marker-stack (&optional m)
   "Add point M (defaults to `point-marker') to the marker stack.
-The future stack is erased."
+Erase the stack slots following this one."
   (xref--push-backward (or m (point-marker)))
   (let ((history (xref--get-history)))
     (dolist (mk (cdr history))
@@ -527,7 +531,7 @@ To undo, use \\[xref-go-forward]."
 
 ;;;###autoload
 (defun xref-go-forward ()
-  "Got to the point where a previous \\[xref-go-back] was invoked."
+  "Go to the point where a previous \\[xref-go-back] was invoked."
   (interactive)
   (let ((history (xref--get-history)))
     (if (null (cdr history))