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

related: vim/vim#17228

fb08192ca7

Co-authored-by: Christian Brabandt <cb@256bit.org>

runtime/doc/options.txt

@@ -6531,7 +6531,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 						*'tagfunc'* *'tfu'*
 'tagfunc' 'tfu'		string	(default "")
 			local to buffer
-	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

runtime/doc/tagsrch.txt

@@ -888,8 +888,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:
@@ -943,15 +943,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")
 
@@ -959,5 +958,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:

runtime/lua/vim/_meta/options.lua

@@ -7037,7 +7037,8 @@ vim.bo.tc = vim.bo.tagcase
 vim.go.tagcase = vim.o.tagcase
 vim.go.tc = vim.go.tagcase
 
---- 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

src/nvim/options.lua

@@ -9182,7 +9182,8 @@ local options = {
       cb = 'did_set_tagfunc',
       defaults = '',
       desc = [=[
-        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

src/nvim/tag.c

@@ -1502,7 +1502,8 @@ static bool 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 *pat, char *buf_ffname)
 {
   const bool use_tfu = ((st->flags & TAG_NO_TAGFUNC) == 0);