feat(#2948): tidy decorator args and complete documentation

Author: alex-courtis

doc/nvim-tree-lua.txt

@@ -52,14 +52,15 @@ CONTENTS                                                           *nvim-tree*
   8.2  Highlight: Overhaul                      |nvim-tree-highlight-overhaul|
   9. Events                                   |nvim-tree-events|
  10. Prompts                                  |nvim-tree-prompts|
- 11. OS Specific Restrictions                 |nvim-tree-os-specific|
- 12. Netrw                                    |nvim-tree-netrw|
- 13. Legacy                                   |nvim-tree-legacy|
- 13.1  Legacy: Opts                             |nvim-tree-legacy-opts|
- 13.2  Legacy: Highlight                        |nvim-tree-legacy-highlight|
- 14. Index                                    |nvim-tree-index|
- 14.1  Index: Opts                              |nvim-tree-index-opts|
- 14.2  Index: API                               |nvim-tree-index-api|
+ 11. Decorators                               |nvim-tree-decorators|
+ 12. OS Specific Restrictions                 |nvim-tree-os-specific|
+ 13. Netrw                                    |nvim-tree-netrw|
+ 14. Legacy                                   |nvim-tree-legacy|
+ 14.1  Legacy: Opts                             |nvim-tree-legacy-opts|
+ 14.2  Legacy: Highlight                        |nvim-tree-legacy-highlight|
+ 15. Index                                    |nvim-tree-index|
+ 15.1  Index: Opts                              |nvim-tree-index-opts|
+ 15.2  Index: API                               |nvim-tree-index-api|
 
 ==============================================================================
  1. INTRODUCTION                                      *nvim-tree-introduction*
@@ -843,9 +844,6 @@ Use nvim-tree in a floating window.
 ==============================================================================
  5.3 OPTS: RENDERER                                  *nvim-tree-opts-renderer*
 
-Highlight precedence, additive, change via |nvim-tree.renderer.decorators|
-  git < opened < modified < bookmarked < diagnostics < copied < cut
-
 *nvim-tree.renderer.add_trailing*
 Appends a trailing slash to folder names.
   Type: `boolean`, Default: `false`
@@ -1013,9 +1011,6 @@ Configuration options for tree indent markers.
 *nvim-tree.renderer.icons*
 Configuration options for icons.
 
-Icon order and sign column precedence, change via |nvim-tree.renderer.decorators|
-  git < hidden < modified < bookmarked < diagnostics
-
 `renderer.icons.*_placement` options may be:
 - `"before"` : before file/folder, after the file/folders icons
 - `"after"` : after file/folder
@@ -2772,7 +2767,90 @@ configurations for different types of prompts.
     send all bookmarked to trash during |nvim-tree-api.marks.bulk.trash()|
 
 ==============================================================================
- 11. OS SPECIFIC RESTRICTIONS                          *nvim-tree-os-specific*
+ 11. DECORATORS                                         *nvim-tree-decorators*
+
+Highlighting and icons for nodes are is provided by Decorators. You may provide
+your own in addition to the builtin decorators.
+
+Decorators may:
+- Add icons
+- Set highlight group for the name or icons
+- Override node icon
+
+Create your decorator class via `api.decorator.DecoratorUser:extend()` and add it
+to |nvim-tree.renderer.decorators|
+
+e.g. default decorators with an user decorator being overridden only by Cut: >lua
+  {
+    "Git",
+    "Opened",
+    "Hidden",
+    "Modified",
+    "Bookmarks",
+    "Diagnostics",
+    "Copied",
+    MyDecorator,
+    "Cut",
+  }
+<
+See `api_decorator.lua` for decorator class definition and full documentation.
+
+Example decorator: >lua
+
+  ---Create your decorator class
+  ---@class (exact) MyDecorator: nvim_tree.api.decorator.DecoratorUser
+  ---@field private my_icon nvim_tree.api.HighlightedString
+  local MyDecorator = require("nvim-tree.api").decorator.DecoratorUser: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"
+
+    -- create your icon once, for convenience
+    self.my_icon         = { str = "I", hl = { "MyIcon" } }
+
+    -- Define the icon sign only once
+    -- Only needed if you are using icon_placement = "signcolumn"
+    self:define_sign(self.my_icon)
+  end
+
+  ---Override node icon
+  ---@param node nvim_tree.api.Node
+  ---@return nvim_tree.api.HighlightedString? icon_node
+  function MyDecorator:icon_node(node)
+    if node.name == "example" then
+      return self.my_icon
+    else
+      return nil
+    end
+  end
+
+  ---Return one icon for DecoratorIconPlacement
+  ---@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 }
+    else
+      return nil
+    end
+  end
+
+  ---Exactly one highlight group for DecoratorHighlightRange
+  ---@param node nvim_tree.api.Node
+  ---@return string? highlight_group
+  function MyDecorator:highlight_group(node)
+    if node.name == "example" then
+      return "MyHighlight"
+    else
+      return nil
+    end
+  end
+<
+==============================================================================
+ 12. OS SPECIFIC RESTRICTIONS                          *nvim-tree-os-specific*
 
 Windows WSL and PowerShell
 - Trash is synchronized
