docs: render `@since` versions, 0 means experimental #30649

An implication of this current approach is that `NVIM_API_LEVEL` should be
bumped when a new Lua function is added.

TODO(future): add a lint check which requires `@since` on all new functions.

ref #25416

5 files changed, 74 insertions, 2 deletions

diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 9dbdaec31c..ee7fa808f2 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -247,6 +247,10 @@ Docstring format:
 - References are written as `[tag]`
 - Use ``` for code samples.
   Code samples can be annotated as `vim` or `lua`
+- Use `@since <api-level>` to note the |api-level| when the function became
+  "stable". If `<api-level>` is greater than the current stable release (or
+  0), it is marked as "experimental".
+  - See scripts/util.lua for the mapping of api-level to Nvim version.
 - Use `@nodoc` to prevent documentation generation.
 - Use `@inlinedoc` to inline `@class` blocks into `@param` blocks.
   E.g. >lua
@@ -271,7 +275,7 @@ Docstring format:
                       - {somefield}? (integer) Documentation
                         for some field
 <
-- Files which has `@meta` are only used for typing and documentation.
+- Files declared as `@meta` are only used for typing and documentation (similar to "*.d.ts" typescript files).
 
 Example: the help for |vim.paste()| is generated from a docstring decorating
 vim.paste in runtime/lua/vim/_editor.lua like this: >
@@ -288,6 +292,7 @@ vim.paste in runtime/lua/vim/_editor.lua like this: >
     --- end)()
     --- ```
     ---
+    --- @since 12
     --- @see |paste|
     ---
     --- @param lines  ...
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index bf931ed711..342947595e 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -733,6 +733,9 @@ hide({namespace}, {bufnr})                             *vim.diagnostic.hide()*
 is_enabled({filter})                             *vim.diagnostic.is_enabled()*
     Check whether diagnostics are enabled.
 
+    Attributes: ~
+        Since: 0.10.0
+
     Parameters: ~
       • {filter}  (`table?`) Optional filters |kwargs|, or `nil` for all.
                   • {ns_id}? (`integer`) Diagnostic namespace, or `nil` for
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index e06d400b63..47d8e190d4 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1673,6 +1673,9 @@ enable({enable}, {filter})                       *vim.lsp.inlay_hint.enable()*
         vim.lsp.inlay_hint.enable(not vim.lsp.inlay_hint.is_enabled())
 <
 
+    Attributes: ~
+        Since: 0.10.0
+
     Parameters: ~
       • {enable}  (`boolean?`) true/nil to enable, false to disable
       • {filter}  (`table?`) Optional filters |kwargs|, or `nil` for all.
@@ -1697,6 +1700,9 @@ get({filter})                                       *vim.lsp.inlay_hint.get()*
         })
 <
 
+    Attributes: ~
+        Since: 0.10.0
+
     Parameters: ~
       • {filter}  (`table?`) Optional filters |kwargs|:
                   • {bufnr} (`integer?`)
@@ -1711,6 +1717,9 @@ get({filter})                                       *vim.lsp.inlay_hint.get()*
 is_enabled({filter})                         *vim.lsp.inlay_hint.is_enabled()*
     Query whether inlay hint is enabled in the {filter}ed scope
 
+    Attributes: ~
+        Since: 0.10.0
+
     Parameters: ~
       • {filter}  (`table?`) Optional filters |kwargs|, or `nil` for all.
                   • {bufnr} (`integer?`) Buffer number, or 0 for current
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 6269eb0c5b..fbd8da93bc 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1103,7 +1103,9 @@ vim.stricmp({a}, {b})                                          *vim.stricmp()*
         lesser than {b}, respectively.
 
 vim.ui_attach({ns}, {options}, {callback})                   *vim.ui_attach()*
-    Attach to ui events, similar to |nvim_ui_attach()| but receive events as
+    WARNING: This feature is experimental/unstable.
+
+    Attach to |ui-events|, similar to |nvim_ui_attach()| but receive events as
     Lua callback. Can be used to implement screen elements like popupmenu or
     message handling in Lua.
 
@@ -1856,6 +1858,9 @@ vim.inspect_pos({bufnr}, {row}, {col}, {filter})           *vim.inspect_pos()*
 
     Can also be pretty-printed with `:Inspect!`.                   *:Inspect!*
 
+    Attributes: ~
+        Since: 0.9.0
+
     Parameters: ~
       • {bufnr}   (`integer?`) defaults to the current buffer
       • {row}     (`integer?`) row to inspect, 0-based. Defaults to the row of
@@ -1889,6 +1894,9 @@ vim.show_pos({bufnr}, {row}, {col}, {filter})                 *vim.show_pos()*
 
     Can also be shown with `:Inspect`.                              *:Inspect*
 
+    Attributes: ~
+        Since: 0.9.0
+
     Parameters: ~
       • {bufnr}   (`integer?`) defaults to the current buffer
       • {row}     (`integer?`) row to inspect, 0-based. Defaults to the row of
@@ -2461,11 +2469,15 @@ vim.validate({opt})                                           *vim.validate()*
 Lua module: vim.loader                                            *vim.loader*
 
 vim.loader.disable()                                    *vim.loader.disable()*
+    WARNING: This feature is experimental/unstable.
+
     Disables the experimental Lua module loader:
     • removes the loaders
     • adds the default Nvim loader
 
 vim.loader.enable()                                      *vim.loader.enable()*
+    WARNING: This feature is experimental/unstable.
+
     Enables the experimental Lua module loader:
     • overrides loadfile
     • adds the Lua loader using the byte-compilation cache
@@ -2473,6 +2485,8 @@ vim.loader.enable()                                      *vim.loader.enable()*
     • removes the default Nvim loader
 
 vim.loader.find({modname}, {opts})                         *vim.loader.find()*
