Skip to content

Commit 9cf71e0

Browse files
wbthomasonwbthomason
committed
Generate docs
1 parent 5a7b811 commit 9cf71e0

File tree

4 files changed

+308
-0
lines changed

4 files changed

+308
-0
lines changed

‎doc/lsp-status.txt

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
*lsp-status.txt* Extract PDF information and annotations to plain-text notes
2+
*lsp-status.nvim*
3+
*lsp-status.nvim*
4+
5+
Author: Wil Thomason <[email protected]>
6+
7+
CONTENTS *lsp-status-contents*
8+
Introduction |lsp-status-introduction|
9+
Requirements |lsp-status-intro-requirements|
10+
Features |lsp-status-intro-features|
11+
Usage |lsp-status-usage|
12+
API |lsp-status-api|
13+
==============================================================================
14+
INTRODUCTION *lsp-status-introduction*
15+
16+
This is a Neovim plugin/library for generating statusline components from the
17+
built-in LSP client.
18+
19+
==============================================================================
20+
REQUIREMENTS *lsp-status-intro-requirements*
21+
22+
You need to be running a version of Neovim recent enough to have the native
23+
LSP client included. It's also recommended to use
24+
https://github.com/neovim/nvim-lsp.
25+
26+
==============================================================================
27+
FEATURES *lsp-status-intro-features*
28+
29+
- Handle `$/progress` LSP messages
30+
- Convenience function for getting all LSP diagnostics in a single call
31+
- Track current enclosing function symbol
32+
- Handle the message and file status protocol extensions from `pyls_ms` and
33+
`clangd`
34+
- An out of the box statusline component displaying all this information
35+
36+
==============================================================================
37+
USAGE *lsp-status-usage*
38+
39+
See the below API documentation in |lsp-status-api|. For a complete setup
40+
example:>
41+
lua << END
42+
local lsp_status = require('lsp-status')
43+
lsp_status.register_progress()
44+
45+
local nvim_lsp = require('nvim-lsp')
46+
47+
-- Some arbitrary servers
48+
nvim_lsp.clangd.setup({
49+
callbacks = lsp_status.extensions.clangd.setup(),
50+
init_options = {
51+
clangdFileStatus = true
52+
},
53+
on_attach = lsp_status.on_attach,
54+
capabilities = lsp_status.capabilities
55+
})
56+
57+
nvim_lsp.pyls_ms.setup({
58+
callbacks = lsp_status.extensions.pyls_ms.setup(),
59+
settings = { python = { workspaceSymbols = { enabled = true }}},
60+
on_attach = lsp_status.on_attach,
61+
capabilities = lsp_status.capabilities
62+
})
63+
64+
nvim_lsp.ghcide.setup({
65+
on_attach = lsp_status.on_attach,
66+
capabilities = lsp_status.capabilities
67+
})
68+
nvim_lsp.rust_analyzer.setup({
69+
on_attach = lsp_status.on_attach,
70+
capabilities = lsp_status.capabilities
71+
})
72+
END
73+
74+
" Statusline
75+
function! LspStatus() abort
76+
if luaeval('#vim.lsp.buf_get_clients() > 0')
77+
return luaeval("require('lsp-status').status()")
78+
endif
79+
80+
return ''
81+
endfunction
82+
83+
==============================================================================
84+
API: core module lsp-status *lsp-status-api*
85+
86+
capabilities() *lsp-status.capabilities()*
87+
Table of client capabilities including progress message
88+
capability. Assign or extend your server's capabilities table
89+
with this
90+
91+
configure({config}) *lsp-status.configure()*
92+
Configure lsp-status.nvim. Currently supported configuration
93+
variables are:
94+
• `kind_labels` : A map from LSP symbol kinds to label
95+
symbols. Used to decorate the current function name.
96+
Default: `{}`•
97+
• `select_symbol` : A callback of the form
98+
`function(cursor_pos, document_symbol)` that should return
99+
`true` if `document_symbol` (a `DocumentSymbol` ) should be
100+
accepted as the symbol currently containing the cursor.•
101+
• `indicator_errors` : Symbol to place next to the error count
102+
in `status` . Default: '',•
103+
• `indicator_warnings` : Symbol to place next to the warning
104+
count in `status` . Default: '',•
105+
• `indicator_info` : Symbol to place next to the info count in
106+
`status` . Default: '🛈',•
107+
• `indicator_hint` : Symbol to place next to the hint count in
108+
`status` . Default: '❗',•
109+
• `indicator_ok` : Symbol to show in `status` if there are no
110+
diagnostics. Default: '',•
111+
• `spinner_frames` : Animation frames for progress spinner in
112+
`status` . Default: { '⣾', '⣽', '⣻', '⢿', '⡿', '⣟', '⣯', '⣷'
113+
},•
114+
• `status_symbol` : Symbol to start the statusline segment in
115+
`status` . Default: ' 🇻',•
116+
117+
Parameters: ~
118+
{config}(required, table) Table of values; keys are as
119+
listed above. Accept defaults by omitting the
120+
relevant key.
121+
122+
diagnostics() *lsp-status.diagnostics()*
123+
Get all diagnostics for the current buffer. Convenience
124+
function to retrieve all diagnostic counts for the current
125+
buffer.
126+
127+
Return: ~
128+
{ 'Error: error_count, 'Warning': warning_count', 'Info':
129+
info_count, 'Hint': hint_count `}
130+
131+
messages() *lsp-status.messages()*
132+
Return the current set of messages from all servers. Messages
133+
are either progress messages, file status messages, or
134+
"normal" messages. Progress messages are tables of the form `{
135+
name = Server name, title = Progress item title, message =
136+
Current progress message (if any), percentage = Current
137+
progress percentage (if any), progress = true, spinner =
138+
Spinner frames index, }`
139+
140+
File status messages are tables of the form `{ name = Server
141+
name, content = Message content, uri = File URI, status = true
142+
}` Normal messages are tables of the form `{ name = Server
143+
name, content = Message contents }`
144+
145+
Return: ~
146+
list of messages
147+
148+
on_attach({client}) *lsp-status.on_attach()*
149+
Register a new server for messages. Use this function either
150+
as your server's `on_attach` or inside your server's
151+
`on_attach` . It registers the server with `lsp-status` for
152+
progress message handling and current function updating
153+
154+
Parameters: ~
155+
{client}(required, vim.lsp.client)
156+
157+
register_client({id}, {name}) *lsp-status.register_client()*
158+
Register a new server to receive messages. Generally, you
159+
don't need to call this manually - `on_attach` sets it up for
160+
you
161+
162+
Parameters: ~
163+
{id} (required, number) Client ID
164+
{name}(required, string) Client name
165+
166+
register_progress() *lsp-status.register_progress()*
167+
Register the progress callback with Neovim's LSP client. Call
168+
once before starting any servers
169+
170+
status() *lsp-status.status()*
171+
Out-of-the-box statusline component. Returns a statusline
172+
component with (1) a leading glyph, (2) the current function
173+
information, and (3) diagnostic information. Call in your
174+
statusline definition. Usable out of the box, but intended
175+
more as an example/template for modification to customize to
176+
your own needs
177+
178+
Return: ~
179+
: statusline component string
180+
181+
update_current_function() *lsp-status.update_current_function()*
182+
Update the current function symbol. Generally, you don't need
183+
to call this manually - |lsp-status.on_attach| sets up its use
184+
for you. Sets the `b:lsp_current_function` variable.
185+
186+
187+
==============================================================================
188+
Module: lsp-status.clangd *lsp-status-api-clangd*
189+
190+
setup() *lsp-status.extensions.clangd.setup()*
191+
Return the callback {LSP Method: callback} table for `clangd` 's `fileStatus` extension
192+
193+
Return: ~
194+
Table of extension method callbacks, to be added to your
195+
`clangd` config
196+
197+
198+
==============================================================================
199+
Module: lsp-status.pyls_ms *lsp-status-api-pyls_ms*
200+
201+
setup() *lsp-status.extensions.pyls_ms.setup()*
202+
Return the callback {LSP Method: callback} table for `MPLS` 's progress and statusbar message extensions
203+
204+
Return: ~
205+
Table of extension method callbacks, to be added to your
206+
`pyls_ms` config
207+
208+
vim:tw=78:ts=2:ft=help:norl:

‎lua/lsp-status.lua

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,14 +40,38 @@ local current_function = require('lsp-status/current_function')
4040
-- Out-of-the-box statusline component
4141
local statusline = require('lsp-status/statusline')
4242

43+
--- Configure lsp-status.nvim.
44+
--- Currently supported configuration variables are:
45+
--- - `kind_labels`: A map from LSP symbol kinds to label symbols. Used to decorate the current
46+
--- function name. Default: `{}`
47+
--- - `select_symbol`: A callback of the form `function(cursor_pos, document_symbol)` that should
48+
--- return `true` if `document_symbol` (a `DocumentSymbol`) should be accepted as the symbol
49+
--- currently containing the cursor.
50+
--- - `indicator_errors`: Symbol to place next to the error count in `status`. Default: '',
51+
--- - `indicator_warnings`: Symbol to place next to the warning count in `status`. Default: '',
52+
--- - `indicator_info`: Symbol to place next to the info count in `status`. Default: '🛈',
53+
--- - `indicator_hint`: Symbol to place next to the hint count in `status`. Default: '❗',
54+
--- - `indicator_ok`: Symbol to show in `status` if there are no diagnostics. Default: '',
55+
--- - `spinner_frames`: Animation frames for progress spinner in `status`. Default: { '⣾', '⣽', '⣻', '⢿', '⡿', '⣟', '⣯', '⣷' },
56+
--- - `status_symbol`: Symbol to start the statusline segment in `status`. Default: ' 🇻',
57+
---
58+
--@param config: (required, table) Table of values; keys are as listed above. Accept defaults by
59+
--- omitting the relevant key.
4360
local function configure(config)
4461
_config = vim.tbl_extend('keep', config, _config, default_config)
4562
pyls_ms._init(messages, _config)
4663
clangd._init(messages, _config)
4764
messaging._init(messages, _config)
4865
current_function._init(messages, _config)
66+
statusline._init(messages, _config)
4967
end
5068

69+
--- Register a new server for messages.
70+
--- Use this function either as your server's `on_attach` or inside your server's `on_attach`. It
71+
--- registers the server with `lsp-status` for progress message handling and current function
72+
--- updating
73+
---
74+
--@param client: (required, vim.lsp.client)
5175
local function on_attach(client)
5276
-- Register the client for messages
5377
messaging.register_client(client.id, client.name)
@@ -73,6 +97,73 @@ end
7397

7498
configure(_config)
7599

100+
-- Stubs for documentation
101+
--- Update the current function symbol.
102+
--- Generally, you don't need to call this manually - |lsp-status.on_attach| sets up its use for you.
103+
--- Sets the `b:lsp_current_function` variable.
104+
local function update_current_function() -- luacheck: no unused
105+
error()
106+
end
107+
108+
--- Return the current set of messages from all servers. Messages are either progress messages,
109+
--- file status messages, or "normal" messages.
110+
--- Progress messages are tables of the form
111+
--- `{
112+
--- name = Server name,
113+
--- title = Progress item title,
114+
--- message = Current progress message (if any),
115+
--- percentage = Current progress percentage (if any),
116+
--- progress = true,
117+
--- spinner = Spinner frames index,
118+
--- }`
119+
---
120+
--- File status messages are tables of the form
121+
--- `{
122+
--- name = Server name,
123+
--- content = Message content,
124+
--- uri = File URI,
125+
--- status = true
126+
--- }`
127+
--- Normal messages are tables of the form
128+
--- `{ name = Server name, content = Message contents }`
129+
---
130+
--@returns list of messages
131+
local function messages() -- luacheck: no unused
132+
error()
133+
end
134+
135+
--- Register the progress callback with Neovim's LSP client.
136+
--- Call once before starting any servers
137+
local function register_progress() -- luacheck: no unused
138+
error()
139+
end
140+
141+
--- Register a new server to receive messages.
142+
--- Generally, you don't need to call this manually - `on_attach` sets it up for you
143+
---
144+
--@param id: (required, number) Client ID
145+
--@param name: (required, string) Client name
146+
local function register_client(id, name) -- luacheck: no unused
147+
error()
148+
end
149+
150+
--- Out-of-the-box statusline component.
151+
--- Returns a statusline component with (1) a leading glyph, (2) the current function information,
152+
--- and (3) diagnostic information. Call in your statusline definition.
153+
--- Usable out of the box, but intended more as an example/template for modification to customize
154+
--- to your own needs
155+
---
156+
--@returns: statusline component string
157+
local function status() -- luacheck: no unused
158+
error()
159+
end
160+
161+
--- Table of client capabilities including progress message capability.
162+
--- Assign or extend your server's capabilities table with this
163+
local function capabilities() -- luacheck: no unused
164+
error()
165+
end
166+
76167
local M = {
77168
update_current_function = current_function.update,
78169
diagnostics = diagnostics,

‎lua/lsp-status/extensions/clangd.lua

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,12 @@ local util = require('lsp-status/util')
22

33
local messages = {}
44

5+
---@private
56
local function init(_messages, _)
67
messages = _messages
78
end
89

10+
---@private
911
local function ensure_init(id)
1012
util.ensure_init(messages, id, 'clangd')
1113
end
@@ -18,6 +20,8 @@ local callbacks = {
1820
end,
1921
}
2022

23+
--- Return the callback {LSP Method: callback} table for `clangd`'s `fileStatus` extension
24+
--@returns Table of extension method callbacks, to be added to your `clangd` config
2125
local function setup()
2226
return callbacks
2327
end

‎lua/lsp-status/extensions/pyls_ms.lua

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
local util = require('lsp-status/util')
22

33
local messages = {}
4+
---@private
45
local function init(_messages, _)
56
messages = _messages
67
end
78

9+
---@private
810
local function ensure_init(id)
911
util.ensure_init(messages, id, 'pyls_ms')
1012
end
@@ -32,6 +34,9 @@ local callbacks = {
3234
end,
3335
}
3436

37+
--- Return the callback {LSP Method: callback} table for `MPLS`'s progress and statusbar message
38+
--- extensions
39+
--@returns Table of extension method callbacks, to be added to your `pyls_ms` config
3540
local function setup()
3641
return callbacks
3742
end

0 commit comments

Comments
 (0)