docs: support @since for api level #25574

close #25416

3 files changed, 53 insertions, 5 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 3cbadb9bdb..5e97628f42 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1468,13 +1468,15 @@ Lua module: vim.lsp.inlay_hint                                *lsp-inlay_hint*
 enable({bufnr}, {enable})                        *vim.lsp.inlay_hint.enable()*
     Enable/disable/toggle inlay hints for a buffer
 
+    Note: ~
+        This API is pre-release (unstable).
+
     Parameters: ~
       • {bufnr}   (integer|nil) Buffer handle, or 0 or nil for current
       • {enable}  (boolean|nil) true/nil to enable, false to disable
 
 get({filter})                                       *vim.lsp.inlay_hint.get()*
-    Get the list of inlay hints, (optionally) restricted by buffer, client, or
-    range.
+    Get the list of inlay hints, (optionally) restricted by buffer or range.
 
     Example usage: >lua
         local hint = vim.lsp.inlay_hint.get({ bufnr = 0 })[1] -- 0 for current buffer
@@ -1490,6 +1492,9 @@ get({filter})                                       *vim.lsp.inlay_hint.get()*
         })
 <
 
+    Note: ~
+        This API is pre-release (unstable).
+
     Parameters: ~
       • {filter}  vim.lsp.inlay_hint.get.filter ? Optional filters |kwargs|:
                   • bufnr (integer?): 0 for current buffer
@@ -1502,6 +1507,9 @@ get({filter})                                       *vim.lsp.inlay_hint.get()*
         • inlay_hint (lsp.InlayHint)
 
 is_enabled({bufnr})                          *vim.lsp.inlay_hint.is_enabled()*
+    Note: ~
+        This API is pre-release (unstable).
+
     Parameters: ~
       • {bufnr}  (integer|nil) Buffer handle, or 0 or nil for current
 
diff --git a/runtime/lua/vim/lsp/inlay_hint.lua b/runtime/lua/vim/lsp/inlay_hint.lua
index cdda5dcc17..4f7a3b0076 100644
--- a/runtime/lua/vim/lsp/inlay_hint.lua
+++ b/runtime/lua/vim/lsp/inlay_hint.lua
@@ -107,7 +107,7 @@ end
 --- @field client_id integer
 --- @field inlay_hint lsp.InlayHint
 
---- Get the list of inlay hints, (optionally) restricted by buffer, client, or range.
+--- Get the list of inlay hints, (optionally) restricted by buffer or range.
 ---
 --- Example usage:
 ---
@@ -135,6 +135,8 @@ end
 ---  - bufnr (integer)
 ---  - client_id (integer)
 ---  - inlay_hint (lsp.InlayHint)
+---
+--- @since 12
 function M.get(filter)
   vim.validate({ filter = { filter, 'table', true } })
   filter = filter or {}
@@ -349,6 +351,7 @@ api.nvim_set_decoration_provider(namespace, {
 
 --- @param bufnr (integer|nil) Buffer handle, or 0 or nil for current
 --- @return boolean
+--- @since 12
 function M.is_enabled(bufnr)
   vim.validate({ bufnr = { bufnr, 'number', true } })
   if bufnr == nil or bufnr == 0 then
@@ -361,6 +364,7 @@ end
 ---
 --- @param bufnr (integer|nil) Buffer handle, or 0 or nil for current
 --- @param enable (boolean|nil) true/nil to enable, false to disable
+--- @since 12
 function M.enable(bufnr, enable)
   vim.validate({ enable = { enable, 'boolean', true }, bufnr = { bufnr, 'number', true } })
   if enable == false then
diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index 925e6f98e6..8ed88cb8f5 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -42,6 +42,7 @@ import subprocess
 import collections
 import msgpack
 import logging
+from typing import Tuple
 from pathlib import Path
 
 from xml.dom import minidom
@@ -363,6 +364,30 @@ annotation_map = {
 }
 
 
+def nvim_api_info() -> Tuple[int, bool]:
+    """Returns NVIM_API_LEVEL, NVIM_API_PRERELEASE from CMakeLists.txt"""
+    if not hasattr(nvim_api_info, 'LEVEL'):
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        cmake_file_path = os.path.join(script_dir, '..', 'CMakeLists.txt')
+        with open(cmake_file_path, 'r') as cmake_file:
+            cmake_content = cmake_file.read()
+
+        api_level_match = re.search(r'set\(NVIM_API_LEVEL (\d+)\)', cmake_content)
+        api_prerelease_match = re.search(
+            r'set\(NVIM_API_PRERELEASE (\w+)\)', cmake_content
+        )
+
+        if not api_level_match or not api_prerelease_match:
+            raise RuntimeError(
+                'Could not find NVIM_API_LEVEL or NVIM_API_PRERELEASE in CMakeLists.txt'
+            )
+
+        nvim_api_info.LEVEL = int(api_level_match.group(1))
+        nvim_api_info.PRERELEASE = api_prerelease_match.group(1).lower() == 'true'
+
+    return nvim_api_info.LEVEL, nvim_api_info.PRERELEASE
+
+
 # Raises an error with details about `o`, if `cond` is in object `o`,
 # or if `cond()` is callable and returns True.
 def debug_this(o, cond=True):
@@ -691,6 +716,7 @@ def para_as_map(parent, indent='', width=text_width - indentation, fmt_vimhelp=F
         'params': collections.OrderedDict(),
         'return': [],
         'seealso': [],
+        'prerelease': False,
         'xrefs': []
     }
 
@@ -729,6 +755,14 @@ def para_as_map(parent, indent='', width=text_width - indentation, fmt_vimhelp=F
                 elif kind == 'warning':
                     text += render_node(child, text, indent=indent,
                                         width=width, fmt_vimhelp=fmt_vimhelp)
+                elif kind == 'since':
+                    since_match = re.match(r'^(\d+)', get_text(child))
+                    since = int(since_match.group(1)) if since_match else 0
+                    NVIM_API_LEVEL, NVIM_API_PRERELEASE = nvim_api_info()
+                    if since > NVIM_API_LEVEL or (
+                        since == NVIM_API_LEVEL and NVIM_API_PRERELEASE
+                    ):
+                        chunks['prerelease'] = True
                 else:
                     raise RuntimeError('unhandled simplesect: {}\n{}'.format(
                         child.nodeName, child.toprettyxml(indent='  ', newl='\n')))
@@ -837,9 +871,11 @@ def fmt_node_as_vimhelp(parent: Element, width=text_width - indentation, indent=
 
         # Generate text from the gathered items.
         chunks = [para['text']]
-        if len(para['note']) > 0:
+        notes = ["    This API is pre-release (unstable)."] if para['prerelease'] else []
+        notes += para['note']
+        if len(notes) > 0:
             chunks.append('\nNote: ~')
-            for s in para['note']:
+            for s in notes:
                 chunks.append(s)
         if len(para['params']) > 0 and has_nonexcluded_params(para['params']):
             chunks.append('\nParameters: ~')