runtime(doc): clarify the use of 'tagfunc', update a comment in tags.c

related: #17228

Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index db7370d75443ef05887db121a886d0ef52d4dc40..6c60b5896815b580775963e1c984411d790e556d 100644 (file)
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -8521,7 +8521,8 @@ A jump table for the options with a short description can be found at |Q_op|.
                        local to buffer
                        {not available when compiled without the |+eval|
                        feature}
-       This option specifies a function to be used to perform tag searches.
+       This option specifies a function to be used to perform tag searches
+       (including |taglist()|).
        The function gets the tag pattern and should return a List of matching
        tags.  See |tag-function| for an explanation of how to write the
        function and an example.  The value can be the name of a function, a

diff --git a/runtime/doc/tagsrch.txt b/runtime/doc/tagsrch.txt
index 132414368a26d2eb7d275a0de729c29f14988cbe..e6bfe17856eeb4b0acd890742fd9958dd8f28ac4 100644 (file)
--- a/runtime/doc/tagsrch.txt
+++ b/runtime/doc/tagsrch.txt
@@ -1,4 +1,4 @@
-*tagsrch.txt*   For Vim version 9.1.  Last change: 2025 Apr 26
+*tagsrch.txt*   For Vim version 9.1.  Last change: 2025 Apr 30
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -894,8 +894,8 @@ Common arguments for the commands above:
 7. Using 'tagfunc'                                             *tag-function*
 
 It is possible to provide Vim with a function which will generate a list of
-tags used for commands like |:tag|, |:tselect| and Normal mode tag commands
-like |CTRL-]|.
+tags used for commands like |:tag|, |:tselect|, Normal mode tag commands like
+|CTRL-]| and for the |taglist()| function.
 
 The function used for generating the taglist is specified by setting the
 'tagfunc' option.  The function will be called with three arguments:
@@ -950,15 +950,14 @@ It is not allowed to close a window or change window from inside 'tagfunc'.
 The following is a hypothetical example of a function used for 'tagfunc'.  It
 uses the output of |taglist()| to generate the result: a list of tags in the
 inverse order of file names.
->
-       function TagFunc(pattern, flags, info)
-         function CompareFilenames(item1, item2)
-           let f1 = a:item1['filename']
-           let f2 = a:item2['filename']
-           return f1 >=# f2 ?
-                       \ -1 : f1 <=# f2 ? 1 : 0
-         endfunction
+>vim
+       function CompareFilenames(item1, item2)
+         let f1 = a:item1['filename']
+         let f2 = a:item2['filename']
+         return f1 >=# f2 ? -1 : f1 <=# f2 ? 1 : 0
+       endfunction
 
+       function TagFunc(pattern, flags, info)
          let result = taglist(a:pattern)
          call sort(result, "CompareFilenames")
 
@@ -966,5 +965,7 @@ inverse order of file names.
        endfunc
        set tagfunc=TagFunc
 <
+Note: When executing |taglist()| the 'tagfunc' function won't be called
+recursively.
 
  vim:tw=78:ts=8:noet:ft=help:norl:

diff --git a/src/tag.c b/src/tag.c
index ed8d0a80b39e2e495676b0bdecc059cb60a5839d..b36415c960f5044d4d1d94423a3fc8178a8e7203 100644 (file)
--- a/src/tag.c
+++ b/src/tag.c
@@ -1835,7 +1835,8 @@ findtags_in_help_init(findtags_state_T *st)
  * Use the function set in 'tagfunc' (if configured and enabled) to get the
  * tags.
  * Return OK if at least 1 tag has been successfully found, NOTDONE if the
- * 'tagfunc' is not used or the 'tagfunc' returns v:null and FAIL otherwise.
+ * 'tagfunc' is not used, still executing or the 'tagfunc' returned v:null and
+ * FAIL otherwise.
  */
     static int
 findtags_apply_tfu(findtags_state_T *st, char_u *pat, char_u *buf_ffname)