[ty] Use markdown for completions documentation

crates/ty_server/src/capabilities.rs

@@ -38,6 +38,7 @@ bitflags::bitflags! {
         const WORKSPACE_CONFIGURATION = 1 << 15;
         const RENAME_DYNAMIC_REGISTRATION = 1 << 16;
         const COMPLETION_ITEM_LABEL_DETAILS_SUPPORT = 1 << 17;
+        const PREFER_MARKDOWN_IN_COMPLETION = 1 << 18;
     }
 }
 
@@ -175,6 +176,11 @@ impl ResolvedClientCapabilities {
         self.contains(Self::COMPLETION_ITEM_LABEL_DETAILS_SUPPORT)
     }
 
+    /// Returns `true` if the client prefers Markdown over plain text in completion items.
+    pub(crate) const fn prefers_markdown_in_completion(self) -> bool {
+        self.contains(Self::PREFER_MARKDOWN_IN_COMPLETION)
+    }
+
     pub(super) fn new(client_capabilities: &ClientCapabilities) -> Self {
         let mut flags = Self::empty();
 
@@ -261,6 +267,24 @@ impl ResolvedClientCapabilities {
             flags |= Self::PREFER_MARKDOWN_IN_HOVER;
         }
 
+        if text_document
+            .and_then(|text_document| {
+                Some(
+                    text_document
+                        .completion
+                        .as_ref()?
+                        .completion_item
+                        .as_ref()?
+                        .documentation_format
+                        .as_ref()?
+                        .contains(&MarkupKind::Markdown),
+                )
+            })
+            .unwrap_or_default()
+        {
+            flags |= Self::PREFER_MARKDOWN_IN_COMPLETION;
+        }
+
         if text_document
             .and_then(|text_document| {
                 text_document

crates/ty_server/src/server/api/requests/completion.rs

@@ -100,6 +100,23 @@ impl BackgroundDocumentRequestHandler for CompletionRequestHandler {
                         .unwrap_or_else(|| name);
                     (label, None)
                 };
+
+                let documentation = comp.documentation.map(|docstring| {
+                    let (kind, value) = if snapshot
+                        .resolved_client_capabilities()
+                        .prefers_markdown_in_completion()
+                    {
+                        (lsp_types::MarkupKind::Markdown, docstring.render_markdown())
+                    } else {
+                        (
+                            lsp_types::MarkupKind::PlainText,
+                            docstring.render_plaintext(),
+                        )
+                    };
+
+                    Documentation::MarkupContent(lsp_types::MarkupContent { kind, value })
+                });
+
                 CompletionItem {
                     label,
                     kind,
@@ -108,9 +125,7 @@ impl BackgroundDocumentRequestHandler for CompletionRequestHandler {
                     label_details,
                     insert_text: comp.insert.map(String::from),
                     additional_text_edits: import_edit.map(|edit| vec![edit]),
-                    documentation: comp
-                        .documentation
-                        .map(|docstring| Documentation::String(docstring.render_plaintext())),
+                    documentation,
                     ..Default::default()
                 }
             })

crates/ty_server/tests/e2e/completions.rs

@@ -0,0 +1,58 @@
+use anyhow::Result;
+use lsp_types::{Position, notification::PublishDiagnostics};
+use ruff_db::system::SystemPath;
+use ty_server::ClientOptions;
+
+use crate::TestServerBuilder;
+
+#[test]
+fn completions() -> Result<()> {
+    let workspace_root = SystemPath::new("src");
+    let foo = SystemPath::new("src/foo.py");
+    let foo_content = "type";
+
+    let mut server = TestServerBuilder::new()?
+        .with_initialization_options(ClientOptions::default())
+        .with_workspace(workspace_root, None)?
+        .with_file(foo, foo_content)?
+        .enable_completions(true)
+        .build()
+        .wait_until_workspaces_are_initialized();
+
+    server.open_text_document(foo, &foo_content, 1);
+    let _ = server.await_notification::<PublishDiagnostics>();
+
+    let hints = server
+        .completions_request(foo, Position::new(0, 4))
+        .unwrap();
+
+    insta::assert_json_snapshot!(hints, @r#"
+    {
+      "isIncomplete": true,
+      "items": [
+        {
+          "label": "TypeError",
+          "kind": 7,
+          "detail": "<class 'TypeError'>",
+          "documentation": {
+            "kind": "plaintext",
+            "value": "Inappropriate argument type.\n"
+          },
+          "sortText": "0"
+        },
+        {
+          "label": "type",
+          "kind": 7,
+          "detail": "<class 'type'>",
+          "documentation": {
+            "kind": "plaintext",
+            "value": "type(object) -> the object's type/ntype(name, bases, dict, **kwds) -> a new type\n"
+          },
+          "sortText": "1"
+        }
+      ]
+    }
+    "#);
+
+    Ok(())
+}

crates/ty_server/tests/e2e/main.rs

@@ -29,6 +29,7 @@
 
 mod code_actions;
 mod commands;
+mod completions;
 mod initialize;
 mod inlay_hints;
 mod notebook;
@@ -51,16 +52,17 @@ use lsp_types::notification::{
     Initialized, Notification,
 };
 use lsp_types::request::{
-    DocumentDiagnosticRequest, HoverRequest, Initialize, InlayHintRequest, Request, Shutdown,
-    WorkspaceConfiguration, WorkspaceDiagnosticRequest,
+    Completion, DocumentDiagnosticRequest, HoverRequest, Initialize, InlayHintRequest, Request,
+    Shutdown, WorkspaceConfiguration, WorkspaceDiagnosticRequest,
 };
 use lsp_types::{
-    ClientCapabilities, ConfigurationParams, DiagnosticClientCapabilities,
-    DidChangeTextDocumentParams, DidChangeWatchedFilesClientCapabilities,
-    DidChangeWatchedFilesParams, DidCloseTextDocumentParams, DidOpenTextDocumentParams,
-    DocumentDiagnosticParams, DocumentDiagnosticReportResult, FileEvent, Hover, HoverParams,
-    InitializeParams, InitializeResult, InitializedParams, InlayHint, InlayHintClientCapabilities,
-    InlayHintParams, NumberOrString, PartialResultParams, Position, PreviousResultId,
+    ClientCapabilities, CompletionClientCapabilities, CompletionParams, CompletionResponse,
+    ConfigurationParams, DiagnosticClientCapabilities, DidChangeTextDocumentParams,
+    DidChangeWatchedFilesClientCapabilities, DidChangeWatchedFilesParams,
+    DidCloseTextDocumentParams, DidOpenTextDocumentParams, DocumentDiagnosticParams,
+    DocumentDiagnosticReportResult, FileEvent, Hover, HoverParams, InitializeParams,
+    InitializeResult, InitializedParams, InlayHint, InlayHintClientCapabilities, InlayHintParams,
+    NumberOrString, PartialResultParams, Position, PreviousResultId,
     PublishDiagnosticsClientCapabilities, Range, TextDocumentClientCapabilities,
     TextDocumentContentChangeEvent, TextDocumentIdentifier, TextDocumentItem,
     TextDocumentPositionParams, Url, VersionedTextDocumentIdentifier, WorkDoneProgressParams,
@@ -870,6 +872,26 @@ impl TestServer {
         let id = self.send_request::<InlayHintRequest>(params);
         self.await_response::<InlayHintRequest>(&id)
     }
+
+    pub(crate) fn completions_request(
+        &mut self,
+        path: impl AsRef<SystemPath>,
+        position: Position,
+    ) -> Option<CompletionResponse> {
+        let params = CompletionParams {
+            text_document_position: TextDocumentPositionParams {
+                text_document: TextDocumentIdentifier {
+                    uri: self.file_uri(path),
+                },
+                position,
+            },
+            work_done_progress_params: WorkDoneProgressParams::default(),
+            context: None,
+            partial_result_params: PartialResultParams::default(),
+        };
+        let id = self.send_request::<Completion>(params);
+        self.await_response::<Completion>(&id)
+    }
 }
 
 impl fmt::Debug for TestServer {
@@ -1087,6 +1109,19 @@ impl TestServerBuilder {
         self
     }
 
+    /// Enable (with auto import) or disable completions capability
+    pub(crate) fn enable_completions(mut self, enabled: bool) -> Self {
+        self.client_capabilities
+            .text_document
+            .get_or_insert_default()
+            .completion = if enabled {
+            Some(CompletionClientCapabilities::default())
+        } else {
+            None
+        };
+        self
+    }
+
     /// Enable or disable file watching capability
     #[expect(dead_code)]
     pub(crate) fn enable_did_change_watched_files(mut self, enabled: bool) -> Self {