docs(#3241): api.Decorator help documentation is generated

doc/nvim-tree-lua.txt

@@ -890,53 +890,53 @@ Require and register it during |nvim-tree-setup|:
 <
 Contents of `my-decorator.lua`:
 >lua
-  ---@class (exact) MyDecorator: nvim_tree.api.decorator.UserDecorator
-  ---@field private my_icon1 nvim_tree.api.HighlightedString
-  ---@field private my_icon2 nvim_tree.api.HighlightedString
-  ---@field private my_icon_node nvim_tree.api.HighlightedString
+  ---@class (exact) MyDecorator: nvim_tree.api.Decorator
+  ---@field private my_icon1 nvim_tree.api.decorator.highlighted_string
+  ---@field private my_icon2 nvim_tree.api.decorator.highlighted_string
+  ---@field private my_icon_node nvim_tree.api.decorator.highlighted_string
   ---@field private my_highlight_group string
-  local MyDecorator = require("nvim-tree.api").decorator.UserDecorator:extend()
-
+  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.HighlightedString? icon_node
+  ---@return nvim_tree.api.decorator.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.HighlightedString[]? icons
+  ---@return nvim_tree.api.decorator.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
@@ -947,7 +947,7 @@ Contents of `my-decorator.lua`:
       return nil
     end
   end
-
+  
   return MyDecorator
 <
 ==============================================================================
@@ -1366,7 +1366,7 @@ Config: renderer                                   *nvim-tree-config-renderer*
       • {symlink_destination}?     (`boolean`, default: `true`) Appends an
                                    arrow followed by the target of the
                                    symlink.
-      • {decorators}?              (`(string|nvim_tree.api.decorator.UserDecorator)[]`)
+      • {decorators}?              (`(string|nvim_tree.api.Decorator)[]`)
                                    (default:
                                    `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`)
       • {highlight_git}?           (`nvim_tree.config.renderer.highlight`)
@@ -3200,4 +3200,115 @@ winid({opts})                                     *nvim_tree.api.tree.winid()*
         (`integer?`) |window-ID|, nil if tree is not visible.
 
 
+==============================================================================
+API: Decorator                                       *nvim-tree-api-decorator*
+
+*nvim_tree.api.Decorator*
+    Extends: |nvim_tree.Class|
+
+    Abstract Decorator interface
+
+    Fields: ~
+      • {enabled}          (`boolean`)
+      • {highlight_range}  (`nvim_tree.api.decorator.highlight_range`)
+      • {icon_placement}   (`nvim_tree.api.decorator.icon_placement`)
+      • {icon_node}        (`fun(self: nvim_tree.api.Decorator, node: nvim_tree.api.Node): nvim_tree.api.decorator.highlighted_string?`)
+                           See |nvim_tree.api.Decorator:icon_node()|.
+      • {icons}            (`fun(self: nvim_tree.api.Decorator, node: nvim_tree.api.Node): nvim_tree.api.decorator.highlighted_string[]?`)
+                           See |nvim_tree.api.Decorator:icons()|.
+      • {highlight_group}  (`fun(self: nvim_tree.api.Decorator, node: nvim_tree.api.Node): string?`)
+                           See |nvim_tree.api.Decorator:highlight_group()|.
+      • {define_sign}      (`fun(self: nvim_tree.api.Decorator, icon: nvim_tree.api.decorator.highlighted_string?)`)
+                           See |nvim_tree.api.Decorator:define_sign()|.
+
+
+Decorator:define_sign({icon})          *nvim_tree.api.Decorator:define_sign()*
+    Defines a sign. This should be called in the constructor.
+
+    Parameters: ~
+      • {icon}  (`nvim_tree.api.decorator.highlighted_string?`)
+
+                                   *nvim_tree.api.Decorator:highlight_group()*
+Decorator:highlight_group({node})
+    Abstract: optionally implement to provide one highlight group to apply to
+    your highlight_range.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+    Return: ~
+        (`string?`) highlight_group
+
+Decorator:icon_node({node})              *nvim_tree.api.Decorator:icon_node()*
+    Abstract: optionally implement to set the node's icon
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+    Return: ~
+        (`nvim_tree.api.decorator.highlighted_string?`) icon_node
+
+Decorator:icons({node})                      *nvim_tree.api.Decorator:icons()*
+    Abstract: optionally implement to provide icons and the highlight groups
+    for your icon_placement.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+    Return: ~
+        (`nvim_tree.api.decorator.highlighted_string[]?`) icons
+
+
+==============================================================================
+API: Class                                               *nvim-tree-api-class*
+
+*nvim_tree.Class*
+
+    Fields: ~
+      • {super}      (`Class`)
+      • {extend}     (`fun(self: nvim_tree.Class)`) See
+                     |nvim_tree.Class:extend()|.
+      • {implement}  (`fun(self: nvim_tree.Class, mixin: Class)`) See
+                     |nvim_tree.Class:implement()|.
+      • {is}         (`fun(self: nvim_tree.Class, class: T): boolean`) See
+                     |nvim_tree.Class:is()|.
+      • {as}         (`fun(self: nvim_tree.Class, class: T): T?`) See
+                     |nvim_tree.Class:as()|.
+      • {nop}        (`fun(self: nvim_tree.Class, ...: any)`) See
+                     |nvim_tree.Class:nop()|.
+
+
+Class:as({class})                                       *nvim_tree.Class:as()*
+    Return object if |nvim_tree.Class:is()| otherwise nil
+
+    Parameters: ~
+      • {class}  (`any`)
+
+    Return: ~
+        (`T?`)
+
+Class:extend()                                      *nvim_tree.Class:extend()*
+    Extend a class, setting .super
+
+Class:implement({mixin})                         *nvim_tree.Class:implement()*
+    Implement the functions of a mixin Add the mixin to .implements
+
+    Parameters: ~
+      • {mixin}  (`Class`)
+
+Class:is({class})                                       *nvim_tree.Class:is()*
+    Object is an instance of class or implements a mixin
+
+    Parameters: ~
+      • {class}  (`any`)
+
+    Return: ~
+        (`boolean`)
+
+Class:nop({...})                                       *nvim_tree.Class:nop()*
+
+    Parameters: ~
+      • {...}  (`any`)
+
+
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

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,64 @@
+---@meta
+local nvim_tree = { api = {} }
+
+local Class = require("nvim-tree.classic")
+
+---
+---Highlight group range as per nvim-tree.renderer.highlight_*
+---
+---@alias nvim_tree.api.decorator.highlight_range nvim_tree.config.renderer.highlight
+
+---Icon position as per renderer.icons.*_placement
+---
+---@alias nvim_tree.api.decorator.icon_placement "none"|nvim_tree.config.renderer.icons.placement
+
+---
+---Names of builtin decorators or your decorator classes. Builtins are ordered lowest to highest priority.
+---
+---@alias nvim_tree.api.decorator.types nvim_tree.api.Decorator|"Git"|"Opened"|"Hidden"|"Modified"|"Bookmarks"|"Diagnostics"|"Copied"|"Cut"
+
+---
+---A string for rendering, with optional highlight groups to apply to it
+---
+---@class (exact) nvim_tree.api.decorator.highlighted_string
+---@field str string
+---@field hl string[]
+
+---
+---Abstract Decorator interface
+---
+---@class nvim_tree.api.Decorator: nvim_tree.Class
+---@field enabled boolean
+---@field highlight_range nvim_tree.api.decorator.highlight_range
+---@field icon_placement nvim_tree.api.decorator.icon_placement
+local Decorator = Class:extend()
+nvim_tree.api.Decorator = Decorator
+
+---
+---Abstract: optionally implement to set the node's icon
+---
+---@param node nvim_tree.api.Node
+---@return nvim_tree.api.decorator.highlighted_string? icon_node
+function Decorator:icon_node(node) end
+
+---
+---Abstract: optionally implement to provide icons and the highlight groups for your icon_placement.
+---
+---@param node nvim_tree.api.Node
+---@return nvim_tree.api.decorator.highlighted_string[]? icons
+function Decorator:icons(node) end
+
+---
+---Abstract: optionally implement to provide one highlight group to apply to your highlight_range.
+---
+---@param node nvim_tree.api.Node
+---@return string? highlight_group
+function Decorator:highlight_group(node) end
+
+---
+---Defines a sign. This should be called in the constructor.
+---
+---@param icon nvim_tree.api.decorator.highlighted_string?
+function Decorator:define_sign(icon) end
+
+return nvim_tree.api.Decorator

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/config/default.lua

@@ -8,4 +8,3 @@
 ---default-config-injection-placeholder
 ---}
 ---```
----

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

@@ -62,7 +62,7 @@ error("Cannot require a meta file")
 ---@field symlink_destination? boolean
 ---
 ---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`)
