docs: more @since annotations #30660

This commit is contained in:
Justin M. Keyes 2024-10-04 08:12:17 -07:00 committed by GitHub
parent 49b1af4e24
commit 9a5bbaf813
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 38 additions and 2 deletions

View File

@ -146,9 +146,9 @@ set(NVIM_VERSION_PATCH 0)
set(NVIM_VERSION_PRERELEASE "-dev") # for package maintainers set(NVIM_VERSION_PRERELEASE "-dev") # for package maintainers
# API level # API level
set(NVIM_API_LEVEL 12) # Bump this after any API change. set(NVIM_API_LEVEL 13) # Bump this after any API/stdlib change.
set(NVIM_API_LEVEL_COMPAT 0) # Adjust this after a _breaking_ API change. set(NVIM_API_LEVEL_COMPAT 0) # Adjust this after a _breaking_ API change.
set(NVIM_API_PRERELEASE false) set(NVIM_API_PRERELEASE true)
# Build-type: RelWithDebInfo # Build-type: RelWithDebInfo
# /Og means something different in MSVC # /Og means something different in MSVC

View File

@ -2910,6 +2910,9 @@ Lua module: vim.fs *vim.fs*
vim.fs.basename({file}) *vim.fs.basename()* vim.fs.basename({file}) *vim.fs.basename()*
Return the basename of the given path Return the basename of the given path
Attributes: ~
Since: 0.8.0
Parameters: ~ Parameters: ~
• {file} (`string?`) Path • {file} (`string?`) Path
@ -2919,6 +2922,9 @@ vim.fs.basename({file}) *vim.fs.basename()*
vim.fs.dir({path}, {opts}) *vim.fs.dir()* vim.fs.dir({path}, {opts}) *vim.fs.dir()*
Return an iterator over the items located in {path} Return an iterator over the items located in {path}
Attributes: ~
Since: 0.8.0
Parameters: ~ Parameters: ~
• {path} (`string`) An absolute or relative path to the directory to • {path} (`string`) An absolute or relative path to the directory to
iterate over. The path is first normalized iterate over. The path is first normalized
@ -2938,6 +2944,9 @@ vim.fs.dir({path}, {opts}) *vim.fs.dir()*
vim.fs.dirname({file}) *vim.fs.dirname()* vim.fs.dirname({file}) *vim.fs.dirname()*
Return the parent directory of the given path Return the parent directory of the given path
Attributes: ~
Since: 0.8.0
Parameters: ~ Parameters: ~
• {file} (`string?`) Path • {file} (`string?`) Path
@ -2970,6 +2979,9 @@ vim.fs.find({names}, {opts}) *vim.fs.find()*
end, {limit = math.huge, type = 'file'}) end, {limit = math.huge, type = 'file'})
< <
Attributes: ~
Since: 0.8.0
Parameters: ~ Parameters: ~
• {names} (`string|string[]|fun(name: string, path: string): boolean`) • {names} (`string|string[]|fun(name: string, path: string): boolean`)
Names of the items to find. Must be base names, paths and Names of the items to find. Must be base names, paths and
@ -3001,6 +3013,9 @@ vim.fs.joinpath({...}) *vim.fs.joinpath()*
Concatenate directories and/or file paths into a single path with Concatenate directories and/or file paths into a single path with
normalization (e.g., `"foo/"` and `"bar"` get joined to `"foo/bar"`) normalization (e.g., `"foo/"` and `"bar"` get joined to `"foo/bar"`)
Attributes: ~
Since: 0.10.0
Parameters: ~ Parameters: ~
• {...} (`string`) • {...} (`string`)
@ -3037,6 +3052,9 @@ vim.fs.normalize({path}, {opts}) *vim.fs.normalize()*
[[\\?\UNC\server\share\foo\..\..\..\bar]] => "//?/UNC/server/share/bar" [[\\?\UNC\server\share\foo\..\..\..\bar]] => "//?/UNC/server/share/bar"
< <
Attributes: ~
Since: 0.8.0
Parameters: ~ Parameters: ~
• {path} (`string`) Path to normalize • {path} (`string`) Path to normalize
• {opts} (`table?`) A table with the following fields: • {opts} (`table?`) A table with the following fields:
@ -3065,6 +3083,9 @@ vim.fs.parents({start}) *vim.fs.parents()*
end end
< <
Attributes: ~
Since: 0.8.0
Parameters: ~ Parameters: ~
• {start} (`string`) Initial path. • {start} (`string`) Initial path.
@ -3074,6 +3095,8 @@ vim.fs.parents({start}) *vim.fs.parents()*
(`string?`) (`string?`)
vim.fs.rm({path}, {opts}) *vim.fs.rm()* vim.fs.rm({path}, {opts}) *vim.fs.rm()*
WARNING: This feature is experimental/unstable.
Remove files or directories Remove files or directories
Parameters: ~ Parameters: ~
@ -3103,6 +3126,9 @@ vim.fs.root({source}, {marker}) *vim.fs.root()*
end) end)
< <
Attributes: ~
Since: 0.10.0
Parameters: ~ Parameters: ~
• {source} (`integer|string`) Buffer number (0 for current buffer) or • {source} (`integer|string`) Buffer number (0 for current buffer) or
file path (absolute or relative to the |current-directory|) file path (absolute or relative to the |current-directory|)

