From 825bfba789d924ab2f33b3e87814750863ff4f02 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Sat, 25 Apr 2026 17:16:45 +0200
Subject: [PATCH] docs: lsp.CodeActionContext, nested `@inlinedoc`

- fix https://github.com/neovim/neovim/issues/39208
- fix generation of neste `@inlinedoc` classes
---
 runtime/doc/lsp.txt         | 18 +++++++++---------
 runtime/lua/vim/lsp/buf.lua | 22 ++++++++++++++--------
 runtime/lua/vim/ui.lua      |  7 ++++---
 src/gen/gen_vimdoc.lua      |  8 ++++++++
 4 files changed, 35 insertions(+), 20 deletions(-)

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 59ddd86654..6f5f806b8f 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1480,15 +1480,15 @@ code_action({opts})                                *vim.lsp.buf.code_action()*
 
     Parameters: ~
       • {opts}  (`table?`) A table with the following fields:
-                • {context}? (`lsp.CodeActionContext`) Corresponds to
-                  `CodeActionContext` of the LSP specification:
-                  • {diagnostics}? (`table`) LSP `Diagnostic[]`. Inferred from
-                    the current position if not provided.
-                  • {only}? (`table`) List of LSP `CodeActionKind`s used to
-                    filter the code actions. Most language servers support
-                    values like `refactor` or `quickfix`.
-                  • {triggerKind}? (`integer`) The reason why code actions
-                    were requested.
+                • {context}? (`table`) Corresponds to `lsp.CodeActionContext`,
+                  but all fields are optional:
+                  • {diagnostics}? (`lsp.Diagnostic[]`) Inferred from the
+                    current position if not provided.
+                  • {only}? (`lsp.CodeActionKind[]`) `CodeActionKind`s used to
+                    filter the code actions. Most servers support values like
+                    "refactor" or "quickfix".
+                  • {triggerKind}? (`lsp.CodeActionTriggerKind`) Why code
+                    actions were requested.
                 • {filter}?
                   (`fun(x: lsp.CodeAction|lsp.Command, client_id: integer):boolean`)
                   Predicate taking a code action or command and the provider's
diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua
index 926d82c986..68cecb3df0 100644
--- a/runtime/lua/vim/lsp/buf.lua
+++ b/runtime/lua/vim/lsp/buf.lua
@@ -1125,17 +1125,23 @@ end
 ---@field result? (lsp.Command|lsp.CodeAction)[]
 ---@field context lsp.HandlerContext
 
+--- Corresponds to `lsp.CodeActionContext`, but all fields are optional:
+--- @class vim.lsp.buf.code_action.context : lsp.CodeActionContext
+--- @inlinedoc
+---
+--- Inferred from the current position if not provided.
+--- @field diagnostics? lsp.Diagnostic[]
+---
+--- `CodeActionKind`s used to filter the code actions. Most servers support values like "refactor" or "quickfix".
+--- @field only? lsp.CodeActionKind[]
+---
+--- Why code actions were requested.
+--- @field triggerKind? lsp.CodeActionTriggerKind
+
 --- @class vim.lsp.buf.code_action.Opts
 --- @inlinedoc
 ---
---- Corresponds to `CodeActionContext` of the LSP specification:
----   - {diagnostics}? (`table`) LSP `Diagnostic[]`. Inferred from the current
----     position if not provided.
----   - {only}? (`table`) List of LSP `CodeActionKind`s used to filter the code actions.
----     Most language servers support values like `refactor`
----     or `quickfix`.
----   - {triggerKind}? (`integer`) The reason why code actions were requested.
---- @field context? lsp.CodeActionContext
+--- @field context? vim.lsp.buf.code_action.context
 ---
 --- Predicate taking a code action or command and the provider's ID.
 --- If it returns false, the action is filtered out.
diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua
index 89133697b3..bf4728c4d8 100644
--- a/runtime/lua/vim/ui.lua
+++ b/runtime/lua/vim/ui.lua
@@ -3,11 +3,12 @@ local M = {}
 ---@class vim.ui.select.Opts
 ---@inlinedoc
 ---
---- Text of the prompt. Defaults to `Select one of:`
+--- Text of the prompt.
+--- (default: `Select one of:`)
 ---@field prompt? string
 ---
---- Function to format an
---- individual item from `items`. Defaults to `tostring`.
+--- Formats an individual item from `items`.
+--- (default: `tostring`)
 ---@field format_item? fun(item: any):string
 ---
 --- Function to preview an individual item from `items`.
diff --git a/src/gen/gen_vimdoc.lua b/src/gen/gen_vimdoc.lua
index f96cc32605..204187cb3e 100755
--- a/src/gen/gen_vimdoc.lua
+++ b/src/gen/gen_vimdoc.lua
@@ -556,6 +556,9 @@ local function get_class(ty, classes)
   return classes[cty]
 end
 
+--- Recursively resolves `@inlinedoc` classes: replaces the type with "table" and expands class
+--- fields into the object's description.
+---
 --- @param obj nvim.luacats.parser.param|nvim.luacats.parser.return|nvim.luacats.parser.field
 --- @param classes? table<string,nvim.luacats.parser.class>
 local function inline_type(obj, classes)
@@ -610,7 +613,12 @@ local function inline_type(obj, classes)
   local desc_append = {}
   for _, f in ipairs(cls.fields) do
     if not f.access then
+      inline_type(f, classes)
       local fdesc, default = get_default(f.desc)
+      if fdesc then
+        -- Indent nested list items from recursive inlining.
+        fdesc = fdesc:gsub('\n(%- {)', '\n  %1')
+      end
       local fty = render_type(f.type, nil, default)
       local fnm = fmt_field_name(f.name)
       table.insert(desc_append, table.concat({ '-', fnm, fty, fdesc }, ' '))