docs(#3241): add api.Decorator and Class meta with generated help, harden decorator rendering, api.decorator.UserDecorator changed to nvim_tree.api.Decorator in a non-breaking manner

lua/nvim-tree.lua

@@ -813,7 +813,7 @@ function M.setup(conf)
   vim.g.NvimTreeSetup = 1
   vim.api.nvim_exec_autocmds("User", { pattern = "NvimTreeSetup" })
 
-  require("nvim-tree.api.impl.post")(api)
+  require("nvim-tree.api.impl.post").hydrate(api)
 end
 
 vim.g.NvimTreeRequired = 1

lua/nvim-tree/_meta/api/decorator.lua

@@ -0,0 +1,103 @@
+---@meta
+
+---@brief
+---Highlighting and icons for nodes are provided by Decorators, see [nvim-tree-icons-highlighting] for an overview.
+---
+---Decorators are rendered in [nvim_tree.config.renderer] {decorators} order of additive precedence, with later decorators applying additively over earlier.
+---
+---You may provide your own in addition to the builtin decorators, see |nvim-tree-class-decorator-example|.
+---
+---Decorators may:
+---- Add icons
+---- Set a highlight group name for the name or icons
+---- Override node icon
+---
+---To register your decorator:
+---- Create a class that extends [nvim_tree.api.Decorator]
+---- Register it by adding the class to [nvim_tree.config.renderer] {decorators}
+---
+---Your decorator will be constructed and executed each time the tree is rendered.
+---
+---Your class must:
+---- [nvim_tree.Class:extend()] the interface [nvim_tree.api.Decorator]
+---- Provide a no-arguments constructor [nvim_tree.Class:new()] that sets the mandatory fields:
+---   - {enabled}
+---   - {highlight_range}
+---   - {icon_placement}
+---- Call [nvim_tree.api.Decorator:define_sign()] in your constructor when {icon_placement} is `"signcolumn"`
+---
+---Your class may:
+---- Implement methods to provide decorations:
+---   - [nvim_tree.api.Decorator:highlight_group()]
+---   - [nvim_tree.api.Decorator:icon_node()]
+---   - [nvim_tree.api.Decorator:icons()]
+
+local nvim_tree = { api = {} }
+
+local Class = require("nvim-tree.classic")
+
+---
+---Text or glyphs with optional highlight group names to apply to it.
+---
+---@class nvim_tree.api.highlighted_string
+---
+---One or many glyphs/characters. 
+---@field str string
+---
+---Highlight group names to apply in order. Empty table for no highlighting.
+---@field hl string[]
+
+
+---
+---Decorator interface
+---
+---@class nvim_tree.api.Decorator: nvim_tree.Class
+---
+---Enable this decorator.
+---@field enabled boolean
+---
+---What to highlight: [nvim_tree.config.renderer.highlight]
+---@field highlight_range nvim_tree.config.renderer.highlight
+---
+---Where to place the icons: [nvim_tree.config.renderer.icons.placement]
+---@field icon_placement "none"|nvim_tree.config.renderer.icons.placement
+---
+local Decorator = Class:extend()
+nvim_tree.api.Decorator = Decorator
+
+---
+---Icon to override for the node.
+---
+---Abstract, optional to implement.
+---
+---@param node nvim_tree.api.Node
+---@return nvim_tree.api.highlighted_string? icon `nil` for no override
+function Decorator:icon_node(node) end
+
+---
+---Icons to add to the node as per {icon_placement}
+---
+---Abstract, optional to implement.
+---
+---@param node nvim_tree.api.Node
+---@return nvim_tree.api.highlighted_string[]? icons `nil` or empty table for no icons. Only the first glyph of {str} is used when {icon_placement} is `"signcolumn"`
+function Decorator:icons(node) end
+
+---
+---One highlight group that applies additively to the {node} name for {highlight_range}.
+---
+---Abstract, optional to implement.
+---
+---@param node nvim_tree.api.Node
+---@return string? highlight group name `nil` when no highlighting to apply to the node
+function Decorator:highlight_group(node) end
+
+---
+---Defines a sign for an icon. This is mandatory and necessary only when {icon_placement} is `"signcolumn"`
+---
+---This must be called during your constructor for all icons that you will return from [nvim_tree.api.Decorator:icons()]
+---
+---@param icon nvim_tree.api.highlighted_string? does nothing if nil
+function Decorator:define_sign(icon) end
+
+return nvim_tree.api.Decorator

lua/nvim-tree/_meta/api/decorator_example.lua

@@ -0,0 +1,96 @@
+---@meta
+error("Cannot require a meta file")
+
+---@brief
+---
+---A decorator class for nodes named "example", overriding all builtin decorators except for Cut.
+---- Highlights node name with `IncSearch`
+---- Creates two icons `"1"` and `"2"` placed after the node name, highlighted with `DiffAdd` and `DiffText`
+---- Replaces the node icon with `"N"`, highlighted with `Error `
+---
+---Create a class file `~/.config/nvim/lua/my-decorator.lua`
+---
+---Require and register it during |nvim-tree-setup|:
+---```lua
+---
+--- local MyDecorator = require("my-decorator")
+--- 
+--- require("nvim-tree").setup({
+---   renderer = {
+---     decorators = {
+---       "Git",
+---       "Open",
+---       "Hidden",
+---       "Modified",
+---       "Bookmark",
+---       "Diagnostics",
+---       "Copied",
+---       MyDecorator,
+---       "Cut",
+---     },
+---   },
+--- })
+---```
+---Contents of `my-decorator.lua`:
+---```lua
+---
+--- ---@class (exact) MyDecorator: nvim_tree.api.Decorator
+--- ---@field private my_icon1 nvim_tree.api.highlighted_string
+--- ---@field private my_icon2 nvim_tree.api.highlighted_string
+--- ---@field private my_icon_node nvim_tree.api.highlighted_string
+--- ---@field private my_highlight_group string
+--- local MyDecorator = require("nvim-tree.api").Decorator:extend()
+--- 
+--- ---Mandatory constructor  :new()  will be called once per tree render, with no arguments.
+--- function MyDecorator:new()
+---   self.enabled            = true
+---   self.highlight_range    = "name"
+---   self.icon_placement     = "after"
+--- 
+---   -- create your icons and highlights once, applied to every node
+---   self.my_icon1           = { str = "1", hl = { "DiffAdd" } }
+---   self.my_icon2           = { str = "2", hl = { "DiffText" } }
+---   self.my_icon_node       = { str = "N", hl = { "Error" } }
+---   self.my_highlight_group = "IncSearch"
+--- 
+---   -- Define the icon signs only once
+---   -- Only needed if you are using icon_placement = "signcolumn"
+---   -- self:define_sign(self.my_icon1)
+---   -- self:define_sign(self.my_icon2)
+--- end
+--- 
+--- ---Override node icon
+--- ---@param node nvim_tree.api.Node
+--- ---@return nvim_tree.api.highlighted_string? icon_node
+--- function MyDecorator:icon_node(node)
+---   if node.name == "example" then
+---     return self.my_icon_node
+---   else
+---     return nil
+---   end
+--- end
+--- 
+--- ---Return two icons for DecoratorIconPlacement "after"
+--- ---@param node nvim_tree.api.Node
+--- ---@return nvim_tree.api.highlighted_string[]? icons
+--- function MyDecorator:icons(node)
+---   if node.name == "example" then
+---     return { self.my_icon1, self.my_icon2, }
+---   else
+---     return nil
+---   end
+--- end
+--- 
+--- ---Exactly one highlight group for DecoratorHighlightRange "name"
+--- ---@param node nvim_tree.api.Node
+--- ---@return string? highlight_group
+--- function MyDecorator:highlight_group(node)
+---   if node.name == "example" then
+---     return self.my_highlight_group
+---   else
+---     return nil
+---   end
+--- end
+--- 
+--- return MyDecorator
+---```

lua/nvim-tree/_meta/api/deprecated.lua

@@ -30,4 +30,10 @@ nvim_tree.api.diagnostics = {}
 ---@deprecated use `nvim_tree.api.health.hi_test()`
 function nvim_tree.api.diagnostics.hi_test() end
 
+nvim_tree.api.decorator = {}
+
+---@class nvim_tree.api.decorator.UserDecorator: nvim_tree.api.Decorator
+---@deprecated use `nvim_tree.api.Decorator`
+nvim_tree.api.decorator.UserDecorator = nvim_tree.api.Decorator
+
 return nvim_tree.api

lua/nvim-tree/_meta/classes.lua

@@ -1,12 +1,6 @@
 ---@meta
 error("Cannot require a meta file")
 
-
--- TODO #2688
--- 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
 ---

lua/nvim-tree/_meta/config/actions.lua

@@ -60,13 +60,13 @@ error("Cannot require a meta file")
 ---
 ---{open_win_config} is passed to [nvim_open_win()], default:
 ---```lua
----{
----  col = 1,
----  row = 1,
----  relative = "cursor",
----  border = "shadow",
----  style = "minimal",
----}
+--- {
+---   col = 1,
+---   row = 1,
+---   relative = "cursor",
+---   border = "shadow",
+---   style = "minimal",
+--- }
 ---```
 ---You shouldn't define {width} and {height} values here. They will be overridden to fit the file_popup content.
 ---@class nvim_tree.config.actions.file_popup

lua/nvim-tree/_meta/config/default.lua

@@ -3,9 +3,8 @@
 ---
 ---```lua
 ---
-------@type nvim_tree.config
----local config = {
----default-config-injection-placeholder
----}
+--- ---@type nvim_tree.config
+--- local config = {
+--- default-config-injection-placeholder
+--- }
 ---```
----