docs(#3241): namespace decorator types

Author: alex-courtis

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

@@ -61,7 +61,6 @@ 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

@@ -101,9 +101,9 @@ local api = {
 require("nvim-tree.api.impl.pre")(api)
 
 
----#TODO 3241
----Public API classes
--- api.decorator = require("nvim-tree.api.decorator")
+--#TODO 3241
+--Public API classes
+--api.decorator = require("nvim-tree.api.decorator")
 
 
 return api

lua/nvim-tree/node/directory-link.lua

@@ -38,7 +38,7 @@ function DirectoryLinkNode:update_git_status(parent_ignored, project)
   self.git_status = git_utils.git_status_dir(parent_ignored, project, self.link_to, self.absolute_path)
 end
 
----@return HighlightedString name
+---@return nvim_tree.api.decorator.highlighted_string name
 function DirectoryLinkNode:highlighted_icon()
   if not self.explorer.opts.renderer.icons.show.folder then
     return self:highlighted_icon_empty()
@@ -58,7 +58,7 @@ function DirectoryLinkNode:highlighted_icon()
 end
 
 ---Maybe override name with arrow
----@return HighlightedString name
+---@return nvim_tree.api.decorator.highlighted_string name
 function DirectoryLinkNode:highlighted_name()
   local name = DirectoryNode.highlighted_name(self)
 

lua/nvim-tree/node/directory.lua

@@ -198,7 +198,7 @@ function DirectoryNode:expand_or_collapse(toggle_group)
   self.explorer.renderer:draw()
 end
 
----@return HighlightedString icon
+---@return nvim_tree.api.decorator.highlighted_string icon
 function DirectoryNode:highlighted_icon()
   if not self.explorer.opts.renderer.icons.show.folder then
     return self:highlighted_icon_empty()
@@ -243,7 +243,7 @@ function DirectoryNode:highlighted_icon()
   return { str = str, hl = { hl } }
 end
 
----@return HighlightedString icon
+---@return nvim_tree.api.decorator.highlighted_string icon
 function DirectoryNode:highlighted_name()
   local str, hl
 

lua/nvim-tree/node/file-link.lua

@@ -31,7 +31,7 @@ function FileLinkNode:update_git_status(parent_ignored, project)
   self.git_status = git_utils.git_status_file(parent_ignored, project, self.link_to, self.absolute_path)
 end
 
----@return HighlightedString icon
+---@return nvim_tree.api.decorator.highlighted_string icon
 function FileLinkNode:highlighted_icon()
   if not self.explorer.opts.renderer.icons.show.file then
     return self:highlighted_icon_empty()
@@ -46,7 +46,7 @@ function FileLinkNode:highlighted_icon()
   return { str = str, hl = { hl } }
 end
 
----@return HighlightedString name
+---@return nvim_tree.api.decorator.highlighted_string name
 function FileLinkNode:highlighted_name()
   local str = self.name
   if self.explorer.opts.renderer.symlink_destination then

lua/nvim-tree/node/file.lua

@@ -50,7 +50,7 @@ function FileNode:get_git_xy()
   return self.git_status.file and { self.git_status.file }
 end
 
----@return HighlightedString icon
+---@return nvim_tree.api.decorator.highlighted_string icon
 function FileNode:highlighted_icon()
   if not self.explorer.opts.renderer.icons.show.file then
     return self:highlighted_icon_empty()
@@ -79,7 +79,7 @@ function FileNode:highlighted_icon()
   return { str = str, hl = { hl } }
 end
 
----@return HighlightedString name
+---@return nvim_tree.api.decorator.highlighted_string name
 function FileNode:highlighted_name()
   local hl
   if vim.tbl_contains(self.explorer.opts.renderer.special_files, self.absolute_path) or vim.tbl_contains(self.explorer.opts.renderer.special_files, self.name) then

lua/nvim-tree/node/init.lua

@@ -93,28 +93,28 @@ end
 
 ---Empty highlighted icon
 ---@protected
----@return HighlightedString icon
+---@return nvim_tree.api.decorator.highlighted_string icon
 function Node:highlighted_icon_empty()
   return { str = "", hl = {} }
 end
 
 ---Highlighted icon for the node
 ---Empty for base Node
----@return HighlightedString icon
+---@return nvim_tree.api.decorator.highlighted_string icon
 function Node:highlighted_icon()
   return self:highlighted_icon_empty()
 end
 
 ---Empty highlighted name
 ---@protected
----@return HighlightedString name
+---@return nvim_tree.api.decorator.highlighted_string name
 function Node:highlighted_name_empty()
   return { str = "", hl = {} }
 end
 
 ---Highlighted name for the node
 ---Empty for base Node
----@return HighlightedString name
+---@return nvim_tree.api.decorator.highlighted_string name
 function Node:highlighted_name()
   return self:highlighted_name_empty()
 end

lua/nvim-tree/renderer/builder.lua

@@ -18,7 +18,7 @@ local UserDecorator = require("nvim-tree.api").decorator.UserDecorator
 
 local pad = require("nvim-tree.renderer.components.padding")
 
----@alias HighlightedString nvim_tree.api.decorator.highlighted_string
+---TODO #3241 add an alias for builtins or document the enum
 
 -- Builtin Decorators
 ---@type table<nvim_tree.api.decorator.types, Decorator>
@@ -106,7 +106,7 @@ function Builder:insert_highlight(groups, start, end_)
 end
 
 ---@private
----@param highlighted_strings HighlightedString[]
+---@param highlighted_strings nvim_tree.api.decorator.highlighted_string[]
 ---@return string
 function Builder:unwrap_highlighted_strings(highlighted_strings)
   if not highlighted_strings then
@@ -126,12 +126,12 @@ function Builder:unwrap_highlighted_strings(highlighted_strings)
 end
 
 ---@private
----@param indent_markers HighlightedString[]
----@param arrows HighlightedString[]|nil
----@param icon HighlightedString
----@param name HighlightedString
+---@param indent_markers nvim_tree.api.decorator.highlighted_string[]
+---@param arrows? nvim_tree.api.decorator.highlighted_string[]
+---@param icon nvim_tree.api.decorator.highlighted_string
+---@param name nvim_tree.api.decorator.highlighted_string
 ---@param node table
----@return HighlightedString[]
+---@return nvim_tree.api.decorator.highlighted_string[]
 function Builder:format_line(indent_markers, arrows, icon, name, node)
   local added_len = 0
   local function add_to_end(t1, t2)
@@ -231,8 +231,8 @@ end
 ---A highlight group is always calculated and upserted for the case of highlights changing.
 ---@private
 ---@param node Node
----@return HighlightedString icon
----@return HighlightedString name
+---@return nvim_tree.api.decorator.highlighted_string icon
+---@return nvim_tree.api.decorator.highlighted_string name
 function Builder:icon_name_decorated(node)
   -- use the api node for user decorators
   local api_node = self.api_nodes and self.api_nodes[node.uid_node] --[[@as Node]]

lua/nvim-tree/renderer/components/padding.lua

@@ -64,7 +64,7 @@ end
 ---@param node Node
 ---@param markers table
 ---@param early_stop integer?
----@return HighlightedString
+---@return nvim_tree.api.decorator.highlighted_string
 function M.get_indent_markers(depth, idx, nodes_number, node, markers, early_stop)
   local str = ""
 
@@ -83,7 +83,7 @@ function M.get_indent_markers(depth, idx, nodes_number, node, markers, early_sto
 end
 
 ---@param node Node
----@return HighlightedString[]|nil
+---@return nvim_tree.api.decorator.highlighted_string[]?
 function M.get_arrows(node)
   if not M.config.icons.show.folder_arrow then
     return

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

@@ -2,7 +2,7 @@ local Decorator = require("nvim-tree.renderer.decorator")
 
 ---@class (exact) BookmarkDecorator: Decorator
 ---@field private explorer Explorer
----@field private icon HighlightedString?
+---@field private icon nvim_tree.api.decorator.highlighted_string?
 local BookmarkDecorator = Decorator:extend()
 
 ---@class BookmarkDecorator
@@ -28,7 +28,7 @@ end
 
 ---Bookmark icon: renderer.icons.show.bookmarks and node is marked
 ---@param node Node
----@return HighlightedString[]? icons
+---@return nvim_tree.api.decorator.highlighted_string[]? icons
 function BookmarkDecorator:icons(node)
   if self.explorer.marks:get(node) then
     return { self.icon }