Merge #4593

4593: Document some rust-analyzer specific protocol extensions r=matklad a=matklad



bors r+
🤖

Co-authored-by: Aleksey Kladov <aleksey.kladov@gmail.com>

Author: bors[bot]

crates/rust-analyzer/src/lsp_ext.rs

@@ -38,13 +38,6 @@ pub struct SyntaxTreeParams {
     pub range: Option<Range>,
 }
 
-#[derive(Deserialize, Serialize, Debug)]
-#[serde(rename_all = "camelCase")]
-pub struct ExpandedMacro {
-    pub name: String,
-    pub expansion: String,
-}
-
 pub enum ExpandMacro {}
 
 impl Request for ExpandMacro {
@@ -60,19 +53,26 @@ pub struct ExpandMacroParams {
     pub position: Option<Position>,
 }
 
-pub enum FindMatchingBrace {}
+#[derive(Deserialize, Serialize, Debug)]
+#[serde(rename_all = "camelCase")]
+pub struct ExpandedMacro {
+    pub name: String,
+    pub expansion: String,
+}
+
+pub enum MatchingBrace {}
 
-impl Request for FindMatchingBrace {
-    type Params = FindMatchingBraceParams;
+impl Request for MatchingBrace {
+    type Params = MatchingBraceParams;
     type Result = Vec<Position>;
-    const METHOD: &'static str = "rust-analyzer/findMatchingBrace";
+    const METHOD: &'static str = "experimental/matchingBrace";
 }
 
 #[derive(Deserialize, Serialize, Debug)]
 #[serde(rename_all = "camelCase")]
-pub struct FindMatchingBraceParams {
+pub struct MatchingBraceParams {
     pub text_document: TextDocumentIdentifier,
-    pub offsets: Vec<Position>,
+    pub positions: Vec<Position>,
 }
 
 pub enum ParentModule {}

crates/rust-analyzer/src/main_loop.rs

@@ -509,9 +509,7 @@ fn on_request(
         .on_sync::<lsp_types::request::SelectionRangeRequest>(|s, p| {
             handlers::handle_selection_range(s.snapshot(), p)
         })?
-        .on_sync::<lsp_ext::FindMatchingBrace>(|s, p| {
-            handlers::handle_find_matching_brace(s.snapshot(), p)
-        })?
+        .on_sync::<lsp_ext::MatchingBrace>(|s, p| handlers::handle_matching_brace(s.snapshot(), p))?
         .on::<lsp_ext::AnalyzerStatus>(handlers::handle_analyzer_status)?
         .on::<lsp_ext::SyntaxTree>(handlers::handle_syntax_tree)?
         .on::<lsp_ext::ExpandMacro>(handlers::handle_expand_macro)?

crates/rust-analyzer/src/main_loop/handlers.rs

@@ -126,15 +126,15 @@ pub fn handle_selection_range(
     Ok(Some(res?))
 }
 
-pub fn handle_find_matching_brace(
+pub fn handle_matching_brace(
     world: WorldSnapshot,
-    params: lsp_ext::FindMatchingBraceParams,
+    params: lsp_ext::MatchingBraceParams,
 ) -> Result<Vec<Position>> {
-    let _p = profile("handle_find_matching_brace");
+    let _p = profile("handle_matching_brace");
     let file_id = from_proto::file_id(&world, &params.text_document.uri)?;
     let line_index = world.analysis().file_line_index(file_id)?;
     let res = params
-        .offsets
+        .positions
         .into_iter()
         .map(|position| {
             let offset = from_proto::offset(&line_index, position);

docs/dev/lsp-extensions.md

@@ -95,7 +95,7 @@ Invoking code action at this position will yield two code actions for importing
 
 This request is send from client to server to handle "Join Lines" editor action.
 
-**Method:** `experimental/JoinLines`
+**Method:** `experimental/joinLines`
 
 **Request:**
 
@@ -172,3 +172,110 @@ SSR with query `foo($a:expr, $b:expr) ==>> ($a).foo($b)` will transform, eg `foo
 
 * Probably needs search without replace mode
 * Needs a way to limit the scope to certain files.
+
+## Matching Brace
+
+**Issue:** https://github.com/microsoft/language-server-protocol/issues/999
+
+**Server Capability:** `{ "matchingBrace": boolean }`
+
+This request is send from client to server to handle "Matching Brace" editor action.
+
+**Method:** `experimental/matchingBrace`
+
+**Request:**
+
+```typescript
+interface MatchingBraceParams {
+    textDocument: TextDocumentIdentifier,
+    /// Position for each cursor
+    positions: Position[],
+}
+```
+
+**Response:**
+
+```typescript
+Position[]
+```
+
+### Example
+
+```rust
+fn main() {
+    let x: Vec<()>/*cursor here*/ = vec![]
+}
+```
+
+`experimental/matchingBrace` yields the position of `<`.
+In many cases, matching braces can be handled by the editor.
+However, some cases (like disambiguating between generics and comparison operations) need a real parser.
+Moreover, it would be cool if editors didn't need to implement even basic language parsing
+
+### Unresolved Question
+
+* Should we return a a nested brace structure, to allow paredit-like actions of jump *out* of the current brace pair?
+  This is how `SelectionRange` request works.
+* Alternatively, should we perhaps flag certain `SelectionRange`s as being brace pairs?
+
+## Analyzer Status
+
+**Method:** `rust-analyzer/analyzerStatus`
+
+**Request:** `null`
+
+**Response:** `string`
+
+Returns internal status message, mostly for debugging purposes.
+
+## Collect Garbage
+
+**Method:** `rust-analyzer/collectGarbage`
+
+**Request:** `null`
+
+**Response:** `null`
+
+Frees some caches. For internal use, and is mostly broken at the moment.
+
+## Syntax Tree
+
+**Method:** `rust-analyzer/syntaxTree`
+
+**Request:**
+
+```typescript
+interface SyntaxTeeParams {
+    textDocument: TextDocumentIdentifier,
+    range?: Range,
+}
+```
+
+**Response:** `string`
+
+Returns textual representation of a parse tree for the file/selected region.
+Primarily for debugging, but very useful for all people working on rust-analyzer itself.
+
+## Expand Macro
+
+**Method:** `rust-analyzer/expandMacro`
+
+**Request:**
+
+```typescript
+interface ExpandMacroParams {
+    textDocument: TextDocumentIdentifier,
+    position?: Position,
+}
+```
+
+**Response:**
+
+```typescript
+interface ExpandedMacro {
+    name: string,
+    expansion: string,
+}
+```
+
+Expands macro call at a given position.

editors/code/src/commands/matching_brace.ts

@@ -9,9 +9,9 @@ export function matchingBrace(ctx: Ctx): Cmd {
         const client = ctx.client;
         if (!editor || !client) return;
 
-        const response = await client.sendRequest(ra.findMatchingBrace, {
+        const response = await client.sendRequest(ra.matchingBrace, {
             textDocument: { uri: editor.document.uri.toString() },
-            offsets: editor.selections.map(s =>
+            positions: editor.selections.map(s =>
                 client.code2ProtocolConverter.asPosition(s.active),
             ),
         });

editors/code/src/rust-analyzer-api.ts

@@ -40,12 +40,11 @@ export interface ExpandedMacro {
 export const expandMacro = request<ExpandMacroParams, Option<ExpandedMacro>>("expandMacro");
 
 
-export interface FindMatchingBraceParams {
+export interface MatchingBraceParams {
     textDocument: lc.TextDocumentIdentifier;
-    offsets: Vec<lc.Position>;
+    positions: lc.Position[];
 }
-export const findMatchingBrace = request<FindMatchingBraceParams, Vec<lc.Position>>("findMatchingBrace");
-
+export const matchingBrace = new lc.RequestType<MatchingBraceParams, lc.Position[], unknown>('experimental/matchingBrace');
 
 export interface PublishDecorationsParams {
     uri: string;