refactor(treesitter): deprecate for_each_child #25118

The name for_each_child is misleading and caused bugs.
After #25111, #25115, there are no more usages of `for_each_child` in Nvim.

In the future if we want to restore this functionality we can consider a
generalized vim.traverse(node, key, visitor) function.

runtime/doc/deprecated.txt

@@ -151,6 +151,8 @@ TREESITTER FUNCTIONS
 						and |TSNode:type()| instead.
 - *vim.treesitter.query.get_query()*		Use |vim.treesitter.query.get()|
 						instead.
+- *LanguageTree:for_each_child()*		Use |LanguageTree:children()|
+						(non-recursive) instead.
 
 LUA
 - vim.register_keystroke_callback()	Use |vim.on_key()| instead.

runtime/doc/news.txt

@@ -268,4 +268,7 @@ release.
 
 • `vim.loop` has been renamed to `vim.uv`.
 
+• vim.treesitter.languagetree functions:
+  - |LanguageTree:for_each_child()|	Use |LanguageTree:children()| (non-recursive) instead.
+
  vim:tw=78:ts=8:sw=2:et:ft=help:norl:

runtime/doc/treesitter.txt

@@ -1094,15 +1094,6 @@ LanguageTree:destroy()                                *LanguageTree:destroy()*
     Note: This DOES NOT remove this tree from a parent. Instead,
     `remove_child` must be called on the parent to remove it.
 
-                                               *LanguageTree:for_each_child()*
-LanguageTree:for_each_child({fn}, {include_self})
-    Invokes the callback for each |LanguageTree| and its children recursively
-
-    Parameters: ~
-      • {fn}            fun(tree: LanguageTree, lang: string)
-      • {include_self}  (boolean|nil) Whether to include the invoking tree in
-                        the results
-
 LanguageTree:for_each_tree({fn})                *LanguageTree:for_each_tree()*
     Invokes the callback for each |LanguageTree| recursively.
 

runtime/lua/vim/treesitter/languagetree.lua

@@ -451,11 +451,14 @@ function LanguageTree:parse(range)
   return self._trees
 end
 
+---@deprecated Misleading name. Use `LanguageTree:children()` (non-recursive) instead,
+---            add recursion yourself if needed.
 --- Invokes the callback for each |LanguageTree| and its children recursively
 ---
 ---@param fn fun(tree: LanguageTree, lang: string)
 ---@param include_self boolean|nil Whether to include the invoking tree in the results
 function LanguageTree:for_each_child(fn, include_self)
+  vim.deprecate('LanguageTree:for_each_child()', 'LanguageTree:children()', '0.11')
   if include_self then
     fn(self, self._lang)
   end