1 files changed, 55 insertions, 37 deletions

diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md
index 68a5df27e..647cf6107 100644
--- a/docs/dev/lsp-extensions.md
+++ b/docs/dev/lsp-extensions.md
@@ -7,6 +7,16 @@ All capabilities are enabled via `experimental` field of `ClientCapabilities` or
 Requests which we hope to upstream live under `experimental/` namespace.
 Requests, which are likely to always remain specific to `rust-analyzer` are under `rust-analyzer/` namespace.
 
+If you want to be notified about the changes to this document, subscribe to [#4604](https://github.com/rust-analyzer/rust-analyzer/issues/4604).
+
+## `initializationOptions`
+
+As `initializationOptions`, `rust-analyzer` expects `"rust-analyzer"` section of the configuration.
+That is, `rust-analyzer` usually sends `"workspace/configuration"` request with `{ "items": ["rust-analyzer"] }` payload.
+`initializationOptions` should contain the same data that would be in the first item of the result.
+It's OK to not send anything, then all the settings would take their default values.
+However, some settings can not be changed after startup at the moment.
+
 ## Snippet `TextEdit`
 
 **Issue:** https://github.com/microsoft/language-server-protocol/issues/724
@@ -154,7 +164,7 @@ fn main() {
 }
 ```
 
-`experimental/joinLines` yields (curly braces are automagiacally removed)
+`experimental/joinLines` yields (curly braces are automagically removed)
 
 ```rust
 fn main() {
@@ -301,6 +311,50 @@ Moreover, it would be cool if editors didn't need to implement even basic langua
   This is how `SelectionRange` request works.
 * Alternatively, should we perhaps flag certain `SelectionRange`s as being brace pairs?
 
+## Runnables
+
+**Issue:** https://github.com/microsoft/language-server-protocol/issues/944
+
+**Server Capability:** `{ "runnables": { "kinds": string[] } }`
+
+This request is send from client to server to get the list of things that can be run (tests, binaries, `cargo check -p`).
+
+**Method:** `experimental/runnables`
+
+**Request:**
+
+```typescript
+interface RunnablesParams {
+    textDocument: TextDocumentIdentifier;
+    /// If null, compute runnables for the whole file.
+    position?: Position;
+}
+```
+
+**Response:** `Runnable[]`
+
+```typescript
+interface Runnable {
+    label: string;
+    /// If this Runnable is associated with a specific function/module, etc, the location of this item
+    location?: LocationLink;
+    /// Running things is necessary technology specific, `kind` needs to be advertised via server capabilities,
+    // the type of `args` is specific to `kind`. The actual running is handled by the client.
+    kind: string;
+    args: any;
+}
+```
+
+rust-analyzer supports only one `kind`, `"cargo"`. The `args` for `"cargo"` look like this:
+
+```typescript
+{
+    workspaceRoot?: string;
+    cargoArgs: string[];
+    executableArgs: string[];
+}
+```
+
 ## Analyzer Status
 
 **Method:** `rust-analyzer/analyzerStatus`
@@ -389,39 +443,3 @@ interface InlayHint {
     label: string,
 }
 ```
-
-## Runnables
-
-**Method:** `rust-analyzer/runnables`
-
-This request is send from client to server to get the list of things that can be run (tests, binaries, `cargo check -p`).
-Note that we plan to move this request to `experimental/runnables`, as it is not really Rust-specific, but the current API is not necessary the right one.
-Upstream issue: https://github.com/microsoft/language-server-protocol/issues/944
-
-**Request:**
-
-```typescript
-interface RunnablesParams {
-    textDocument: TextDocumentIdentifier;
-    /// If null, compute runnables for the whole file.
-    position?: Position;
-}
-```
-
-**Response:** `Runnable[]`
-
-```typescript
-interface Runnable {
-    /// The range this runnable is applicable for.
-    range: lc.Range;
-    /// The label to show in the UI.
-    label: string;
-    /// The following fields describe a process to spawn.
-    bin: string;
-    args: string[];
-    /// Args for cargo after `--`.
-    extraArgs: string[];
-    env: { [key: string]: string };
-    cwd: string | null;
-}
-```