View File

@ -25,6 +25,7 @@ local os_sep = iswin and '\\' or '/'
--- end --- end
--- ``` --- ```
--- ---
---@since 10
---@param start (string) Initial path. ---@param start (string) Initial path.
---@return fun(_, dir: string): string? # Iterator ---@return fun(_, dir: string): string? # Iterator
---@return nil ---@return nil
@ -44,6 +45,7 @@ end
--- Return the parent directory of the given path --- Return the parent directory of the given path
--- ---
---@since 10
---@generic T : string|nil ---@generic T : string|nil
---@param file T Path ---@param file T Path
---@return T Parent directory of {file} ---@return T Parent directory of {file}
@ -73,6 +75,7 @@ end
--- Return the basename of the given path --- Return the basename of the given path
--- ---
---@since 10
---@generic T : string|nil ---@generic T : string|nil
---@param file T Path ---@param file T Path
---@return T Basename of {file} ---@return T Basename of {file}
@ -93,6 +96,7 @@ end
--- Concatenate directories and/or file paths into a single path with normalization --- Concatenate directories and/or file paths into a single path with normalization
--- (e.g., `"foo/"` and `"bar"` get joined to `"foo/bar"`) --- (e.g., `"foo/"` and `"bar"` get joined to `"foo/bar"`)
--- ---
---@since 12
---@param ... string ---@param ... string
---@return string ---@return string
function M.joinpath(...) function M.joinpath(...)
@ -103,6 +107,7 @@ end
--- Return an iterator over the items located in {path} --- Return an iterator over the items located in {path}
--- ---
---@since 10
---@param path (string) An absolute or relative path to the directory to iterate ---@param path (string) An absolute or relative path to the directory to iterate
--- over. The path is first normalized |vim.fs.normalize()|. --- over. The path is first normalized |vim.fs.normalize()|.
--- @param opts table|nil Optional keyword arguments: --- @param opts table|nil Optional keyword arguments:
@ -214,6 +219,7 @@ end
--- end, {limit = math.huge, type = 'file'}) --- end, {limit = math.huge, type = 'file'})
--- ``` --- ```
--- ---
---@since 10
---@param names (string|string[]|fun(name: string, path: string): boolean) Names of the items to find. ---@param names (string|string[]|fun(name: string, path: string): boolean) Names of the items to find.
--- Must be base names, paths and globs are not supported when {names} is a string or a table. --- Must be base names, paths and globs are not supported when {names} is a string or a table.
--- If {names} is a function, it is called for each traversed item with args: --- If {names} is a function, it is called for each traversed item with args:
@ -353,6 +359,7 @@ end
--- end) --- end)
--- ``` --- ```
--- ---
--- @since 12
--- @param source integer|string Buffer number (0 for current buffer) or file path (absolute or --- @param source integer|string Buffer number (0 for current buffer) or file path (absolute or
--- relative to the |current-directory|) to begin the search from. --- relative to the |current-directory|) to begin the search from.
--- @param marker (string|string[]|fun(name: string, path: string): boolean) A marker, or list --- @param marker (string|string[]|fun(name: string, path: string): boolean) A marker, or list
@ -532,6 +539,7 @@ end
--- [[\\?\UNC\server\share\foo\..\..\..\bar]] => "//?/UNC/server/share/bar" --- [[\\?\UNC\server\share\foo\..\..\..\bar]] => "//?/UNC/server/share/bar"
--- ``` --- ```
--- ---
---@since 10
---@param path (string) Path to normalize ---@param path (string) Path to normalize
---@param opts? vim.fs.normalize.Opts ---@param opts? vim.fs.normalize.Opts
---@return (string) : Normalized path ---@return (string) : Normalized path
@ -651,6 +659,7 @@ end
--- @field force? boolean --- @field force? boolean
--- Remove files or directories --- Remove files or directories
--- @since 13
--- @param path string Path to remove --- @param path string Path to remove
--- @param opts? vim.fs.rm.Opts --- @param opts? vim.fs.rm.Opts
function M.rm(path, opts) function M.rm(path, opts)

View File

@ -20,6 +20,7 @@ end
-- Map of api_level:version, by inspection of: -- Map of api_level:version, by inspection of:
-- :lua= vim.mpack.decode(vim.fn.readfile('test/functional/fixtures/api_level_9.mpack','B')).version -- :lua= vim.mpack.decode(vim.fn.readfile('test/functional/fixtures/api_level_9.mpack','B')).version
M.version_level = { M.version_level = {
[13] = '0.11.0',
[12] = '0.10.0', [12] = '0.10.0',
[11] = '0.9.0', [11] = '0.9.0',
[10] = '0.8.0', [10] = '0.8.0',