refactor: rename show_tree => inspect_tree #22474

Problem:
"show" is potentially a new verb that we can avoid (there is already
"open" and "echo"). Even if we can't avoid it, the behavior of
`show_tree` fits well in the "inspect" family of functions: a way for
users to introspect/reflect on the state of Nvim.

Existing "inspect" functions:
    vim.inspect()
    vim.inspect_pos()
    vim.treesitter.inspect_language()
    nvim__inspect_cell

Solution:
Rename `show_tree` to `inspect_tree`.

runtime/doc/news.txt

@@ -89,7 +89,7 @@ The following new APIs or features were added.
 
   See |lsp-semantic_tokens| for more information.
 
-• |vim.treesitter.show_tree()| opens a split window showing a text
+• |vim.treesitter.inspect_tree()| opens a split window showing a text
   representation of the nodes in a language tree for the current buffer.
 
 • Added support for the `willSave` and `willSaveWaitUntil` capabilities to the

runtime/doc/treesitter.txt

@@ -595,6 +595,31 @@ get_string_parser({str}, {lang}, {opts})
     Return: ~
         |LanguageTree| object to use for parsing
 
+inspect_tree({opts})                           *vim.treesitter.inspect_tree()*
+    Open a window that displays a textual representation of the nodes in the
+    language tree.
+
+    While in the window, press "a" to toggle display of anonymous nodes, "I"
+    to toggle the display of the source language of each node, and press
+    <Enter> to jump to the node under the cursor in the source buffer.
+
+    Parameters: ~
+      • {opts}  (table|nil) Optional options table with the following possible
+                keys:
+                • lang (string|nil): The language of the source buffer. If
+                  omitted, the filetype of the source buffer is used.
+                • bufnr (integer|nil): Buffer to draw the tree into. If
+                  omitted, a new buffer is created.
+                • winid (integer|nil): Window id to display the tree buffer
+                  in. If omitted, a new window is created with {command}.
+                • command (string|nil): Vimscript command to create the
+                  window. Default value is "topleft 60vnew". Only used when
+                  {winid} is nil.
+                • title (string|fun(bufnr:integer):string|nil): Title of the
+                  window. If a function, it accepts the buffer number of the
+                  source buffer as its only argument and should return a
+                  string.
+
 is_ancestor({dest}, {source})                   *vim.treesitter.is_ancestor()*
     Determines whether a node is the ancestor of another
 
@@ -627,31 +652,6 @@ node_contains({node}, {range})                *vim.treesitter.node_contains()*
     Return: ~
         (boolean) True if the {node} contains the {range}
 
-show_tree({opts})                                 *vim.treesitter.show_tree()*
-    Open a window that displays a textual representation of the nodes in the
-    language tree.
-
-    While in the window, press "a" to toggle display of anonymous nodes, "I"
-    to toggle the display of the source language of each node, and press
-    <Enter> to jump to the node under the cursor in the source buffer.
-
-    Parameters: ~
-      • {opts}  (table|nil) Optional options table with the following possible
-                keys:
-                • lang (string|nil): The language of the source buffer. If
-                  omitted, the filetype of the source buffer is used.
-                • bufnr (integer|nil): Buffer to draw the tree into. If
-                  omitted, a new buffer is created.
-                • winid (integer|nil): Window id to display the tree buffer
-                  in. If omitted, a new window is created with {command}.
-                • command (string|nil): Vimscript command to create the
-                  window. Default value is "topleft 60vnew". Only used when
-                  {winid} is nil.
-                • title (string|fun(bufnr:integer):string|nil): Title of the
-                  window. If a function, it accepts the buffer number of the
-                  source buffer as its only argument and should return a
-                  string.
-
 start({bufnr}, {lang})                                *vim.treesitter.start()*
     Starts treesitter highlighting for a buffer
 

runtime/lua/vim/treesitter.lua

@@ -436,7 +436,7 @@ end
 ---                      - title (string|fun(bufnr:integer):string|nil): Title of the window. If a
 ---                        function, it accepts the buffer number of the source buffer as its only
 ---                        argument and should return a string.
-function M.show_tree(opts)
+function M.inspect_tree(opts)
   vim.validate({
     opts = { opts, 't', true },
   })
@@ -622,6 +622,12 @@ function M.show_tree(opts)
   })
 end
 
+---@deprecated
+---@private
+function M.show_tree()
+  vim.deprecate('show_tree', 'inspect_tree', '0.9', nil, false)
+end
+
 --- Returns the fold level for {lnum} in the current buffer. Can be set directly to 'foldexpr':
 --- <pre>lua
 --- vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'