docs(#3088): move api help and classes back into api.lua

Author: alex-courtis

lua/nvim-tree/_meta/api.lua

@@ -0,0 +1,43 @@
+---@meta
+error("Cannot require a meta file")
+
+
+-- These node subclasses are not ready for public exposure as they are:
+-- - not classic classes
+-- - only used in a few locations: api.tree.get_nodes and UserDecorator
+
+---
+---File
+---
+---@class (exact) nvim_tree.api.FileNode: nvim_tree.api.Node
+---@field extension string
+
+---
+---Directory
+---
+---@class (exact) nvim_tree.api.DirectoryNode: nvim_tree.api.Node
+---@field has_children boolean
+---@field nodes nvim_tree.api.Node[]
+---@field open boolean
+
+---
+---Root Directory
+---
+---@class (exact) nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode
+
+---
+---Link mixin
+---
+---@class (exact) nvim_tree.api.LinkNode
+---@field link_to string
+---@field fs_stat_target uv.fs_stat.result
+
+---
+---File Link
+---
+---@class (exact) nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode
+
+---
+---DirectoryLink
+---
+---@class (exact) nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode

lua/nvim-tree/_meta/classes.lua

@@ -1,5 +1,75 @@
 local api = {}
 
+---@brief
+---nvim-tree exposes a public API. This is non breaking, with additions made as necessary.
+---
+---Please do not require or use modules other than `nvim-tree.api`, as internal modules will change without notice.
+---
+---The API is separated into multiple modules:
+---
+---- [nvim-tree-api-commands]
+---- [nvim-tree-api-events]
+---- [nvim-tree-api-filter]
+---- [nvim-tree-api-fs]
+---- [nvim-tree-api-health]
+---- [nvim-tree-api-map]
+---- [nvim-tree-api-marks]
+---- [nvim-tree-api-node]
+---- [nvim-tree-api-tree]
+---
+---Modules are accessed via `api.<module>.<function>`
+---
+---Example invocation of the `reload` function in the `tree` module:
+---```lua
+---
+---local api = require("nvim-tree.api")
+---api.tree.reload()
+---```
+---Generally, functions accepting a [nvim_tree.api.Node] as their first argument will use the node under the cursor when that argument is not present or nil. e.g. the following are functionally identical:
+---```lua
+---
+---api.node.open.edit(nil, { focus = true })
+---
+---api.node.open.edit(api.tree.get_node_under_cursor(), { focus = true })
+---```
+
+
+
+---The Node class is a data class. Instances may be provided by API functions for use as a:
+---- handle to pass back to API functions e.g. [nvim_tree.api.node.run.cmd()]
+---- reference in callbacks e.g. [nvim_tree.config.sort.Sorter] {sorter}
+---
+---Please do not mutate the contents of any Node object.
+---
+---@class nvim_tree.api.Node
+---@field absolute_path string of the file or directory
+---@field name string file or directory name
+---@field parent? nvim_tree.api.DirectoryNode parent directory, nil for root
+---@field type "file" | "directory" | "link" [uv.fs_stat()] {type}
+---@field executable boolean file is executable
+---@field fs_stat? uv.fs_stat.result at time of last tree display, see [uv.fs_stat()]
+---@field git_status nvim_tree.git.Status? for files and directories
+---@field diag_severity? lsp.DiagnosticSeverity diagnostic status
+---@field hidden boolean node is not visible in the tree
+
+
+
+---
+---Git statuses for a single node.
+---
+---`nvim_tree.git.XY`: 2 character string, see `man 1 git-status` "Short Format"
+---@alias nvim_tree.git.XY string
+---
+---{dir} status is derived from its contents:
+---- `direct`: inherited from child files
+---- `indirect`: inherited from child directories
+---
+---@class nvim_tree.git.Status
+---@field file? nvim_tree.git.XY status of a file node
+---@field dir? table<"direct" | "indirect", nvim_tree.git.XY[]> direct inclusive-or indirect status
+
+
+
 --
 -- Load the (empty) meta definitions
 --
@@ -13,9 +83,13 @@ api.marks = require("nvim-tree._meta.api.marks")
 api.node = require("nvim-tree._meta.api.node")
 api.tree = require("nvim-tree._meta.api.tree")
 
+
+
 --
--- Map implementations
+-- Map before-setup implementations, most throw an error notification "nvim-tree setup not called".
 --
 require("nvim-tree.api.impl.pre")(api)
 
+
+
 return api

lua/nvim-tree/api.lua

@@ -1,3 +1,11 @@
+---Hydrates all API functions with concrete implementations.
+---All "nvim-tree setup not called" error functions from pre.lua will be replaced.
+---
+---Call this after nvim-tree setup
+---
+---This is expensive as there are many cascading requires and is avoided
+---until after setup has been called, so that the user may require API cheaply.
+
 local view = require("nvim-tree.view")
 local actions = require("nvim-tree.actions")
 
@@ -243,13 +251,7 @@ local function hydrate_post(api)
   api.map.get_keymap = function() require("nvim-tree.keymap").get_keymap() end
 end
 
----Hydrates all API functions with concrete implementations.
----All "nvim-tree setup not called" error functions will be replaced.
----
----Call this after nvim-tree setup
----
----This is expensive as there are many cascading requires and is avoided
----until after setup has been called, so that the user may require API cheaply.
+---Re-hydrate api
 ---@param api table
 return function(api)
   -- All concrete implementations

lua/nvim-tree/api/impl/post.lua

@@ -1,4 +1,11 @@
+--Hydrates meta api empty definition functions with a new function:
+-- - Default: error notification "nvim-tree setup not called".
+-- - Exceptions: concrete implementation for API that can be called before setup.
+--
+--Call it once when api is first required
+--
 --This file should have minimal requires that are cheap and have no dependencies or are already required.
+--
 --Everything must be as lazily loaded as possible: the user must be able to require api cheaply.
 
 local commands = require("nvim-tree.commands") -- already required by plugin.lua
@@ -58,10 +65,7 @@ local function hydrate_pre(api)
   api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]]
 end
 
---Hydrates meta api empty definition functions with a new function:
--- - Default: error notification "nvim-tree setup not called".
--- - Exceptions: concrete implementation for API that can be called before setup.
---Call it once when api is first required
+---Hydrate api
 ---@param api table
 return function(api)
   -- Default: error

lua/nvim-tree/api/impl/pre.lua

@@ -38,7 +38,7 @@ local srcs = {
 
   { helptag = "nvim-tree-config-default",             section = "Config: Default",             path = "./lua/nvim_tree/_meta/config/default.lua", },
 
-  { helptag = "nvim-tree-api",                        section = "API",                         path = "./lua/nvim_tree/_meta/api.lua", },
+  { helptag = "nvim-tree-api",                        section = "API",                         path = "./lua/nvim_tree/api.lua", },
 
   { helptag = "nvim-tree-api-commands",               section = "API: commands",               path = "./lua/nvim_tree/_meta/api/commands.lua", },
   { helptag = "nvim-tree-api-events",                 section = "API: events",                 path = "./lua/nvim_tree/_meta/api/events.lua", },