@@ -2784,7 +2862,7 @@ Windows WSL and PowerShell
   issues or disable this feature.
 
 ==============================================================================
- 12. NETRW                                                   *nvim-tree-netrw*
+ 13. NETRW                                                   *nvim-tree-netrw*
 
 |netrw| is a standard neovim plugin that is enabled by default. It provides,
 amongst other functionality, a file/directory browser.
@@ -2805,14 +2883,14 @@ keep using |netrw| without its browser features please ensure:
 |nvim-tree.hijack_netrw| ` = true`
 
 ==============================================================================
- 13. LEGACY                                                 *nvim-tree-legacy*
+ 14. LEGACY                                                 *nvim-tree-legacy*
 
 Breaking refactors have been made however the legacy versions will be silently
 migrated and used.
 There are no plans to remove this migration.
 
 ==============================================================================
- 13.1 LEGACY: OPTS                                     *nvim-tree-legacy-opts*
+ 14.1 LEGACY: OPTS                                     *nvim-tree-legacy-opts*
 
 Legacy options are translated to the current, making type and value changes as
 needed.
@@ -2830,7 +2908,7 @@ needed.
 `renderer.icons.webdev_colors`       |nvim-tree.renderer.icons.web_devicons.file.color|
 
 ==============================================================================
- 13.2 LEGACY: HIGHLIGHT                           *nvim-tree-legacy-highlight*
+ 14.2 LEGACY: HIGHLIGHT                           *nvim-tree-legacy-highlight*
 
 Legacy highlight group are still obeyed when they are defined and the current
 highlight group is not, hard linking as follows: >
@@ -2879,10 +2957,10 @@ highlight group is not, hard linking as follows: >
     NvimTreeLspDiagnosticsHintFolderText        NvimTreeDiagnosticHintFolderHL
 <
 ==============================================================================
- 14 INDEX                                                    *nvim-tree-index*
+ 15 INDEX                                                    *nvim-tree-index*
 
 ==============================================================================
- 14.1 INDEX: OPTS                                       *nvim-tree-index-opts*
+ 15.1 INDEX: OPTS                                       *nvim-tree-index-opts*
 
 |nvim-tree.actions.change_dir|
 |nvim-tree.actions.change_dir.enable|
@@ -3051,7 +3129,7 @@ highlight group is not, hard linking as follows: >
 |nvim-tree.view.width.padding|
 
 ==============================================================================
- 14.2 INDEX: API                                         *nvim-tree-index-api*
+ 15.2 INDEX: API                                         *nvim-tree-index-api*
 
 |nvim-tree-api.commands.get()|
 |nvim-tree-api.config.mappings.default_on_attach()|

lua/nvim-tree/_meta/aliases.lua

@@ -1,19 +1,7 @@
 ---@meta
 error("Cannot require a meta file")
 
-local nvim_tree = { api = { decorator = { DecoratorUser = {} } } }
-
----Custom decorator
----It may:
----  Add icons
----  Set highlight group for the name or icons
----  Override node icon
----Register it via  :help nvim-tree.renderer.decorators
----Create class via require("nvim-tree.api").decorator.DecoratorUser:extend()
----Mandatory constructor  :new()  will be called once per tree render, with no arguments.
----Constructor must call:
----  :init
----  :define_sign when using "signcolumn" range
+local nvim_tree = {}
 
 ---Highlight group range as per nvim-tree.renderer.highlight_*
 ---@alias nvim_tree.api.decorator.HighlightRange "none" | "icon" | "name" | "all"
@@ -24,27 +12,28 @@ local nvim_tree = { api = { decorator = { DecoratorUser = {} } } }
 ---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.DecoratorUser
 
----Your decorator will extend this class via require("nvim-tree.api").decorator.DecoratorUser:extend()
+---Custom decorator, see :help nvim-tree-decorators
 ---
 ---@class (exact) nvim_tree.api.decorator.DecoratorUser
 ---@field protected enabled boolean
 ---@field protected highlight_range nvim_tree.api.decorator.HighlightRange
 ---@field protected icon_placement nvim_tree.api.decorator.IconPlacement
 
----Abstract: no-args constructor must be implemented.
+---Abstract: no-args constructor must be implemented and will be called once per tree render.
+---Must set all fields.
 ---
 function nvim_tree.api.decorator.DecoratorUser:new() end
 
 ---Abstract: optionally implement to set the node's icon
 ---
 ---@param node nvim_tree.api.Node
