diff options
author | Aleksey Kladov <[email protected]> | 2020-05-24 14:49:32 +0100 |
---|---|---|
committer | Aleksey Kladov <[email protected]> | 2020-05-24 14:49:32 +0100 |
commit | e4af9f6d8a4587fc66d13db4c10ad9260d813ed3 (patch) | |
tree | c184fc376a13ec8c9b75e0185fa3012a899c8188 /docs | |
parent | d1ff0145a9fe84f86192b2d88d5f0bd96a95a98f (diff) |
Reorgonise extensions docs
Diffstat (limited to 'docs')
-rw-r--r-- | docs/dev/lsp-extensions.md | 98 |
1 files changed, 50 insertions, 48 deletions
diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md index 158d3c599..1cc51410b 100644 --- a/docs/dev/lsp-extensions.md +++ b/docs/dev/lsp-extensions.md | |||
@@ -3,7 +3,9 @@ | |||
3 | This document describes LSP extensions used by rust-analyzer. | 3 | This document describes LSP extensions used by rust-analyzer. |
4 | It's a best effort document, when in doubt, consult the source (and send a PR with clarification ;-) ). | 4 | It's a best effort document, when in doubt, consult the source (and send a PR with clarification ;-) ). |
5 | We aim to upstream all non Rust-specific extensions to the protocol, but this is not a top priority. | 5 | We aim to upstream all non Rust-specific extensions to the protocol, but this is not a top priority. |
6 | All capabilities are enabled via `experimental` field of `ClientCapabilities`. | 6 | All capabilities are enabled via `experimental` field of `ClientCapabilities` or `ServerCapabilities`. |
7 | Requests which we hope to upstream live under `experimental/` namespace. | ||
8 | Requests, which are likely to always remain specific to `rust-analyzer` are under `rust-analyzer/` namespace. | ||
7 | 9 | ||
8 | ## Snippet `TextEdit` | 10 | ## Snippet `TextEdit` |
9 | 11 | ||
@@ -38,6 +40,53 @@ At the moment, rust-analyzer guarantees that only a single edit will have `Inser | |||
38 | * Where exactly are `SnippetTextEdit`s allowed (only in code actions at the moment)? | 40 | * Where exactly are `SnippetTextEdit`s allowed (only in code actions at the moment)? |
39 | * Can snippets span multiple files (so far, no)? | 41 | * Can snippets span multiple files (so far, no)? |
40 | 42 | ||
43 | ## `CodeAction` Groups | ||
44 | |||
45 | **Issue:** https://github.com/microsoft/language-server-protocol/issues/994 | ||
46 | |||
47 | **Client Capability:** `{ "codeActionGroup": boolean }` | ||
48 | |||
49 | If this capability is set, `CodeAction` returned from the server contain an additional field, `group`: | ||
50 | |||
51 | ```typescript | ||
52 | interface CodeAction { | ||
53 | title: string; | ||
54 | group?: string; | ||
55 | ... | ||
56 | } | ||
57 | ``` | ||
58 | |||
59 | All code-actions with the same `group` should be grouped under single (extendable) entry in lightbulb menu. | ||
60 | The set of actions `[ { title: "foo" }, { group: "frobnicate", title: "bar" }, { group: "frobnicate", title: "baz" }]` should be rendered as | ||
61 | |||
62 | ``` | ||
63 | 💡 | ||
64 | +-------------+ | ||
65 | | foo | | ||
66 | +-------------+-----+ | ||
67 | | frobnicate >| bar | | ||
68 | +-------------+-----+ | ||
69 | | baz | | ||
70 | +-----+ | ||
71 | ``` | ||
72 | |||
73 | Alternatively, selecting `frobnicate` could present a user with an additional menu to choose between `bar` and `baz`. | ||
74 | |||
75 | ### Example | ||
76 | |||
77 | ```rust | ||
78 | fn main() { | ||
79 | let x: Entry/*cursor here*/ = todo!(); | ||
80 | } | ||
81 | ``` | ||
82 | |||
83 | Invoking code action at this position will yield two code actions for importing `Entry` from either `collections::HashMap` or `collection::BTreeMap`, grouped under a single "import" group. | ||
84 | |||
85 | ### Unresolved Questions | ||
86 | |||
87 | * Is a fixed two-level structure enough? | ||
88 | * Should we devise a general way to encode custom interaction protocols for GUI refactorings? | ||
89 | |||
41 | ## Join Lines | 90 | ## Join Lines |
42 | 91 | ||
43 | **Issue:** https://github.com/microsoft/language-server-protocol/issues/992 | 92 | **Issue:** https://github.com/microsoft/language-server-protocol/issues/992 |
@@ -123,50 +172,3 @@ SSR with query `foo($a:expr, $b:expr) ==>> ($a).foo($b)` will transform, eg `foo | |||
123 | 172 | ||
124 | * Probably needs search without replace mode | 173 | * Probably needs search without replace mode |
125 | * Needs a way to limit the scope to certain files. | 174 | * Needs a way to limit the scope to certain files. |
126 | |||
127 | ## `CodeAction` Groups | ||
128 | |||
129 | **Issue:** https://github.com/microsoft/language-server-protocol/issues/994 | ||
130 | |||
131 | **Client Capability:** `{ "codeActionGroup": boolean }` | ||
132 | |||
133 | If this capability is set, `CodeAction` returned from the server contain an additional field, `group`: | ||
134 | |||
135 | ```typescript | ||
136 | interface CodeAction { | ||
137 | title: string; | ||
138 | group?: string; | ||
139 | ... | ||
140 | } | ||
141 | ``` | ||
142 | |||
143 | All code-actions with the same `group` should be grouped under single (extendable) entry in lightbulb menu. | ||
144 | The set of actions `[ { title: "foo" }, { group: "frobnicate", title: "bar" }, { group: "frobnicate", title: "baz" }]` should be rendered as | ||
145 | |||
146 | ``` | ||
147 | 💡 | ||
148 | +-------------+ | ||
149 | | foo | | ||
150 | +-------------+-----+ | ||
151 | | frobnicate >| bar | | ||
152 | +-------------+-----+ | ||
153 | | baz | | ||
154 | +-----+ | ||
155 | ``` | ||
156 | |||
157 | Alternatively, selecting `frobnicate` could present a user with an additional menu to choose between `bar` and `baz`. | ||
158 | |||
159 | ### Example | ||
160 | |||
161 | ```rust | ||
162 | fn main() { | ||
163 | let x: Entry/*cursor here*/ = todo!(); | ||
164 | } | ||
165 | ``` | ||
166 | |||
167 | Invoking code action at this position will yield two code actions for importing `Entry` from either `collections::HashMap` or `collection::BTreeMap`, grouped under a single "import" group. | ||
168 | |||
169 | ### Unresolved Questions | ||
170 | |||
171 | * Is a fixed two-level structure enough? | ||
172 | * Should we devise a general way to encode custom interaction protocols for GUI refactorings? | ||