From 9fa9b3cad94a1ea7fced128fed2cd5ac3ff7bc44 Mon Sep 17 00:00:00 2001 From: LW Date: Mon, 27 Nov 2023 08:23:04 -0800 Subject: [PATCH] docs: support @since for api level #25574 close #25416 --- runtime/doc/lsp.txt | 12 +++++++-- runtime/lua/vim/lsp/inlay_hint.lua | 6 ++++- scripts/gen_vimdoc.py | 40 ++++++++++++++++++++++++++++-- 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: ~')