docs(#3241): use general nvim_tree.api.highlighted_string

Author: alex-courtis

doc/nvim-tree-lua.txt

@@ -902,9 +902,9 @@ Require and register it during |nvim-tree-setup|:
 Contents of `my-decorator.lua`:
 >lua
   ---@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_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()
 
@@ -928,7 +928,7 @@ Contents of `my-decorator.lua`:
 
   ---Override node icon
   ---@param node nvim_tree.api.Node
-  ---@return nvim_tree.api.decorator.highlighted_string? icon_node
+  ---@return nvim_tree.api.highlighted_string? icon_node
   function MyDecorator:icon_node(node)
     if node.name == "example" then
       return self.my_icon_node
@@ -939,7 +939,7 @@ Contents of `my-decorator.lua`:
 
   ---Return two icons for DecoratorIconPlacement "after"
   ---@param node nvim_tree.api.Node
-  ---@return nvim_tree.api.decorator.highlighted_string[]? icons
+  ---@return nvim_tree.api.highlighted_string[]? icons
   function MyDecorator:icons(node)
     if node.name == "example" then
       return { self.my_icon1, self.my_icon2, }
@@ -3213,7 +3213,64 @@ winid({opts})                                     *nvim_tree.api.tree.winid()*
 
 
 ==============================================================================
-API: Decorator                                       *nvim-tree-api-decorator*
+Class                                                        *nvim-tree-class*
+
+*nvim_tree.Class*
+
+    Fields: ~
+      • {super}      (`Class`)
+      • {new}        (`fun(self: nvim_tree.Class)`) See
+                     |nvim_tree.Class:new()|.
+      • {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:new()                                            *nvim_tree.Class:new()*
+    Default constructor
+
+Class:nop({...})                                       *nvim_tree.Class:nop()*
+
+    Parameters: ~
+      • {...}  (`any`)
+
+
+==============================================================================
+Class: Decorator                                   *nvim-tree-class-decorator*
 
 Highlighting and icons for nodes are provided by Decorators, see
 |nvim-tree-icons-highlighting| for an overview. You may provide your own in
@@ -3263,16 +3320,16 @@ Your class may:
       • {icon_placement}   (`"none"|nvim_tree.config.renderer.icons.placement`)
                            Where to place the icons:
                            |nvim_tree.config.renderer.icons.placement|
-      • {icon_node}        (`fun(self: nvim_tree.api.Decorator, node: nvim_tree.api.Node): nvim_tree.api.decorator.highlighted_string?`)
+      • {icon_node}        (`fun(self: nvim_tree.api.Decorator, node: nvim_tree.api.Node): nvim_tree.api.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[]?`)
+      • {icons}            (`fun(self: nvim_tree.api.Decorator, node: nvim_tree.api.Node): nvim_tree.api.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?)`)
+      • {define_sign}      (`fun(self: nvim_tree.api.Decorator, icon: nvim_tree.api.highlighted_string?)`)
                            See |nvim_tree.api.Decorator:define_sign()|.
 
-*nvim_tree.api.decorator.highlighted_string*
+*nvim_tree.api.highlighted_string*
     Text or glyphs with optional highlight group names to apply to it.
 
     Fields: ~
@@ -3289,8 +3346,7 @@ Decorator:define_sign({icon})          *nvim_tree.api.Decorator:define_sign()*
     return from |nvim_tree.api.Decorator:icons()|
 
     Parameters: ~
-      • {icon}  (`nvim_tree.api.decorator.highlighted_string?`) does nothing
-                if nil
+      • {icon}  (`nvim_tree.api.highlighted_string?`) does nothing if nil
 
                                    *nvim_tree.api.Decorator:highlight_group()*
 Decorator:highlight_group({node})
@@ -3315,8 +3371,7 @@ Decorator:icon_node({node})              *nvim_tree.api.Decorator:icon_node()*
       • {node}  (`nvim_tree.api.Node`)
 
     Return: ~
-        (`nvim_tree.api.decorator.highlighted_string?`) icon `nil` for no
-        override
+        (`nvim_tree.api.highlighted_string?`) icon `nil` for no override
 
 Decorator:icons({node})                      *nvim_tree.api.Decorator:icons()*
     Icons to add to the node as per {icon_placement}
@@ -3327,66 +3382,9 @@ Decorator:icons({node})                      *nvim_tree.api.Decorator:icons()*
       • {node}  (`nvim_tree.api.Node`)
 
     Return: ~
-        (`nvim_tree.api.decorator.highlighted_string[]?`) icons `nil` or empty
-        table for no icons. Only the first glyph of {str} is used when
-        {icon_placement} is `"signcolumn"`
-
-
-==============================================================================
-API: Class                                               *nvim-tree-api-class*
-
-*nvim_tree.Class*
-
-    Fields: ~
-      • {super}      (`Class`)
-      • {new}        (`fun(self: nvim_tree.Class)`) See
-                     |nvim_tree.Class:new()|.
-      • {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:new()                                            *nvim_tree.Class:new()*
-    Default constructor
-
-Class:nop({...})                                       *nvim_tree.Class:nop()*
-
-    Parameters: ~
-      • {...}  (`any`)
+        (`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"`
 
 
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

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

@@ -1,5 +1,7 @@
 ---@meta
 
+---#TODO 3241 maybe rename to UserDecorator
+
 ---@brief
 ---Highlighting and icons for nodes are provided by Decorators, see [nvim-tree-icons-highlighting] for an overview. You may provide your own in addition to the builtin decorators.
 ---
@@ -37,7 +39,7 @@ local Class = require("nvim-tree.classic")
 ---
 ---Text or glyphs with optional highlight group names to apply to it.
 ---
----@class nvim_tree.api.decorator.highlighted_string
+---@class nvim_tree.api.highlighted_string
 ---
 ---One or many glyphs/characters. 
 ---@field str string
@@ -69,7 +71,7 @@ nvim_tree.api.Decorator = Decorator
 ---Abstract, optional to implement.
 ---
 ---@param node nvim_tree.api.Node
----@return nvim_tree.api.decorator.highlighted_string? icon `nil` for no override
+---@return nvim_tree.api.highlighted_string? icon `nil` for no override
 function Decorator:icon_node(node) end
 
 ---
@@ -78,7 +80,7 @@ function Decorator:icon_node(node) end
 ---Abstract, optional to implement.
 ---
 ---@param node nvim_tree.api.Node
----@return nvim_tree.api.decorator.highlighted_string[]? icons `nil` or empty table for no icons. Only the first glyph of {str} is used when {icon_placement} is `"signcolumn"`
+---@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
 
 ---
@@ -95,7 +97,7 @@ function Decorator:highlight_group(node) end
 ---
 ---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.decorator.highlighted_string? does nothing if nil
+---@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/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 nvim_tree.api.decorator.highlighted_string name
+---@return nvim_tree.api.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 nvim_tree.api.decorator.highlighted_string name
+---@return nvim_tree.api.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 nvim_tree.api.decorator.highlighted_string icon
+---@return nvim_tree.api.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 nvim_tree.api.decorator.highlighted_string icon
+---@return nvim_tree.api.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 nvim_tree.api.decorator.highlighted_string icon
+---@return nvim_tree.api.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 nvim_tree.api.decorator.highlighted_string name
+---@return nvim_tree.api.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 nvim_tree.api.decorator.highlighted_string icon
+---@return nvim_tree.api.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 nvim_tree.api.decorator.highlighted_string name
+---@return nvim_tree.api.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 nvim_tree.api.decorator.highlighted_string icon
+---@return nvim_tree.api.highlighted_string icon
 function Node:highlighted_icon_empty()
   return { str = "", hl = {} }
 end
 
 ---Highlighted icon for the node
 ---Empty for base Node
----@return nvim_tree.api.decorator.highlighted_string icon
+---@return nvim_tree.api.highlighted_string icon
 function Node:highlighted_icon()
   return self:highlighted_icon_empty()
 end
 
 ---Empty highlighted name
 ---@protected
----@return nvim_tree.api.decorator.highlighted_string name
+---@return nvim_tree.api.highlighted_string name
 function Node:highlighted_name_empty()
   return { str = "", hl = {} }
 end
 
 ---Highlighted name for the node
 ---Empty for base Node
----@return nvim_tree.api.decorator.highlighted_string name
+---@return nvim_tree.api.highlighted_string name
 function Node:highlighted_name()
   return self:highlighted_name_empty()
 end

lua/nvim-tree/renderer/builder.lua

@@ -106,7 +106,7 @@ function Builder:insert_highlight(groups, start, end_)
 end
 
 ---@private
----@param highlighted_strings nvim_tree.api.decorator.highlighted_string[]
+---@param highlighted_strings nvim_tree.api.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 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 indent_markers nvim_tree.api.highlighted_string[]
+---@param arrows? nvim_tree.api.highlighted_string[]
+---@param icon nvim_tree.api.highlighted_string
+---@param name nvim_tree.api.highlighted_string
 ---@param node table
----@return nvim_tree.api.decorator.highlighted_string[]
+---@return nvim_tree.api.highlighted_string[]
 function Builder:format_line(indent_markers, arrows, icon, name, node)
   local added_len = 0
   local function add_to_end(t1, t2)
@@ -254,8 +254,8 @@ end
 ---A highlight group is always calculated and upserted for the case of highlights changing.
 ---@private
 ---@param node Node
----@return nvim_tree.api.decorator.highlighted_string icon
----@return nvim_tree.api.decorator.highlighted_string name
+---@return nvim_tree.api.highlighted_string icon
+---@return nvim_tree.api.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]]