doc(#2934): POC to use gen_vimdoc.lua for decorator meta

Author: alex-courtis

doc/decorator.txt

@@ -0,0 +1,66 @@
+*decorator.txt*   nvim-tree decorators
+
+==============================================================================
+==============================================================================
+Lua module: nvim_tree.api.decorator                     *nvim-tree-decorators*
+
+*nvim_tree.api.decorator.UserDecorator*
+    Custom decorator, see :help nvim-tree-decorators
+
+    Fields: ~
+      • {enabled}          (`boolean`)
+      • {highlight_range}  (`nvim_tree.api.decorator.HighlightRange`)
+      • {icon_placement}   (`nvim_tree.api.decorator.IconPlacement`)
+      • {extend}           (`fun(self: nvim_tree.api.decorator.UserDecorator)`)
+                           See |UserDecorator:extend()|.
+      • {new}              (`fun(self: nvim_tree.api.decorator.UserDecorator)`)
+                           See |UserDecorator:new()|.
+      • {icon_node}        (`fun(self: nvim_tree.api.decorator.UserDecorator, node: nvim_tree.api.Node): nvim_tree.api.HighlightedString?`)
+                           See |UserDecorator:icon_node()|.
+      • {icons}            (`fun(self: nvim_tree.api.decorator.UserDecorator, node: nvim_tree.api.Node): nvim_tree.api.HighlightedString[]?`)
+                           See |UserDecorator:icons()|.
+      • {highlight_group}  (`fun(self: nvim_tree.api.decorator.UserDecorator, node: nvim_tree.api.Node): string?`)
+                           See |UserDecorator:highlight_group()|.
+
+
+UserDecorator:extend()        *nvim_tree.api.decorator.UserDecorator:extend()*
+    Create your decorator class
+
+                     *nvim_tree.api.decorator.UserDecorator:highlight_group()*
+UserDecorator: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.UserDecorator:icon_node()*
+UserDecorator:icon_node({node})
+    Abstract: optionally implement to set the node's icon
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+    Return: ~
+        (`nvim_tree.api.HighlightedString?`) icon_node
+
+                               *nvim_tree.api.decorator.UserDecorator:icons()*
+UserDecorator:icons({node})
+    Abstract: optionally implement to provide icons and the highlight groups
+    for your icon_placement.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+    Return: ~
+        (`nvim_tree.api.HighlightedString[]?`) icons
+
+UserDecorator:new()              *nvim_tree.api.decorator.UserDecorator:new()*
+    Abstract: no-args constructor must be implemented and will be called once
+    per tree render. Must set all fields.
+
+
+ vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

lua/nvim-tree/_meta/api_decorator.lua

@@ -1,8 +1,6 @@
 ---@meta
 error("Cannot require a meta file")
 
-local nvim_tree = { api = { decorator = {} } }
-
 ---Highlight group range as per nvim-tree.renderer.highlight_*
 ---@alias nvim_tree.api.decorator.HighlightRange "none" | "icon" | "name" | "all"
 
@@ -14,41 +12,41 @@ local nvim_tree = { api = { decorator = {} } }
 
 ---Custom decorator, see :help nvim-tree-decorators
 ---
----@class (exact) nvim_tree.api.decorator.UserDecorator
----@field protected enabled boolean
----@field protected highlight_range nvim_tree.api.decorator.HighlightRange
----@field protected icon_placement nvim_tree.api.decorator.IconPlacement
-nvim_tree.api.decorator.UserDecorator = {}
+---@class nvim_tree.api.decorator.UserDecorator
+---@field enabled boolean
+---@field highlight_range nvim_tree.api.decorator.HighlightRange
+---@field icon_placement nvim_tree.api.decorator.IconPlacement
+local UserDecorator = {}
 
 ---Create your decorator class
 ---
-function nvim_tree.api.decorator.UserDecorator:extend() end
+function UserDecorator:extend() end
 
 ---Abstract: no-args constructor must be implemented and will be called once per tree render.
 ---Must set all fields.
 ---
-function nvim_tree.api.decorator.UserDecorator:new() end
+function UserDecorator:new() end
 
 ---Abstract: optionally implement to set the node's icon
 ---
 ---@param node nvim_tree.api.Node
 ---@return nvim_tree.api.HighlightedString? icon_node
-function nvim_tree.api.decorator.UserDecorator:icon_node(node) end
+function UserDecorator: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.HighlightedString[]? icons
-function nvim_tree.api.decorator.UserDecorator:icons(node) end
+function UserDecorator: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.UserDecorator:highlight_group(node) end
+function UserDecorator:highlight_group(node) end
 
 ---Define a sign. This should be called in the constructor.
 ---
 ---@protected
 ---@param icon nvim_tree.api.HighlightedString?
-function nvim_tree.api.decorator.UserDecorator:define_sign(icon) end
+function UserDecorator:define_sign(icon) end

scripts/doc.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+
+set -e
+
+if [ ! -d "${NEOVIM_SRC}" ]; then
+	echo "\$NEOVIM_SRC not set"
+	exit 1
+fi
+
+# runtime/doc is hardcoded, copy it in
+mkdir -p runtime/doc
+cp "doc/decorator.txt" runtime/doc
+
+# use luacacts etc. from neovim src
+LUA_PATH="${NEOVIM_SRC}/src/?.lua"
+
+# generate
+scripts/gen_vimdoc.lua
+
+# move the output
+mv "runtime/doc/decorator.txt" doc
+rmdir runtime/doc
+rmdir runtime
+

scripts/gen_vimdoc.decorator.lua

@@ -0,0 +1,49 @@
+---@diagnostic disable: undefined-doc-name
+
+--- @param fun nvim.luacats.parser.fun
+--- @return string
+local function fn_helptag_fmt_common0(fun)
+  local fn_sfx = fun.table and '' or '()'
+  if fun.classvar then
+    return string.format('%s:%s%s', 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
+
+return {
+  filename = "decorator.txt",
+  section_order = {
+    "api_decorator.lua",
+  },
+  files = {
+    -- module is derived soley from the file name, first letter capitalised
+    -- 'runtime/lua/nvim-tree/foo/api_decorator.lua',
+    "/home/alex/src/nvim-tree/master/lua/nvim-tree/_meta/api_decorator.lua"
+  },
+  section_fmt = function(name)
+    if name == "Api_decorator" then
+      return "Lua module: nvim_tree.api.decorator"
+    end
+    error(string.format("unknown module %s passed to section_fmt", name))
+  end,
+  helptag_fmt = function(name)
+    -- used to locate the help section
+    if name == "Api_decorator" then
+      return "nvim-tree-decorators"
+    end
+    error(string.format("unknown module %s passed to helptag_fmt", name))
+  end,
+  fn_helptag_fmt = function(fun)
+    -- use the fully qualified class name in the tag for methods
+    -- this is done everywhere but for classes
+    local common = fn_helptag_fmt_common0(fun)
+    local helptag = common
+    if fun.class then
+      helptag = common:gsub(fun.classvar, fun.class)
+    end
+    return helptag
+  end,
+}