From 9beb40a4db5613601fc1a4b828a44e5977eca046 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Thu, 15 Feb 2024 17:16:04 +0000 Subject: feat(docs): replace lua2dox.lua Problem: The documentation flow (`gen_vimdoc.py`) has several issues: - it's not very versatile - depends on doxygen - doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C. - The intermediate XML files and filters makes it too much like a rube goldberg machine. Solution: Re-implement the flow using Lua, LPEG and treesitter. - `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic. - `lua2dox.lua` is gone! - No more XML files. - Doxygen is now longer used and instead we now use: - LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`). - LPEG for C parsing (see `scripts/cdoc_parser.lua`) - Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`). - Treesitter for Markdown parsing (see `scripts/text_utils.lua`). - The generated `runtime/doc/*.mpack` files have been removed. - `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly. - Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change). --- runtime/lua/vim/fs.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/fs.lua') diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua index 22612a7255..0af5fc4f30 100644 --- a/runtime/lua/vim/fs.lua +++ b/runtime/lua/vim/fs.lua @@ -320,7 +320,7 @@ end --- Normalize a path to a standard format. A tilde (~) character at the --- beginning of the path is expanded to the user's home directory and any ---- backslash (\\) characters are converted to forward slashes (/). Environment +--- backslash (\) characters are converted to forward slashes (/). Environment --- variables are also expanded. --- --- Examples: -- cgit From a5fe8f59d98398d04bed8586cee73864bbcdde92 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Tue, 27 Feb 2024 15:20:32 +0000 Subject: docs: improve/add documentation of Lua types - Added `@inlinedoc` so single use Lua types can be inlined into the functions docs. E.g. ```lua --- @class myopts --- @inlinedoc --- --- Documentation for some field --- @field somefield integer --- @param opts myOpts function foo(opts) end ``` Will be rendered as ``` foo(opts) Parameters: - {opts} (table) Object with the fields: - somefield (integer) Documentation for some field ``` - Marked many classes with with `@nodoc` or `(private)`. We can eventually introduce these when we want to. --- runtime/lua/vim/fs.lua | 49 ++++++++++++++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 19 deletions(-) (limited to 'runtime/lua/vim/fs.lua') diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua index 0af5fc4f30..a47b35e991 100644 --- a/runtime/lua/vim/fs.lua +++ b/runtime/lua/vim/fs.lua @@ -147,11 +147,29 @@ function M.dir(path, opts) end) end ---- @class vim.fs.find.opts +--- @class vim.fs.find.Opts +--- @inlinedoc +--- +--- Path to begin searching from. If +--- omitted, the |current-directory| is used. --- @field path string +--- +--- Search upward through parent directories. +--- Otherwise, search through child directories (recursively). +--- (default: `false`) --- @field upward boolean +--- +--- Stop searching when this directory is reached. +--- The directory itself is not searched. --- @field stop string +--- +--- Find only items of the given type. +--- If omitted, all items that match {names} are included. --- @field type string +--- +--- Stop the search after finding this many matches. +--- Use `math.huge` to place no limit on the number of matches. +--- (default: `1`) --- @field limit number --- Find files or directories (or other items as specified by `opts.type`) in the given path. @@ -194,23 +212,10 @@ end --- - path: full path of the current item --- The function should return `true` if the given item is considered a match. --- ----@param opts (table) Optional keyword arguments: ---- - path (string): Path to begin searching from. If ---- omitted, the |current-directory| is used. ---- - upward (boolean, default false): If true, search ---- upward through parent directories. Otherwise, ---- search through child directories ---- (recursively). ---- - stop (string): Stop searching when this directory is ---- reached. The directory itself is not searched. ---- - type (string): Find only items of the given type. ---- If omitted, all items that match {names} are included. ---- - limit (number, default 1): Stop the search after ---- finding this many matches. Use `math.huge` to ---- place no limit on the number of matches. +---@param opts vim.fs.find.Opts Optional keyword arguments: ---@return (string[]) # Normalized paths |vim.fs.normalize()| of all matching items function M.find(names, opts) - opts = opts or {} --[[@as vim.fs.find.opts]] + opts = opts or {} vim.validate({ names = { names, { 's', 't', 'f' } }, path = { opts.path, 's', true }, @@ -318,6 +323,13 @@ function M.find(names, opts) return matches end +--- @class vim.fs.normalize.Opts +--- @inlinedoc +--- +--- Expand environment variables. +--- (default: `true`) +--- @field expand_env boolean + --- Normalize a path to a standard format. A tilde (~) character at the --- beginning of the path is expanded to the user's home directory and any --- backslash (\) characters are converted to forward slashes (/). Environment @@ -337,9 +349,8 @@ end --- ``` --- ---@param path (string) Path to normalize ----@param opts table|nil Options: ---- - expand_env: boolean Expand environment variables (default: true) ----@return (string) Normalized path +---@param opts? vim.fs.normalize.Opts +---@return (string) : Normalized path function M.normalize(path, opts) opts = opts or {} -- cgit From ea44f74d84f87ce5aff2ef7797be986900bd74a6 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Wed, 6 Mar 2024 10:03:55 +0000 Subject: refactor(types): more fixes --- runtime/lua/vim/fs.lua | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'runtime/lua/vim/fs.lua') diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua index a47b35e991..28a531707f 100644 --- a/runtime/lua/vim/fs.lua +++ b/runtime/lua/vim/fs.lua @@ -152,25 +152,25 @@ end --- --- Path to begin searching from. If --- omitted, the |current-directory| is used. ---- @field path string +--- @field path? string --- --- Search upward through parent directories. --- Otherwise, search through child directories (recursively). --- (default: `false`) ---- @field upward boolean +--- @field upward? boolean --- --- Stop searching when this directory is reached. --- The directory itself is not searched. ---- @field stop string +--- @field stop? string --- --- Find only items of the given type. --- If omitted, all items that match {names} are included. ---- @field type string +--- @field type? string --- --- Stop the search after finding this many matches. --- Use `math.huge` to place no limit on the number of matches. --- (default: `1`) ---- @field limit number +--- @field limit? number --- Find files or directories (or other items as specified by `opts.type`) in the given path. --- @@ -229,7 +229,7 @@ function M.find(names, opts) names = { names } end - local path = opts.path or vim.uv.cwd() + local path = opts.path or assert(vim.uv.cwd()) local stop = opts.stop local limit = opts.limit or 1 -- cgit From ae5095cac9b233cfb6785534de6f084c70dc6424 Mon Sep 17 00:00:00 2001 From: altermo <107814000+altermo@users.noreply.github.com> Date: Wed, 6 Mar 2024 17:18:00 +0100 Subject: fix(fs): use generics for better typing --- runtime/lua/vim/fs.lua | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'runtime/lua/vim/fs.lua') diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua index 28a531707f..f9fe122f01 100644 --- a/runtime/lua/vim/fs.lua +++ b/runtime/lua/vim/fs.lua @@ -39,8 +39,9 @@ end --- Return the parent directory of the given path --- ----@param file (string) Path ----@return string|nil Parent directory of {file} +---@generic T : string|nil +---@param file T Path +---@return T Parent directory of {file} function M.dirname(file) if file == nil then return nil @@ -53,6 +54,7 @@ function M.dirname(file) elseif file == '/' or file:match('^/[^/]+$') then return '/' end + ---@type string local dir = file:match('[/\\]$') and file:sub(1, #file - 1) or file:match('^([/\\]?.+)[/\\]') if iswin and dir:match('^%w:$') then return dir .. '/' @@ -62,8 +64,9 @@ end --- Return the basename of the given path --- ----@param file string Path ----@return string|nil Basename of {file} +---@generic T : string|nil +---@param file T Path +---@return T Basename of {file} function M.basename(file) if file == nil then return nil -- cgit