Rename DocC SourceKit-LSP request to textDocument/doccDocumentation (#1318)

Author: matthewbastien

src/WorkspaceContext.ts

@@ -34,6 +34,7 @@ import { SwiftBuildStatus } from "./ui/SwiftBuildStatus";
 import { SwiftToolchain } from "./toolchain/toolchain";
 import { DiagnosticsManager } from "./DiagnosticsManager";
 import { DocumentationManager } from "./documentation/DocumentationManager";
+import { DocCDocumentationRequest, ReIndexProjectRequest } from "./sourcekit-lsp/extensions";
 
 /**
  * Context for whole workspace. Holds array of contexts for each workspace folder
@@ -239,9 +240,9 @@ export class WorkspaceContext implements vscode.Disposable {
                 return;
             }
             contextKeys.supportsReindexing =
-                experimentalCaps["workspace/triggerReindex"] !== undefined;
+                experimentalCaps[ReIndexProjectRequest.method] !== undefined;
             contextKeys.supportsDocumentationLivePreview =
-                experimentalCaps["textDocument/convertDocumentation"] !== undefined;
+                experimentalCaps[DocCDocumentationRequest.method] !== undefined;
         });
 
         setSnippetContextKey(this);

src/documentation/DocumentationPreviewEditor.ts

@@ -17,7 +17,8 @@ import * as fs from "fs/promises";
 import * as path from "path";
 import { RenderNode, WebviewContent, WebviewMessage } from "./webview/WebviewMessage";
 import { WorkspaceContext } from "../WorkspaceContext";
-import { ConvertDocumentationRequest } from "../sourcekit-lsp/extensions/ConvertDocumentationRequest";
+import { DocCDocumentationRequest, DocCDocumentationResponse } from "../sourcekit-lsp/extensions";
+import { LSPErrorCodes, ResponseError } from "vscode-languageclient";
 
 export enum PreviewEditorConstant {
     VIEW_TYPE = "swift.previewDocumentationEditor",
@@ -185,33 +186,56 @@ export class DocumentationPreviewEditor implements vscode.Disposable {
             return;
         }
 
-        const response = await this.context.languageClientManager.useLanguageClient(
-            async client => {
-                return await client.sendRequest(ConvertDocumentationRequest.type, {
-                    textDocument: {
-                        uri: document.uri.toString(),
-                    },
-                    position: textEditor.selection.start,
-                });
+        try {
+            const response = await this.context.languageClientManager.useLanguageClient(
+                async (client): Promise<DocCDocumentationResponse> => {
+                    return await client.sendRequest(DocCDocumentationRequest.type, {
+                        textDocument: {
+                            uri: document.uri.toString(),
+                        },
+                        position: textEditor.selection.start,
+                    });
+                }
+            );
+            this.postMessage({
+                type: "update-content",
+                content: {
+                    type: "render-node",
+                    renderNode: this.parseRenderNode(response.renderNode),
+                },
+            });
+        } catch (error) {
+            // Update the preview editor to reflect what error occurred
+            let livePreviewErrorMessage = "An internal error occurred";
+            const baseLogErrorMessage = `SourceKit-LSP request "${DocCDocumentationRequest.method}" failed: `;
+            if (error instanceof ResponseError) {
+                if (error.code === LSPErrorCodes.RequestCancelled) {
+                    // We can safely ignore cancellations
+                    return undefined;
+                }
+                switch (error.code) {
+                    case LSPErrorCodes.RequestFailed:
+                        // RequestFailed response errors can be shown to the user
+                        livePreviewErrorMessage = error.message;
+                        break;
+                    default:
+                        // We should log additional info for other response errors
+                        this.context.outputChannel.log(
+                            baseLogErrorMessage + JSON.stringify(error.toJson(), undefined, 2)
+                        );
+                        break;
+                }
+            } else {
+                this.context.outputChannel.log(baseLogErrorMessage + `${error}`);
             }
-        );
-        if (response.type === "error") {
             this.postMessage({
                 type: "update-content",
                 content: {
                     type: "error",
-                    errorMessage: response.error.message,
+                    errorMessage: livePreviewErrorMessage,
                 },
             });
-            return;
         }
-        this.postMessage({
-            type: "update-content",
-            content: {
-                type: "render-node",
-                renderNode: this.parseRenderNode(response.renderNode),
-            },
-        });
     }
 
     private parseRenderNode(content: string): RenderNode {

src/sourcekit-lsp/extensions/ConvertDocumentationRequest.ts

@@ -0,0 +1,55 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the VS Code Swift open source project
+//
+// Copyright (c) 2021-2024 the VS Code Swift project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of VS Code Swift project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+// We use namespaces to store request information just like vscode-languageclient
+/* eslint-disable @typescript-eslint/no-namespace */
+
+import {
+    TextDocumentIdentifier,
+    Position,
+    MessageDirection,
+    RequestType,
+} from "vscode-languageclient";
+
+/** Parameters used to make a {@link DocCDocumentationRequest}. */
+export interface DocCDocumentationParams {
+    /**
+     * The document to render documentation for.
+     */
+    textDocument: TextDocumentIdentifier;
+
+    /**
+     * The document location at which to lookup symbol information.
+     *
+     * This parameter is only used in Swift files to determine which symbol to render.
+     * The position is ignored for markdown and tutorial documents.
+     */
+    position: Position;
+}
+
+/**
+ * The response from a {@link DocCDocumentationRequest} containing a single RenderNode
+ * that can be displayed in an editor via `swiftlang/swift-docc-render`
+ */
+export interface DocCDocumentationResponse {
+    renderNode: string;
+}
+
+export namespace DocCDocumentationRequest {
+    export const method = "textDocument/doccDocumentation" as const;
+    export const messageDirection: MessageDirection = MessageDirection.clientToServer;
+    export const type = new RequestType<DocCDocumentationParams, DocCDocumentationResponse, never>(
+        method
+    );
+}

src/sourcekit-lsp/extensions/DocCDocumentationRequest.ts

@@ -14,6 +14,7 @@
 
 // Definitions for non-standard requests used by sourcekit-lsp
 
+export * from "./DocCDocumentationRequest";
 export * from "./GetReferenceDocumentRequest";
 export * from "./GetTestsRequest";
 export * from "./LegacyInlayHintRequest";