docs: treesitter.add_directive, add_predicate #21206

3 files changed, 32 insertions, 18 deletions

diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 096cec6678..917863eef8 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -708,8 +708,15 @@ add_directive({name}, {handler}, {force})
 
     Parameters: ~
       • {name}     (string) Name of the directive, without leading #
-      • {handler}  function(match:string, pattern:string, bufnr:number,
-                   predicate:function, metadata:table)
+      • {handler}  function(match:table, pattern:string, bufnr:number,
+                   predicate:string[], metadata:table)
+                   • match: see |treesitter-query|
+                     • node-level data are accessible via `match[capture_id]`
+
+                   • pattern: see |treesitter-query|
+                   • predicate: list of strings containing the full directive
+                     being called, e.g. `(node (#set! conceal "-"))` would get
+                     the predicate `{ "#set!", "conceal", "-" }`
 
                                         *vim.treesitter.query.add_predicate()*
 add_predicate({name}, {handler}, {force})
@@ -717,8 +724,10 @@ add_predicate({name}, {handler}, {force})
 
     Parameters: ~
       • {name}     (string) Name of the predicate, without leading #
-      • {handler}  function(match:string, pattern:string, bufnr:number,
-                   predicate:function)
+      • {handler}  function(match:table, pattern:string, bufnr:number,
+                   predicate:string[])
+                   • see |vim.treesitter.query.add_directive()| for argument
+                     meanings
 
                                         *vim.treesitter.query.get_node_text()*
 get_node_text({node}, {source}, {opts})
diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua
index 4bec5db527..dbf134573d 100644
--- a/runtime/lua/vim/treesitter/query.lua
+++ b/runtime/lua/vim/treesitter/query.lua
@@ -419,7 +419,8 @@ local directive_handlers = {
 --- Adds a new predicate to be used in queries
 ---
 ---@param name string Name of the predicate, without leading #
----@param handler function(match:string, pattern:string, bufnr:number, predicate:function)
+---@param handler function(match:table, pattern:string, bufnr:number, predicate:string[])
+---   - see |vim.treesitter.query.add_directive()| for argument meanings
 function M.add_predicate(name, handler, force)
   if predicate_handlers[name] and not force then
     error(string.format('Overriding %s', name))
@@ -436,7 +437,12 @@ end
 --- metadata table `metadata[capture_id].key = value`
 ---
 ---@param name string Name of the directive, without leading #
----@param handler function(match:string, pattern:string, bufnr:number, predicate:function, metadata:table)
+---@param handler function(match:table, pattern:string, bufnr:number, predicate:string[], metadata:table)
+---   - match: see |treesitter-query|
+---      - node-level data are accessible via `match[capture_id]`
+---   - pattern: see |treesitter-query|
+---   - predicate: list of strings containing the full directive being called, e.g.
+---     `(node (#set! conceal "-"))` would get the predicate `{ "#set!", "conceal", "-" }`
 function M.add_directive(name, handler, force)
   if directive_handlers[name] and not force then
     error(string.format('Overriding %s', name))
diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua
index fa7c14eaa3..2563f2f410 100644
--- a/scripts/gen_help_html.lua
+++ b/scripts/gen_help_html.lua
@@ -60,19 +60,18 @@ local exclude_invalid = {
   ["'previewpopup'"] = "quickref.txt",
   ["'pvp'"] = "quickref.txt",
   ["'string'"] = "eval.txt",
-  Query = "treesitter.txt",
-  ["eq?"] = "treesitter.txt",
-  ["lsp-request"] = "lsp.txt",
-  matchit = "vim_diff.txt",
-  ["matchit.txt"] = "help.txt",
+  Query = 'treesitter.txt',
+  ['eq?'] = 'treesitter.txt',
+  ['lsp-request'] = 'lsp.txt',
+  matchit = 'vim_diff.txt',
+  ['matchit.txt'] = 'help.txt',
   ["set!"] = "treesitter.txt",
-  ["v:_null_blob"] = "builtin.txt",
-  ["v:_null_dict"] = "builtin.txt",
-  ["v:_null_list"] = "builtin.txt",
-  ["v:_null_string"] = "builtin.txt",
-  ["vim.lsp.buf_request()"] = "lsp.txt",
-  ["vim.lsp.util.get_progress_messages()"] = "lsp.txt",
-  ["vim.treesitter.start()"] = "treesitter.txt",
+  ['v:_null_blob'] = 'builtin.txt',
+  ['v:_null_dict'] = 'builtin.txt',
+  ['v:_null_list'] = 'builtin.txt',
+  ['v:_null_string'] = 'builtin.txt',
+  ['vim.lsp.buf_request()'] = 'lsp.txt',
+  ['vim.lsp.util.get_progress_messages()'] = 'lsp.txt',
 }
 
 -- False-positive "invalid URLs".