+    WARNING: This feature is experimental/unstable.
+
     Finds Lua modules for the given module name.
 
     Parameters: ~
@@ -2498,6 +2512,8 @@ vim.loader.find({modname}, {opts})                         *vim.loader.find()*
           returned for `modname="*"`
 
 vim.loader.reset({path})                                  *vim.loader.reset()*
+    WARNING: This feature is experimental/unstable.
+
     Resets the cache for the path, or all the paths if path is nil.
 
     Parameters: ~
@@ -2767,6 +2783,9 @@ vim.filetype.get_option({filetype}, {option})
     means |ftplugin| and |FileType| autocommands are only triggered once and
     may not reflect later changes.
 
+    Attributes: ~
+        Since: 0.9.0
+
     Parameters: ~
       • {filetype}  (`string`) Filetype
       • {option}    (`string`) Option name
@@ -3649,6 +3668,9 @@ vim.secure.read({path})                                    *vim.secure.read()*
     be trusted. The user's choice is persisted in a trust database at
     $XDG_STATE_HOME/nvim/trust.
 
+    Attributes: ~
+        Since: 0.9.0
+
     Parameters: ~
       • {path}  (`string`) Path to a file to read.
 
@@ -3664,6 +3686,9 @@ vim.secure.trust({opts})                                  *vim.secure.trust()*
 
     The trust database is located at |$XDG_STATE_HOME|/nvim/trust.
 
+    Attributes: ~
+        Since: 0.9.0
+
     Parameters: ~
       • {opts}  (`table`) A table with the following fields:
                 • {action} (`'allow'|'deny'|'remove'`) - `'allow'` to add a
@@ -3755,6 +3780,9 @@ vim.version.cmp({v1}, {v2})                                *vim.version.cmp()*
       • Per semver, build metadata is ignored when comparing two
         otherwise-equivalent versions.
 
+    Attributes: ~
+        Since: 0.9.0
+
     Parameters: ~
       • {v1}  (`vim.Version|number[]|string`) Version object.
       • {v2}  (`vim.Version|number[]|string`) Version to compare with `v1`.
@@ -3766,6 +3794,9 @@ vim.version.eq({v1}, {v2})                                  *vim.version.eq()*
     Returns `true` if the given versions are equal. See |vim.version.cmp()|
     for usage.
 
+    Attributes: ~
+        Since: 0.9.0
+
     Parameters: ~
       • {v1}  (`vim.Version|number[]|string`)
       • {v2}  (`vim.Version|number[]|string`)
@@ -3776,6 +3807,9 @@ vim.version.eq({v1}, {v2})                                  *vim.version.eq()*
 vim.version.ge({v1}, {v2})                                  *vim.version.ge()*
     Returns `true` if `v1 >= v2`. See |vim.version.cmp()| for usage.
 
+    Attributes: ~
+        Since: 0.10.0
+
     Parameters: ~
       • {v1}  (`vim.Version|number[]|string`)
       • {v2}  (`vim.Version|number[]|string`)
@@ -3786,6 +3820,9 @@ vim.version.ge({v1}, {v2})                                  *vim.version.ge()*
 vim.version.gt({v1}, {v2})                                  *vim.version.gt()*
     Returns `true` if `v1 > v2`. See |vim.version.cmp()| for usage.
 
+    Attributes: ~
+        Since: 0.9.0
+
     Parameters: ~
       • {v1}  (`vim.Version|number[]|string`)
       • {v2}  (`vim.Version|number[]|string`)
@@ -3805,6 +3842,9 @@ vim.version.last({versions})                              *vim.version.last()*
 vim.version.le({v1}, {v2})                                  *vim.version.le()*
     Returns `true` if `v1 <= v2`. See |vim.version.cmp()| for usage.
 
+    Attributes: ~
+        Since: 0.10.0
+
     Parameters: ~
       • {v1}  (`vim.Version|number[]|string`)
       • {v2}  (`vim.Version|number[]|string`)
@@ -3815,6 +3855,9 @@ vim.version.le({v1}, {v2})                                  *vim.version.le()*
 vim.version.lt({v1}, {v2})                                  *vim.version.lt()*
     Returns `true` if `v1 < v2`. See |vim.version.cmp()| for usage.
 
+    Attributes: ~
+        Since: 0.9.0
+
     Parameters: ~
       • {v1}  (`vim.Version|number[]|string`)
       • {v2}  (`vim.Version|number[]|string`)
@@ -3829,6 +3872,9 @@ vim.version.parse({version}, {opts})                     *vim.version.parse()*
         { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" }
 <
 
+    Attributes: ~
+        Since: 0.9.0
+
     Parameters: ~
       • {version}  (`string`) Version string to parse.
       • {opts}     (`table?`) Optional keyword arguments:
@@ -3869,6 +3915,9 @@ vim.version.range({spec})                                *vim.version.range()*
         print(vim.version.ge({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to))
 <
 
+    Attributes: ~
+        Since: 0.9.0
+
     Parameters: ~
       • {spec}  (`string`) Version range "spec"
 
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 0712f1f856..35192cc43d 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -854,6 +854,9 @@ foldexpr({lnum})                                   *vim.treesitter.foldexpr()*
         vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'
 <
 
+    Attributes: ~
+        Since: 0.9.0
+
     Parameters: ~
       • {lnum}  (`integer?`) Line number to calculate fold level for
 
@@ -1003,6 +1006,9 @@ inspect_tree({opts})                           *vim.treesitter.inspect_tree()*
 
     Can also be shown with `:InspectTree`.                      *:InspectTree*
 
+    Attributes: ~
+        Since: 0.9.0
+
     Parameters: ~
       • {opts}  (`table?`) Optional options table with the following possible
                 keys: