docs(#3241): generate decorator help

Author: alex-courtis

doc/nvim-tree-lua.txt

@@ -2362,9 +2362,6 @@ Following is the default configuration, see |nvim_tree.config| for details. >lua
       },
     }
 <
-
-
-
 ==============================================================================
 API                                                            *nvim-tree-api*
 
@@ -3200,4 +3197,120 @@ winid({opts})                                     *nvim_tree.api.tree.winid()*
         (`integer?`) |window-ID|, nil if tree is not visible.
 
 
+==============================================================================
+API: Decorator                                       *nvim-tree-api-decorator*
+
+*nvim_tree.api.decorator.Decorator*
+    Extends: |nvim_tree.Class|
+
+    Abstract Decorator interface
+
+    Fields: ~
+      • {enabled}          (`boolean`)
+      • {highlight_range}  (`nvim_tree.api.decorator.highlight_range`)
+      • {icon_placement}   (`nvim_tree.api.decorator.icon_placement`)
+      • {icon_node}        (`fun(self: nvim_tree.api.decorator.Decorator, node: nvim_tree.api.Node): nvim_tree.api.decorator.highlighted_string?`)
+                           See
+                           |nvim_tree.api.decorator.Decorator:icon_node()|.
+      • {icons}            (`fun(self: nvim_tree.api.decorator.Decorator, node: nvim_tree.api.Node): nvim_tree.api.decorator.highlighted_string[]?`)
+                           See |nvim_tree.api.decorator.Decorator:icons()|.
+      • {highlight_group}  (`fun(self: nvim_tree.api.decorator.Decorator, node: nvim_tree.api.Node): string?`)
+                           See
+                           |nvim_tree.api.decorator.Decorator:highlight_group()|.
+      • {define_sign}      (`fun(self: nvim_tree.api.decorator.Decorator, icon: nvim_tree.api.decorator.highlighted_string?)`)
+                           See
+                           |nvim_tree.api.decorator.Decorator:define_sign()|.
+
+
+                             *nvim_tree.api.decorator.Decorator:define_sign()*
+Decorator:define_sign({icon})
+    Defines a sign. This should be called in the constructor.
+
+    Parameters: ~
+      • {icon}  (`nvim_tree.api.decorator.highlighted_string?`)
+
+                         *nvim_tree.api.decorator.Decorator:highlight_group()*
+Decorator:highlight_group({node})
+    Abstract: optionally implement to provide one highlight group to apply to
+    your highlight_range.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+    Return: ~
+        (`string?`) highlight_group
+
+                               *nvim_tree.api.decorator.Decorator:icon_node()*
+Decorator:icon_node({node})
+    Abstract: optionally implement to set the node's icon
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+    Return: ~
+        (`nvim_tree.api.decorator.highlighted_string?`) icon_node
+
+Decorator:icons({node})            *nvim_tree.api.decorator.Decorator:icons()*
+    Abstract: optionally implement to provide icons and the highlight groups
+    for your icon_placement.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+    Return: ~
+        (`nvim_tree.api.decorator.highlighted_string[]?`) icons
+
+
+==============================================================================
+API: Class                                               *nvim-tree-api-class*
+
+*nvim_tree.Class*
+
+    Fields: ~
+      • {super}      (`Class`)
+      • {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 :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:nop({...})                                       *nvim_tree.Class:nop()*
+
+    Parameters: ~
+      • {...}  (`any`)
+
+
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

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

@@ -1,57 +1,71 @@
 ---@meta
----
 local nvim_tree = { api = { decorator = {} } }
 
 local Class = require("nvim-tree.classic")
 
+---
 ---Highlight group range as per nvim-tree.renderer.highlight_*
+---
 ---@alias nvim_tree.api.decorator.highlight_range nvim_tree.config.renderer.highlight
 
 ---Icon position as per renderer.icons.*_placement
+---
 ---@alias nvim_tree.api.decorator.icon_placement "none"|nvim_tree.config.renderer.icons.placement
 
+---
 ---Names of builtin decorators or your decorator classes. Builtins are ordered lowest to highest priority.
+---
 ---@alias nvim_tree.api.decorator.types nvim_tree.api.decorator.Decorator|"Git"|"Opened"|"Hidden"|"Modified"|"Bookmarks"|"Diagnostics"|"Copied"|"Cut"
 
+---
 ---A string for rendering, with optional highlight groups to apply to it
+---
 ---@class (exact) nvim_tree.api.decorator.highlighted_string
 ---@field str string
 ---@field hl string[]
 
+---
 ---Abstract Decorator interface
 ---
----@class (exact) nvim_tree.api.decorator.Decorator: Class
----@field protected enabled boolean
----@field protected highlight_range nvim_tree.api.decorator.highlight_range
----@field protected icon_placement nvim_tree.api.decorator.icon_placement
-nvim_tree.api.decorator.Decorator = Class:extend()
+---@class nvim_tree.api.decorator.Decorator: nvim_tree.Class
+---@field enabled boolean
+---@field highlight_range nvim_tree.api.decorator.highlight_range
+---@field icon_placement nvim_tree.api.decorator.icon_placement
+local Decorator = Class:extend()
+nvim_tree.api.decorator.Decorator = Decorator
 
+---
 ---Abstract: optionally implement to set the node's icon
 ---
 ---@param node nvim_tree.api.Node
 ---@return nvim_tree.api.decorator.highlighted_string? icon_node
-function nvim_tree.api.decorator.Decorator:icon_node(node) end
+function Decorator: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 nvim_tree.api.decorator.highlighted_string[]? icons
-function nvim_tree.api.decorator.Decorator:icons(node) end
+function Decorator:icons(node) end
 
+---
 ---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.Decorator:highlight_group(node) end
+function Decorator:highlight_group(node) end
 
+---
 ---Defines a sign. This should be called in the constructor.
 ---
----@protected
 ---@param icon nvim_tree.api.decorator.highlighted_string?
-function nvim_tree.api.decorator.Decorator:define_sign(icon) end
+function Decorator:define_sign(icon) end
 
----@deprecated use `nvim_tree.api.decorator.Decorator`
+---
 ---@class nvim_tree.api.decorator.UserDecorator: nvim_tree.api.decorator.Decorator
+---@nodoc
+---@deprecated use `nvim_tree.api.decorator.Decorator`
+---
 nvim_tree.api.decorator.UserDecorator = nvim_tree.api.decorator.Decorator
 
 return nvim_tree.api.decorator

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

@@ -9,3 +9,4 @@
 ---}
 ---```
 ---
+---placeholder for next section [nvim-tree-api]()

lua/nvim-tree/api/impl/post.lua

@@ -255,7 +255,7 @@ function M.hydrate(api)
 
   api.map.keymap.current = keymap.get_keymap
 
-  -- (Re)hydrate any legacy by mapping to function set above
+  -- (Re)hydrate any legacy by mapping to concrete set above
   require("nvim-tree.api.impl.legacy").hydrate(api)
 end
 

lua/nvim-tree/api/impl/pre.lua

@@ -52,7 +52,7 @@ function M.hydrate(api)
   -- classes
   api.decorator.Decorator = UserDecorator:extend()
 
-  -- Hydrate any legacy by mapping to function set above
+  -- Hydrate any legacy by mapping to concrete set above
   require("nvim-tree.api.impl.legacy").hydrate(api)
 end
 

lua/nvim-tree/classic.lua

@@ -9,7 +9,11 @@
 -- https://github.com/rxi/classic
 --
 
----@class (exact) Class
+---TODO #3241 document and rename
+---@class Class: nvim_tree.Class
+---@nodoc
+
+---@class nvim_tree.Class
 ---@field super Class
 ---@field private implements table<Class, boolean>
 local Class = {}

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

@@ -5,7 +5,7 @@
 ---@field protected icon_placement nvim_tree.api.decorator.icon_placement
 local Decorator = require("nvim-tree._meta.api.decorator").Decorator:extend()
 
----TODO #3241 maybe create an internal decorator class and lose the UserDecorator
+---TODO #3241 create an internal decorator class with explorer member and lose the UserDecorator
 ---@class (exact) DecoratorArgs
 ---@field explorer Explorer
 

scripts/gen_vimdoc_config.lua

@@ -10,6 +10,14 @@
 ---@field section string arbitrary
 ---@field path string relative to root
 
+---TODO #3241 do this for all classes, moving decorator up to nvim_tree.api.Decorator
+
+---Module overrides
+---@type table<string, string>
+local module_overrides = {
+  ["nvim_tree.classic"] = "nvim_tree"
+}
+
 local pre = "runtime/lua/nvim_tree/"
 
 ---@type Src[]
@@ -39,24 +47,24 @@ local srcs_config = {
   { helptag = "nvim-tree-config-log",                 section = "Config: log",                 path = pre .. "_meta/config/log.lua", },
 
   { helptag = "nvim-tree-config-default",             section = "Config: Default",             path = pre .. "_meta/config/default.lua", },
-
-  { helptag = "nvim-tree-api",                        section = "placeholder for next Config", path = pre .. "api.lua", },
 }
 
 ---@type Src[]
 local srcs_api = {
-  { helptag = "nvim-tree-api",          section = "API",           path = pre .. "api.lua", },
-
-  { helptag = "nvim-tree-api-commands", section = "API: commands", path = pre .. "_meta/api/commands.lua", },
-  { helptag = "nvim-tree-api-events",   section = "API: events",   path = pre .. "_meta/api/events.lua", },
-  { helptag = "nvim-tree-api-filter",   section = "API: filter",   path = pre .. "_meta/api/filter.lua", },
-  { helptag = "nvim-tree-api-fs",       section = "API: fs",       path = pre .. "_meta/api/fs.lua", },
-  { helptag = "nvim-tree-api-git",      section = "API: git",      path = pre .. "_meta/api/git.lua", },
-  { helptag = "nvim-tree-api-health",   section = "API: health",   path = pre .. "_meta/api/health.lua", },
-  { helptag = "nvim-tree-api-map",      section = "API: map",      path = pre .. "_meta/api/map.lua", },
-  { helptag = "nvim-tree-api-marks",    section = "API: marks",    path = pre .. "_meta/api/marks.lua", },
-  { helptag = "nvim-tree-api-node",     section = "API: node",     path = pre .. "_meta/api/node.lua", },
-  { helptag = "nvim-tree-api-tree",     section = "API: tree",     path = pre .. "_meta/api/tree.lua", },
+  { helptag = "nvim-tree-api",           section = "API",            path = pre .. "api.lua", },
+
+  { helptag = "nvim-tree-api-commands",  section = "API: commands",  path = pre .. "_meta/api/commands.lua", },
+  { helptag = "nvim-tree-api-events",    section = "API: events",    path = pre .. "_meta/api/events.lua", },
+  { helptag = "nvim-tree-api-filter",    section = "API: filter",    path = pre .. "_meta/api/filter.lua", },
+  { helptag = "nvim-tree-api-fs",        section = "API: fs",        path = pre .. "_meta/api/fs.lua", },
+  { helptag = "nvim-tree-api-git",       section = "API: git",       path = pre .. "_meta/api/git.lua", },
+  { helptag = "nvim-tree-api-health",    section = "API: health",    path = pre .. "_meta/api/health.lua", },
+  { helptag = "nvim-tree-api-map",       section = "API: map",       path = pre .. "_meta/api/map.lua", },
+  { helptag = "nvim-tree-api-marks",     section = "API: marks",     path = pre .. "_meta/api/marks.lua", },
+  { helptag = "nvim-tree-api-node",      section = "API: node",      path = pre .. "_meta/api/node.lua", },
+  { helptag = "nvim-tree-api-tree",      section = "API: tree",      path = pre .. "_meta/api/tree.lua", },
+  { helptag = "nvim-tree-api-decorator", section = "API: Decorator", path = pre .. "_meta/api/decorator.lua", },
+  { helptag = "nvim-tree-api-class",     section = "API: Class",     path = pre .. "classic.lua", },
 }
 
 ---Map paths to file names
@@ -92,6 +100,17 @@ local function src_by_name(name, srcs)
   error(string.format("\n\nPath for lower, extension stripped file name='%s' not found in\nsrcs=%s\n", name, vim.inspect(srcs)))
 end
 
+---HACK
+---Problem:
+--- Generator generates fields for a class' methods.
+--- This is a problem as method fields don't have a module and aren't transformed.
+--- Method field fun only contains: classvar, desc, name and (function) type
+---Solution:
+--- Collect a map of "class:method" to modules when the real method passes through fn_xform
+--- This works as the real method function is processed before the field method.
+---@type table<string, string>
+local modules_by_method = {}
+
 -- @type nvim.gen_vimdoc.Config[]
 return {
   -- Config
@@ -110,23 +129,42 @@ return {
     section_fmt = function(name) return src_by_name(name, srcs_api).section end,
     helptag_fmt = function(name) return src_by_name(name, srcs_api).helptag end,
 
-    -- optional, no default xform to override
     fn_xform = function(fun)
-      if (fun.module) then
-        -- generator doesn't strip meta
-        -- also cascades into fn_helptag_fmt
-        local module = fun.module:gsub("._meta", "", 1)
-
-        -- remove the API prefix from the left aligned function name
-        -- this will cascade into fn_helptag_fmt, which will apply the module prefix anyway
-        local name, replaced = fun.name:gsub("^" .. module .. "%.", "", 1)
+      -- generator doesn't strip _meta; this propagates to fn_helptag_fmt
+      fun.module = fun.module:gsub("._meta", "", 1)
+      fun.module = module_overrides[fun.module] or fun.module
+
+      if not fun.class then
+        -- functions require the module to be stripped from the name, classes do not
+        local name, replaced = fun.name:gsub("^" .. fun.module .. "%.", "", 1)
         if (replaced ~= 1) then
-          error(string.format("\n\nfun.name='%s' does not start with _meta stripped module='%s'\nfun=%s", fun.name, module, vim.inspect(fun)))
+          error(string.format("\n\nfn_xform: fun.name='%s' does not start with _meta stripped \nfun=%s",
+            fun.name, vim.inspect(fun)))
         end
-
-        fun.module = module
         fun.name = name
+      elseif fun.class and fun.classvar and fun.name then
+        -- note the module for use by method fields
+        modules_by_method[fun.classvar .. ":" .. fun.name] = fun.module
+      end
+    end,
+
+    -- fn_helptag_fmt_common modified:
+    --  module prepended to classes
+    --  module is fetched from modules_by_method when fun.module unavailable
+    fn_helptag_fmt = function(fun)
+      local fn_sfx = fun.table and "" or "()"
+      if fun.classvar then
+        local module = fun.module or modules_by_method[fun.classvar .. ":" .. fun.name]
+        if not module then
+          error(string.format("\n\nfn_helptag_fmt: no module:\nfun=%s\nmodules_by_method=%s",
+            vim.inspect(fun), vim.inspect(modules_by_method)))
+        end
+        return string.format("%s.%s:%s%s", module, fun.classvar, fun.name, fn_sfx)
+      end
+      if fun.module then
+        return string.format("%s.%s%s", fun.module, fun.name, fn_sfx)
       end
+      return fun.name .. fn_sfx
     end,
   }
 }