docs(#3241): namespace decorator types

Author: alex-courtis

lua/nvim-tree/_meta/api_decorator.lua

@@ -4,25 +4,25 @@ error("Cannot require a meta file")
 local nvim_tree = { api = { decorator = {} } }
 
 ---Highlight group range as per nvim-tree.renderer.highlight_*
----@alias nvim_tree.api.decorator.HighlightRange "none" | "icon" | "name" | "all"
+---@alias nvim_tree.api.decorator.highlight_range nvim_tree.config.renderer.highlight
 
 ---Icon position as per renderer.icons.*_placement
----@alias nvim_tree.api.decorator.IconPlacement "none" | "before" | "after" | "signcolumn" | "right_align"
+---@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.Name "Git" | "Opened" | "Hidden" | "Modified" | "Bookmarks" | "Diagnostics" | "Copied" | "Cut" | nvim_tree.api.decorator.UserDecorator
+---@alias nvim_tree.api.decorator.types nvim_tree.api.decorator.UserDecorator|"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.HighlightedString
+---@class (exact) nvim_tree.api.decorator.highlighted_string
 ---@field str string
 ---@field hl string[]
 
 ---Custom decorator, see :help nvim-tree-decorators
 ---
 ---@class (exact) nvim_tree.api.decorator.UserDecorator
 ---@field protected enabled boolean
----@field protected highlight_range nvim_tree.api.decorator.HighlightRange
----@field protected icon_placement nvim_tree.api.decorator.IconPlacement
+---@field protected highlight_range nvim_tree.api.decorator.highlight_range
+---@field protected icon_placement nvim_tree.api.decorator.icon_placement
 nvim_tree.api.decorator.UserDecorator = {}
 
 ---Create your decorator class
@@ -37,13 +37,13 @@ function nvim_tree.api.decorator.UserDecorator:new() end
 ---Abstract: optionally implement to set the node's icon
 ---
 ---@param node nvim_tree.api.Node
----@return nvim_tree.api.HighlightedString? icon_node
+---@return nvim_tree.api.decorator.highlighted_string? icon_node
 function nvim_tree.api.decorator.UserDecorator: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.HighlightedString[]? icons
+---@return nvim_tree.api.decorator.highlighted_string[]? icons
 function nvim_tree.api.decorator.UserDecorator:icons(node) end
 
 ---Abstract: optionally implement to provide one highlight group to apply to your highlight_range.
@@ -55,5 +55,5 @@ function nvim_tree.api.decorator.UserDecorator:highlight_group(node) end
 ---Define a sign. This should be called in the constructor.
 ---
 ---@protected
----@param icon nvim_tree.api.HighlightedString?
+---@param icon nvim_tree.api.decorator.highlighted_string?
 function nvim_tree.api.decorator.UserDecorator:define_sign(icon) end

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

@@ -61,6 +61,7 @@ error("Cannot require a meta file")
 ---(default: `true`)
 ---@field symlink_destination? boolean
 ---
+---TODO #3241 add an alias for builtins
 ---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`)
 ---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[]
 ---

lua/nvim-tree/api.lua

@@ -96,10 +96,14 @@ local api = {
 
 
 --
--- Map before-setup implementations, most throw an error notification "nvim-tree setup not called".
+-- Map before-setup function implementations, most throw an error notification "nvim-tree setup not called".
 --
 require("nvim-tree.api.impl.pre")(api)
 
 
+---#TODO 3241
+---Public API classes
+-- api.decorator = require("nvim-tree.api.decorator")
+
 
 return api

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

@@ -254,6 +254,8 @@ local function hydrate_post(api)
   api.map.keymap.current = keymap.get_keymap
 end
 
+---#TODO 3241 hydrate function, for clarity
+
 ---Re-hydrate api
 ---@param api table not properly typed to prevent LSP from referencing implementations
 return function(api)

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

@@ -65,6 +65,8 @@ local function hydrate_pre(api)
   api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]]
 end
 
+---#TODO 3241 hydrate function, for clarity
+
 ---Hydrate api
 ---@param api table not properly typed to prevent LSP from referencing implementations
 return function(api)

lua/nvim-tree/renderer/builder.lua

@@ -14,14 +14,14 @@ local GitDecorator = require("nvim-tree.renderer.decorator.git")
 local HiddenDecorator = require("nvim-tree.renderer.decorator.hidden")
 local ModifiedDecorator = require("nvim-tree.renderer.decorator.modified")
 local OpenDecorator = require("nvim-tree.renderer.decorator.opened")
-local UserDecorator = require("nvim-tree.renderer.decorator.user")
+local UserDecorator = require("nvim-tree.api").decorator.UserDecorator
 
 local pad = require("nvim-tree.renderer.components.padding")
 
----@alias HighlightedString nvim_tree.api.HighlightedString
+---@alias HighlightedString nvim_tree.api.decorator.highlighted_string
 
 -- Builtin Decorators
----@type table<nvim_tree.api.decorator.Name, Decorator>
+---@type table<nvim_tree.api.decorator.types, Decorator>
 local BUILTIN_DECORATORS = {
   Git = GitDecorator,
   Open = OpenDecorator,

lua/nvim-tree/renderer/decorator/git.lua

@@ -3,7 +3,7 @@ local notify = require("nvim-tree.notify")
 local Decorator = require("nvim-tree.renderer.decorator")
 local DirectoryNode = require("nvim-tree.node.directory")
 
----@class (exact) GitHighlightedString: nvim_tree.api.HighlightedString
+---@class (exact) GitHighlightedString: nvim_tree.api.decorator.highlighted_string
 ---@field ord number decreasing priority
 
 ---@alias GitStatusStrings "deleted" | "ignored" | "renamed" | "staged" | "unmerged" | "unstaged" | "untracked"

lua/nvim-tree/renderer/decorator/init.lua

@@ -1,10 +1,12 @@
 local Class = require("nvim-tree.classic")
 
+--- #TODO 3241 split this into abstract interface for API and concrete to return to user
+
 ---Abstract Decorator
 ---@class (exact) Decorator: Class
 ---@field protected enabled boolean
----@field protected highlight_range nvim_tree.api.decorator.HighlightRange
----@field protected icon_placement nvim_tree.api.decorator.IconPlacement
+---@field protected highlight_range nvim_tree.api.decorator.highlight_range
+---@field protected icon_placement nvim_tree.api.decorator.icon_placement
 local Decorator = Class:extend()
 
 ---@class (exact) DecoratorArgs