docs: more `@since` annotations #30660

4 files changed, 38 insertions, 2 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 14bc18931e..0100146274 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -146,9 +146,9 @@ set(NVIM_VERSION_PATCH 0)
 set(NVIM_VERSION_PRERELEASE "-dev") # for package maintainers
 
 # 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_PRERELEASE false)
+set(NVIM_API_PRERELEASE true)
 
 # Build-type: RelWithDebInfo
 # /Og means something different in MSVC
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index fbd8da93bc..de0c6f27b5 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2910,6 +2910,9 @@ Lua module: vim.fs                                                    *vim.fs*
 vim.fs.basename({file})                                    *vim.fs.basename()*
     Return the basename of the given path
 
+    Attributes: ~
+        Since: 0.8.0
+
     Parameters: ~
       • {file}  (`string?`) Path
 
@@ -2919,6 +2922,9 @@ vim.fs.basename({file})                                    *vim.fs.basename()*
 vim.fs.dir({path}, {opts})                                      *vim.fs.dir()*
     Return an iterator over the items located in {path}
 
+    Attributes: ~
+        Since: 0.8.0
+
     Parameters: ~
       • {path}  (`string`) An absolute or relative path to the directory to
                 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()*
     Return the parent directory of the given path
 
+    Attributes: ~
+        Since: 0.8.0
+
     Parameters: ~
       • {file}  (`string?`) Path
 
@@ -2970,6 +2979,9 @@ vim.fs.find({names}, {opts})                                   *vim.fs.find()*
         end, {limit = math.huge, type = 'file'})
 <
 
+    Attributes: ~
+        Since: 0.8.0
+
     Parameters: ~
       • {names}  (`string|string[]|fun(name: string, path: string): boolean`)
                  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
     normalization (e.g., `"foo/"` and `"bar"` get joined to `"foo/bar"`)
 
+    Attributes: ~
+        Since: 0.10.0
+
     Parameters: ~
       • {...}  (`string`)
 
@@ -3037,6 +3052,9 @@ vim.fs.normalize({path}, {opts})                          *vim.fs.normalize()*
         [[\\?\UNC\server\share\foo\..\..\..\bar]] => "//?/UNC/server/share/bar"
 <
 
+    Attributes: ~
+        Since: 0.8.0
+
     Parameters: ~
       • {path}  (`string`) Path to normalize
       • {opts}  (`table?`) A table with the following fields:
@@ -3065,6 +3083,9 @@ vim.fs.parents({start})                                     *vim.fs.parents()*
         end
 <
 
+    Attributes: ~
+        Since: 0.8.0
+
     Parameters: ~
       • {start}  (`string`) Initial path.
 
@@ -3074,6 +3095,8 @@ vim.fs.parents({start})                                     *vim.fs.parents()*
         (`string?`)
 
 vim.fs.rm({path}, {opts})                                        *vim.fs.rm()*
+    WARNING: This feature is experimental/unstable.
+
     Remove files or directories
 
     Parameters: ~
@@ -3103,6 +3126,9 @@ vim.fs.root({source}, {marker})                                *vim.fs.root()*
         end)
 <
 
+    Attributes: ~
+        Since: 0.10.0
+
     Parameters: ~
       • {source}  (`integer|string`) Buffer number (0 for current buffer) or
                   file path (absolute or relative to the |current-directory|)
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index 0d2e2f907f..ccddf826f7 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -25,6 +25,7 @@ local os_sep = iswin and '\\' or '/'
 --- end
 --- ```
 ---
+---@since 10
 ---@param start (string) Initial path.
 ---@return fun(_, dir: string): string? # Iterator
 ---@return nil
@@ -44,6 +45,7 @@ end
 
 --- Return the parent directory of the given path
 ---
+---@since 10
 ---@generic T : string|nil
 ---@param file T Path
 ---@return T Parent directory of {file}
@@ -73,6 +75,7 @@ end
 
 --- Return the basename of the given path
 ---
+---@since 10
 ---@generic T : string|nil
 ---@param file T Path
 ---@return T Basename of {file}
@@ -93,6 +96,7 @@ end
 --- Concatenate directories and/or file paths into a single path with normalization
 --- (e.g., `"foo/"` and `"bar"` get joined to `"foo/bar"`)
 ---
+---@since 12
 ---@param ... string
 ---@return string
 function M.joinpath(...)
@@ -103,6 +107,7 @@ end
 
 --- Return an iterator over the items located in {path}
 ---
+---@since 10
 ---@param path (string) An absolute or relative path to the directory to iterate
 ---            over. The path is first normalized |vim.fs.normalize()|.
 --- @param opts table|nil Optional keyword arguments:
@@ -214,6 +219,7 @@ end
 --- end, {limit = math.huge, type = 'file'})
 --- ```
 ---
+---@since 10
 ---@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.
 ---             If {names} is a function, it is called for each traversed item with args:
@@ -353,6 +359,7 @@ end
 --- end)
 --- ```
 ---
+--- @since 12
 --- @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.
 --- @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"
 --- ```
 ---
+---@since 10
 ---@param path (string) Path to normalize
 ---@param opts? vim.fs.normalize.Opts
 ---@return (string) : Normalized path
@@ -651,6 +659,7 @@ end
 --- @field force? boolean
 
 --- Remove files or directories
+--- @since 13
 --- @param path string Path to remove
 --- @param opts? vim.fs.rm.Opts
 function M.rm(path, opts)
diff --git a/scripts/util.lua b/scripts/util.lua
index 94598c32a6..6343ad4b21 100644
--- a/scripts/util.lua
+++ b/scripts/util.lua
@@ -20,6 +20,7 @@ end
 -- Map of api_level:version, by inspection of:
 --    :lua= vim.mpack.decode(vim.fn.readfile('test/functional/fixtures/api_level_9.mpack','B')).version
 M.version_level = {
+  [13] = '0.11.0',
   [12] = '0.10.0',
   [11] = '0.9.0',
   [10] = '0.8.0',