Skip to content

Commit dc536aa

Browse files
alex-courtisalex-courtis
committed
docs(#2934): polish vimdoc config
1 parent de9c62c commit dc536aa

File tree

1 file changed

+67
-55
lines changed

1 file changed

+67
-55
lines changed

‎scripts/gen_vimdoc_config.lua‎

Lines changed: 67 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,49 @@
1-
---@class (exact) Module
1+
---@class (exact) Src
22
---@field helptag string must be globally unique
3-
---@field title string arbitrary
3+
---@field section string arbitrary
44
---@field path string relative to root
5-
---@field file string? generated from path
6-
---@field name string? override generated module name
5+
---@field file_name string? generated from path
6+
---@field name string? override generated name
77

8-
---Generated within help files in this order
9-
---@type Module[]
10-
local modules = {
11-
{ helptag = "nvim-tree-config", title = "Class: Config", path = "./lua/nvim_tree/_meta/config.lua", },
12-
{ helptag = "nvim-tree-config-sort", title = "Class: Config.Sort", path = "./lua/nvim_tree/_meta/config/sort.lua", },
13-
{ helptag = "nvim-tree-config-view", title = "Class: Config.View", path = "./lua/nvim_tree/_meta/config/view.lua", },
14-
{ helptag = "nvim-tree-config-renderer", title = "Class: Config.Renderer", path = "./lua/nvim_tree/_meta/config/renderer.lua", },
15-
{ helptag = "nvim-tree-config-hijack-directories", title = "Class: Config.HijackDirectories", path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", },
16-
{ helptag = "nvim-tree-config-update-focused-file", title = "Class: Config.UpdateFocusedFile", path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", },
17-
{ helptag = "nvim-tree-config-system-open", title = "Class: Config.SystemOpen", path = "./lua/nvim_tree/_meta/config/system_open.lua", },
18-
{ helptag = "nvim-tree-config-git", title = "Class: Config.Git", path = "./lua/nvim_tree/_meta/config/git.lua", },
19-
{ helptag = "nvim-tree-config-diagnostics", title = "Class: Config.Diagnostics", path = "./lua/nvim_tree/_meta/config/diagnostics.lua", },
20-
{ helptag = "nvim-tree-config-modified", title = "Class: Config.Modified", path = "./lua/nvim_tree/_meta/config/modified.lua", },
21-
{ helptag = "nvim-tree-config-filters", title = "Class: Config.Filters", path = "./lua/nvim_tree/_meta/config/filters.lua", },
22-
{ helptag = "nvim-tree-config-live-filter", title = "Class: Config.LiveFilter", path = "./lua/nvim_tree/_meta/config/live_filter.lua", },
23-
{ helptag = "nvim-tree-config-filesystem-watchers", title = "Class: Config.FilesystemWatchers", path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", },
24-
{ helptag = "nvim-tree-config-actions", title = "Class: Config.Actions", path = "./lua/nvim_tree/_meta/config/actions.lua", },
25-
{ helptag = "nvim-tree-config-trash", title = "Class: Config.Trash", path = "./lua/nvim_tree/_meta/config/trash.lua", },
26-
{ helptag = "nvim-tree-config-tab", title = "Class: Config.Tab", path = "./lua/nvim_tree/_meta/config/tab.lua", },
27-
{ helptag = "nvim-tree-config-notify", title = "Class: Config.Notify", path = "./lua/nvim_tree/_meta/config/notify.lua", },
28-
{ helptag = "nvim-tree-config-bookmarks", title = "Class: Config.Bookmarks", path = "./lua/nvim_tree/_meta/config/bookmarks.lua", },
29-
{ helptag = "nvim-tree-config-help", title = "Class: Config.Help", path = "./lua/nvim_tree/_meta/config/help.lua", },
30-
{ helptag = "nvim-tree-config-ui", title = "Class: Config.UI", path = "./lua/nvim_tree/_meta/config/ui.lua", name = "UI", },
31-
{ helptag = "nvim-tree-config-experimental", title = "Class: Config.Experimental", path = "./lua/nvim_tree/_meta/config/experimental.lua", },
32-
{ helptag = "nvim-tree-config-log", title = "Class: Config.Log", path = "./lua/nvim_tree/_meta/config/log.lua", },
8+
---Help txt is deleted from first tag down and generated content is appended.
9+
---@type Src[]
10+
local srcs = {
11+
{ helptag = "nvim-tree-config", section = "Class: Config", path = "./lua/nvim_tree/_meta/config.lua", },
12+
{ helptag = "nvim-tree-config-sort", section = "Class: Config.Sort", path = "./lua/nvim_tree/_meta/config/sort.lua", },
13+
{ helptag = "nvim-tree-config-view", section = "Class: Config.View", path = "./lua/nvim_tree/_meta/config/view.lua", },
14+
{ helptag = "nvim-tree-config-renderer", section = "Class: Config.Renderer", path = "./lua/nvim_tree/_meta/config/renderer.lua", },
15+
{ helptag = "nvim-tree-config-hijack-directories", section = "Class: Config.HijackDirectories", path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", },
16+
{ helptag = "nvim-tree-config-update-focused-file", section = "Class: Config.UpdateFocusedFile", path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", },
17+
{ helptag = "nvim-tree-config-system-open", section = "Class: Config.SystemOpen", path = "./lua/nvim_tree/_meta/config/system_open.lua", },
18+
{ helptag = "nvim-tree-config-git", section = "Class: Config.Git", path = "./lua/nvim_tree/_meta/config/git.lua", },
19+
{ helptag = "nvim-tree-config-diagnostics", section = "Class: Config.Diagnostics", path = "./lua/nvim_tree/_meta/config/diagnostics.lua", },
20+
{ helptag = "nvim-tree-config-modified", section = "Class: Config.Modified", path = "./lua/nvim_tree/_meta/config/modified.lua", },
21+
{ helptag = "nvim-tree-config-filters", section = "Class: Config.Filters", path = "./lua/nvim_tree/_meta/config/filters.lua", },
22+
{ helptag = "nvim-tree-config-live-filter", section = "Class: Config.LiveFilter", path = "./lua/nvim_tree/_meta/config/live_filter.lua", },
23+
{ helptag = "nvim-tree-config-filesystem-watchers", section = "Class: Config.FilesystemWatchers", path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", },
24+
{ helptag = "nvim-tree-config-actions", section = "Class: Config.Actions", path = "./lua/nvim_tree/_meta/config/actions.lua", },
25+
{ helptag = "nvim-tree-config-trash", section = "Class: Config.Trash", path = "./lua/nvim_tree/_meta/config/trash.lua", },
26+
{ helptag = "nvim-tree-config-tab", section = "Class: Config.Tab", path = "./lua/nvim_tree/_meta/config/tab.lua", },
27+
{ helptag = "nvim-tree-config-notify", section = "Class: Config.Notify", path = "./lua/nvim_tree/_meta/config/notify.lua", },
28+
{ helptag = "nvim-tree-config-bookmarks", section = "Class: Config.Bookmarks", path = "./lua/nvim_tree/_meta/config/bookmarks.lua", },
29+
{ helptag = "nvim-tree-config-help", section = "Class: Config.Help", path = "./lua/nvim_tree/_meta/config/help.lua", },
30+
{ helptag = "nvim-tree-config-ui", section = "Class: Config.UI", path = "./lua/nvim_tree/_meta/config/ui.lua", name = "UI", },
31+
{ helptag = "nvim-tree-config-experimental", section = "Class: Config.Experimental", path = "./lua/nvim_tree/_meta/config/experimental.lua", },
32+
{ helptag = "nvim-tree-config-log", section = "Class: Config.Log", path = "./lua/nvim_tree/_meta/config/log.lua", },
3333
}
3434

3535
-- hydrate file names
36-
for _, m in ipairs(modules) do
37-
m.file = vim.fn.fnamemodify(m.path, ":t")
36+
for _, m in ipairs(srcs) do
37+
m.file_name = vim.fn.fnamemodify(m.path, ":t")
3838
end
3939

40-
--module name is derived by the generator as the file name with the first letter capitalised
41-
--except for some like UI
42-
---@type table<string, Module>
43-
local modules_by_name = {}
44-
for _, m in ipairs(modules) do
45-
local name = m.name or m.file:gsub(".lua", ""):gsub("^%l", string.upper)
46-
modules_by_name[name] = m
40+
--name is derived by the generator as the file name with the first letter capitalised
41+
--except for some like UI which are overridden in srcs
42+
---@type table<string, Src>
43+
local srcs_by_name = {}
44+
for _, m in ipairs(srcs) do
45+
local name = m.name or m.file_name:gsub(".lua", ""):gsub("^%l", string.upper)
46+
srcs_by_name[name] = m
4747
end
4848

4949
---@diagnostic disable-next-line: undefined-doc-name
@@ -52,33 +52,45 @@ local config = {
5252
all = {
5353
filename = "nvim-tree-lua.txt",
5454

55-
-- file is used to set order
56-
section_order = vim.tbl_map(function(m) return m.file end, modules),
55+
-- source file name is used to set order
56+
section_order = vim.tbl_map(function(src) return src.file_name end, srcs),
5757

5858
-- path
59-
files = vim.tbl_map(function(m) return m.path end, modules),
59+
files = vim.tbl_map(function(src) return src.path end, srcs),
6060

6161
section_fmt = function(name)
62-
return modules_by_name[name] and modules_by_name[name].title or error(string.format("unknown module %s passed to section_fmt", name))
62+
print(string.format("section_fmt name=%s", name))
63+
return srcs_by_name[name] and srcs_by_name[name].section or
64+
error(string.format("unknown name %s passed to section_fmt", name))
6365
end,
6466

6567
helptag_fmt = function(name)
66-
return modules_by_name[name] and modules_by_name[name].helptag or error(string.format("unknown module %s passed to helptag_fmt", name))
68+
print(string.format("helptag_fmt name=%s", name))
69+
return srcs_by_name[name] and srcs_by_name[name].helptag or
70+
error(string.format("unknown name %s passed to helptag_fmt", name))
6771
end,
6872

69-
-- class/function's help tag
70-
fn_helptag_fmt = function(fun)
71-
-- Modified copy of fn_helptag_fmt_common
72-
-- Uses fully qualified class name in the tag for methods.
73-
-- The module is used everywhere else, however not available for classes.
74-
local fn_sfx = fun.table and "" or "()"
75-
if fun.classvar then
76-
return string.format("%s:%s%s", fun.class or fun.classvar, fun.name, fn_sfx)
77-
end
78-
if fun.module then
79-
return string.format("%s.%s%s", fun.module, fun.name, fn_sfx)
73+
-- optional, no default xform
74+
fn_xform = function(fun)
75+
print(string.format("fn_xform fun=%s", vim.inspect(fun)))
76+
77+
if (fun.module) then
78+
-- generator doesn't strip meta
79+
-- also cascades into fn_helptag_fmt
80+
local module = fun.module:gsub("._meta", "", 1)
81+
82+
-- remove the API prefix from the left aligned function name
83+
-- this will cascade into fn_helptag_fmt, which will apply the module prefix anyway
84+
local name, replaced = fun.name:gsub("^" .. module .. "%.", "", 1)
85+
if (replaced ~= 1) then
86+
error(string.format("function name does not start with module: %s", vim.inspect(fun)))
87+
end
88+
89+
print(string.format("fn_xform name: %s -> %s", fun.name, name))
90+
91+
fun.module = module
92+
fun.name = name
8093
end
81-
return fun.name .. fn_sfx
8294
end,
8395
}
8496
}

0 commit comments

Comments
 (0)