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 db7370d..6c60b58 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -8521,7 +8521,8 @@
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 1324143..e6bfe17 100644
--- 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 @@
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 @@
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 @@
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: