feat(#2948): document API

Author: alex-courtis

lua/nvim-tree/_meta/api_decorator.lua

@@ -1,9 +1,9 @@
 ---@meta
 error("Cannot require a meta file")
 
-local nvim_tree = { api = { decorator = { BaseDecorator = {} } } }
+local nvim_tree = { api = { decorator = { AbstractDecorator = {} } } }
 
----Custom decorator extends nvim_tree.api.decorator.BaseDecorator
+---Custom decorator extends nvim_tree.api.decorator.AbstractDecorator
 ---It may:
 ---  Add icons
 ---  Set name highlight group
@@ -21,60 +21,60 @@ local nvim_tree = { api = { decorator = { BaseDecorator = {} } } }
 ---@alias nvim_tree.api.decorator.IconPlacement "none" | "before" | "after" | "signcolumn" | "right_align"
 
 ---Names of predefined decorators or your decorator classes
----@alias nvim_tree.api.decorator.Name "Cut" | "Copied" | "Diagnostics" | "Bookmarks" | "Modified" | "Hidden" | "Opened" | "Git" | nvim_tree.api.decorator.BaseDecorator
+---@alias nvim_tree.api.decorator.Name "Cut" | "Copied" | "Diagnostics" | "Bookmarks" | "Modified" | "Hidden" | "Opened" | "Git" | nvim_tree.api.decorator.AbstractDecorator
 
----BaseDecorator Class, your decorator will extend this
+---Abstract decorator class, your decorator will extend this
 ---
----@class (exact) nvim_tree.api.decorator.BaseDecorator
+---@class (exact) nvim_tree.api.decorator.AbstractDecorator
 ---@field protected enabled boolean
 ---@field protected highlight_range nvim_tree.api.decorator.HighlightRange
 ---@field protected icon_placement nvim_tree.api.decorator.IconPlacement
 
----No-args constructor must be implemented
+---Abstract no-args constructor must be implemented
 ---
-function nvim_tree.api.decorator.BaseDecorator:new() end
+function nvim_tree.api.decorator.AbstractDecorator:new() end
 
 ---Must be called from your constructor
 ---
----@class (exact) nvim_tree.api.decorator.InitArgs
+---@class (exact) nvim_tree.api.decorator.AbstractDecoratorInitArgs
 ---@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.BaseDecorator:init(args) end
+---@param args nvim_tree.api.decorator.AbstractDecoratorInitArgs
+function nvim_tree.api.decorator.AbstractDecorator:init(args) end
 
----Optionally implement this method to set the node's icon
+---Abstract: optionally implement to set the node's icon
 ---
 ---@param node nvim_tree.api.Node
 ---@return HighlightedString? icon_node
-function nvim_tree.api.decorator.BaseDecorator:icon_node(node) end
+function nvim_tree.api.decorator.AbstractDecorator:icon_node(node) end
 
----Optionally implement this method to provide icons and the highlight groups for your icon_placement
+---Abstract: optionally implement to provide icons and the highlight groups for your icon_placement
 ---
 ---@param node nvim_tree.api.Node
 ---@return HighlightedString[]? icons
-function nvim_tree.api.decorator.BaseDecorator:icons(node) end
+function nvim_tree.api.decorator.AbstractDecorator:icons(node) end
 
----Optionally implement this method to provide one highlight group to apply to your highlight_range
+---Abstract: optionally implement to provide one highlight group to apply to your highlight_range
 ---
 ---@param node nvim_tree.api.Node
 ---@return string? highlight_group
-function nvim_tree.api.decorator.BaseDecorator:highlight_group(node) end
+function nvim_tree.api.decorator.AbstractDecorator:highlight_group(node) end
 
 
 --
 -- Example Decorator
 --
 
----@class (exact) MyDecorator: nvim_tree.api.decorator.BaseDecorator
+---@class (exact) MyDecorator: nvim_tree.api.decorator.AbstractDecorator
 ---@field private my_icon nvim_tree.api.HighlightedString
 local MyDecorator = require("nvim-tree.api").decorator.create()
 
 ---Mandatory constructor  :new()  will be called once per tree render, with no arguments.
 function MyDecorator:new()
-  ---@type nvim_tree.api.decorator.InitArgs
+  ---@type nvim_tree.api.decorator.AbstractDecoratorInitArgs
   local args = {
     enabled         = true,
     highlight_range = "all",

lua/nvim-tree/api.lua

@@ -316,13 +316,13 @@ end)
 
 ---Create a new decorator class
 ---
----@return nvim_tree.api.decorator.BaseDecorator
+---@return nvim_tree.api.decorator.AbstractDecorator
 Api.decorator.create = function() return DecoratorUser:extend() end
 
 ---Register a decorator class
 ---
 ---@class RegisterOpts
----@field decorator nvim_tree.api.decorator.BaseDecorator
+---@field decorator nvim_tree.api.decorator.AbstractDecorator
 ---@field below nvim_tree.api.decorator.Name?
 ---
 ---@param opts RegisterOpts
@@ -331,7 +331,7 @@ Api.decorator.register = function(opts) decorator_registry.register(opts) end
 ---Unregister a decorator class
 ---
 ---@class UnRegisterOpts
----@field decorator nvim_tree.api.decorator.BaseDecorator
+---@field decorator nvim_tree.api.decorator.AbstractDecorator
 ---
 ---@param opts UnRegisterOpts
 Api.decorator.unregister = function(opts) decorator_registry.unregister(opts) end

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

@@ -1,11 +1,11 @@
 local Decorator = require("nvim-tree.renderer.decorator")
 
----Exposed as nvim_tree.api.decorator.BaseDecorator
+---Exposed as nvim_tree.api.decorator.AbstractDecorator
 ---@class (exact) DecoratorUser: Decorator
 local DecoratorUser = Decorator:extend()
 
 ---User calls this instead of new
----@param args nvim_tree.api.decorator.InitArgs
+---@param args nvim_tree.api.decorator.AbstractDecoratorInitArgs
 function DecoratorUser:init(args)
   DecoratorUser.super.new(self, args)
 end