----@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[]
+---@field decorators? (string|nvim_tree.api.Decorator)[]
 ---
 ---(default: `"none"`)
 ---@field highlight_git? nvim_tree.config.renderer.highlight

lua/nvim-tree/api.lua

@@ -69,12 +69,9 @@
 
 
 
---
--- Load the (empty) meta definitions
---
-local deprecated = require("nvim-tree._meta.api.deprecated")
-
+---
 ---nvim-tree Public API
+---
 ---@class nvim_tree.api
 ---@nodoc
 local api = {
@@ -89,17 +86,14 @@ local api = {
   node = require("nvim-tree._meta.api.node"),
   tree = require("nvim-tree._meta.api.tree"),
 
-  config = deprecated.config, ---@deprecated
-  diagnostics = deprecated.diagnostics, ---@deprecated
-  live_filter = deprecated.live_filter, ---@deprecated
-}
-
-
---
--- Map before-setup implementations, most throw an error notification "nvim-tree setup not called".
---
-require("nvim-tree.api.impl.pre")(api)
+  Decorator = require("nvim-tree._meta.api.decorator"),
 
+  config = require("nvim-tree._meta.api.deprecated").config, ---@deprecated
+  decorator = require("nvim-tree._meta.api.deprecated").decorator, ---@deprecated
+  diagnostics = require("nvim-tree._meta.api.deprecated").diagnostics, ---@deprecated
+  live_filter = require("nvim-tree._meta.api.deprecated").live_filter, ---@deprecated
+}
 
+require("nvim-tree.api.impl.pre").hydrate(api)
 
 return api