----@return HighlightedString? icon_node
+---@return nvim_tree.api.HighlightedString? icon_node
 function nvim_tree.api.decorator.DecoratorUser: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 HighlightedString[]? icons
+---@return nvim_tree.api.HighlightedString[]? icons
 function nvim_tree.api.decorator.DecoratorUser:icons(node) end
 
 ---Abstract: optionally implement to provide one highlight group to apply to your highlight_range.
@@ -53,81 +42,8 @@ function nvim_tree.api.decorator.DecoratorUser:icons(node) end
 ---@return string? highlight_group
 function nvim_tree.api.decorator.DecoratorUser:highlight_group(node) end
 
----Must be called from your constructor.
----
----@class (exact) nvim_tree.api.decorator.InitArgs
----@field enabled boolean
----@field highlight_range nvim_tree.api.decorator.HighlightRange
----@field icon_placement nvim_tree.api.decorator.IconPlacement
----
----@protected
----@param args nvim_tree.api.decorator.InitArgs
-function nvim_tree.api.decorator.DecoratorUser:init(args) end
-
 ---Define a sign. This should be called in the constructor.
 ---
 ---@protected
----@param icon HighlightedString?
+---@param icon nvim_tree.api.HighlightedString?
 function nvim_tree.api.decorator.DecoratorUser:define_sign(icon) end
-
-
---
--- Example Decorator
---
-
----@class (exact) MyDecorator: nvim_tree.api.decorator.DecoratorUser
----@field private my_icon nvim_tree.api.HighlightedString
-local MyDecorator = require("nvim-tree.api").decorator.DecoratorUser:extend()
-
----Mandatory constructor  :new()  will be called once per tree render, with no arguments.
-function MyDecorator:new()
-  ---@type nvim_tree.api.decorator.InitArgs
-  local args = {
-    enabled         = true,
-    highlight_range = "all",
-    icon_placement  = "signcolumn",
-  }
-
-  -- init
-  self:init(args)
-
-  -- create your icon once, for convenience
-  self.my_icon = { str = "I", hl = { "MyIcon" } }
-
-  -- Define the icon sign only once
-  -- Only needed if you are using icon_placement = "signcolumn"
-  self:define_sign(self.my_icon)
-end
-
----Override node icon
----@param node nvim_tree.api.Node
----@return nvim_tree.api.HighlightedString? icon_node
-function MyDecorator:icon_node(node)
-  if node.name == "example" then
-    return self.my_icon
-  else
-    return nil
-  end
-end
-
----Return one icon for DecoratorIconPlacement
----@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 }
-  else
-    return nil
-  end
-end
-
----Exactly one highlight group for DecoratorHighlightRange
----@param node nvim_tree.api.Node
----@return string? highlight_group
-function MyDecorator:highlight_group(node)
-  if node.name == "example" then
-    return "MyHighlight"
-  else
-    return nil
-  end
-end

lua/nvim-tree/_meta/api_decorator.lua

@@ -313,7 +313,7 @@ Api.commands.get = wrap(function()
   return require("nvim-tree.commands").get()
 end)
 
----User provided decorator. Extend this class via :extend()
+---Create a decorator class by calling :extend()
 ---@type nvim_tree.api.decorator.DecoratorUser
 Api.decorator.DecoratorUser = DecoratorUser --[[@as nvim_tree.api.decorator.DecoratorUser]]
 

lua/nvim-tree/api.lua

@@ -18,6 +18,8 @@ local DecoratorUser = require("nvim-tree.renderer.decorator.user")
 
 local pad = require("nvim-tree.renderer.components.padding")
 
+---@alias HighlightedString nvim_tree.api.HighlightedString
+
 -- Builtin Decorators
 ---@type table<nvim_tree.api.decorator.Name, Decorator>
 local BUILTIN_DECORATORS = {

lua/nvim-tree/renderer/builder.lua

@@ -11,16 +11,11 @@ local DecoratorBookmarks = Decorator:extend()
 ---@protected
 ---@param args DecoratorArgs
 function DecoratorBookmarks:new(args)
-  self.explorer = args.explorer
+  self.explorer        = args.explorer
 
-  ---@type AbstractDecoratorArgs
-  local a = {
-    enabled         = true,
-    highlight_range = self.explorer.opts.renderer.highlight_bookmarks or "none",
-    icon_placement  = self.explorer.opts.renderer.icons.bookmarks_placement or "none",
-  }
-
-  DecoratorBookmarks.super.new(self, a)
+  self.enabled         = true
+  self.highlight_range = self.explorer.opts.renderer.highlight_bookmarks or "none"
+  self.icon_placement  = self.explorer.opts.renderer.icons.bookmarks_placement or "none"
 
   if self.explorer.opts.renderer.icons.show.bookmarks then
     self.icon = {