runtime(doc): clarify the use of 'tagfunc', update a comment in tags.c
Commit:
https://github.com/vim/vim/commit/fb08192ca75344d6467f9e7f9b9e6d4509df308a
Author: Christian Brabandt <c...@256bit.org>
Date: Wed Apr 30 19:31:58 2025 +0200
runtime(doc): clarify the use of 'tagfunc', update a comment in tags.c
related: https://github.com/vim/vim/issues/17228
Signed-off-by: Christian Brabandt <c...@256bit.org>
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index db7370d75..6c60b5896 100644
--- 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 132414368..e6bfe1785 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 @@ 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 ed8d0a80b..b36415c96 100644
--- 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)
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups
"vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to vim_dev+unsubscr...@googlegroups.com.
To view this discussion visit
https://groups.google.com/d/msgid/vim_dev/E1uABUV-00HTqC-Tx%40256bit.org.
