docs: polish example decorator (#3160)

doc/nvim-tree-lua.txt

@@ -2929,43 +2929,71 @@ Decorators may:
 - Set highlight group for the name or icons
 - Override node icon
 
-Specify decorators and their precedence via |nvim-tree.renderer.decorators|
-e.g. defaults with a user decorator class being overridden only by Cut: >lua
-  {
-    "Git",
-    "Open",
-    "Hidden",
-    "Modified",
-    "Bookmark",
-    "Diagnostics",
-    "Copied",
-    MyDecorator,
-    "Cut",
-  }
+Create a `nvim_tree.api.decorator.UserDecorator` class and register it with
+precedence via |nvim-tree.renderer.decorators|
+
+See |nvim-tree-decorator-example|
+
+See `nvim-tree/_meta/api_decorator.lua` for full class documentation.
 
-See `nvim-tree/_meta/api_decorator.lua` for full
-`nvim_tree.api.decorator.UserDecorator` class documentation.
-<
 ==============================================================================
  11.1. DECORATOR EXAMPLE                         *nvim-tree-decorator-example*
+
+A decorator class for nodes named "example", overridind 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
-  ---Create your decorator class
   ---@class (exact) MyDecorator: nvim_tree.api.decorator.UserDecorator
-  ---@field private my_icon nvim_tree.api.HighlightedString
+  ---@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
+  ---@field private my_highlight_group string
   local MyDecorator = require("nvim-tree.api").decorator.UserDecorator:extend()
 
   ---Mandatory constructor  :new()  will be called once per tree render, with no arguments.
   function MyDecorator:new()
-    self.enabled         = true
-    self.highlight_range = "all"
-    self.icon_placement  = "signcolumn"
+    self.enabled            = true
+    self.highlight_range    = "name"
+    self.icon_placement     = "after"
 
-    -- create your icon once, for convenience
-    self.my_icon         = { str = "I", hl = { "MyIcon" } }
+    -- 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 sign only once
+    -- Define the icon signs only once
     -- Only needed if you are using icon_placement = "signcolumn"
-    self:define_sign(self.my_icon)
+    -- self:define_sign(self.my_icon1)
+    -- self:define_sign(self.my_icon2)
   end
 
   ---Override node icon
@@ -2973,33 +3001,35 @@ See `nvim-tree/_meta/api_decorator.lua` for full
   ---@return nvim_tree.api.HighlightedString? icon_node
   function MyDecorator:icon_node(node)
     if node.name == "example" then
-      return self.my_icon
+      return self.my_icon_node
     else
       return nil
     end
   end
 
-  ---Return one icon for DecoratorIconPlacement
+  ---Return two icons for DecoratorIconPlacement "after"
   ---@param node nvim_tree.api.Node
   ---@return nvim_tree.api.HighlightedString[]? icons
   function MyDecorator:icons(node)
     if node.name == "example" then
-      return { self.my_icon }
+      return { self.my_icon1, self.my_icon2, }
     else
       return nil
     end
   end
 
-  ---Exactly one highlight group for DecoratorHighlightRange
+  ---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 "MyHighlight"
+      return self.my_highlight_group
     else
       return nil
     end
   end
+
+  return MyDecorator
 <
 ==============================================================================
  12. OS SPECIFIC RESTRICTIONS                          *nvim-tree-os-specific*