From 6628741ada73bcf60dd1cb249178aa18e60dbebc Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 6 Oct 2024 09:12:35 -0700 Subject: feat(docs): improve `@see` meta docstrings #30693 --- scripts/gen_eval_files.lua | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) (limited to 'scripts/gen_eval_files.lua') diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua index 6aa8ee0112..25f3e30b74 100755 --- a/scripts/gen_eval_files.lua +++ b/scripts/gen_eval_files.lua @@ -199,14 +199,6 @@ local function process_params(params) return params end ---- @class vim.gen_vim_doc_fun ---- @field signature string ---- @field doc string[] ---- @field parameters_doc table ---- @field return string[] ---- @field seealso string[] ---- @field annotations string[] - --- @return table local function get_api_meta() local ret = {} --- @type table @@ -290,8 +282,19 @@ end --- Ensure code blocks have one empty line before the start fence and after the closing fence. --- --- @param x string +--- @param special string? +--- | 'see-api-meta' Normalize `@see` for API meta docstrings. --- @return string -local function norm_text(x) +local function norm_text(x, special) + if special == 'see-api-meta' then + -- Try to guess a symbol that actually works in @see. + -- "nvim_xx()" => "vim.api.nvim_xx" + x = x:gsub([=[%|?(nvim_[^.()| ]+)%(?%)?%|?]=], 'vim.api.%1') + -- TODO: Remove backticks when LuaLS resolves: https://github.com/LuaLS/lua-language-server/issues/2889 + -- "|foo|" => "`:help foo`" + x = x:gsub([=[|([^ ]+)|]=], '`:help %1`') + end + return ( x:gsub('|([^ ]+)|', '`%1`') :gsub('\n*>lua', '\n\n```lua') @@ -332,7 +335,7 @@ local function render_api_meta(_f, fun, write) end for _, see in ipairs(fun.see or {}) do - write(util.prefix_lines('--- @see ', norm_text(see))) + write(util.prefix_lines('--- @see ', norm_text(see, 'see-api-meta'))) end local param_names = {} --- @type string[] -- cgit