Editor support for link tag (#41877)

* Initial scribbles

* Compiles but provides spans instead of location pairs

Probably need to fork the services/server types and provide a conversion
with Session.toFileSpan. Not sure where to put the conversion.

* Switch to DocumentSpan

In theory this is already better supported, but not sure practise bears
that out.

* Builds w/protocol types + conversions

* cleanup:better names and scrub TODOs

* fix test harness too

* Misc

1. Simplify protocol after talking to @mjbvz.
2. Add more tests.
3. Initial notes about where to add parsing.

* Parse and store links in the compiler

The text of the link is still stored in the comment text, but that's now
kept in an object instead of just a string. Each link has the parse for
the entity reference, if there is one.

Needs lots more tests -- this just makes all the existing jsdoc tests
pass.

* more tests and some fixes

* Fix other failing tests

* fix bad merge

* polish parser

* improve names and array types

* slight tweaks

* remove some done TODOs

* more tests + resulting fixes

* add+fix cross-module tests

* Support `@see {@link`

Plus find-all-refs support equivalent to @see's.

* add server test

* Make comments actually part of the AST

* Add span for link.name in language service/protocol

* Make checker optional in getJSDocTags

Also change to JSDocCommentText from JSDocCommentComment

* Use getTokenValue instead of getTokenText

Measure twice, slice once

* Add missing support for top-level links

The language service and protocol were missing support for top-level
links. This commit adds that plumbing.

* add string back to comment type in node constructors

* Full parse of link tags and jsdoc comment text

- Doesn't pass fourslash yet, I'm going to switch to baselines for
  failures there.
- Still needs some work on the protocol to convert file+offset to
  file+line+offset.

* fix lint

* Fix missing newlines in inferFromUsage codefix

* Parse jsdoc comments as text node/link array

And switch to line+character offsets in the protocol

* Fix fourslash tests

Mostly ones that can't be baselined, but I switched a couple more over
to baselines

* Improve types and documentation

* Test+fix @link emit, scrub other TODOs

* update API baselines

* test that goto-def works with @link

* Split link displaypart into 3

One for link prefix and suffix, one for link name, and one for link
text.

* update baselines

* Provide JSDocTagInfo.text: string to full clients by default

Instead of upgrading them to displayparts.

* Real server tests

* Disambiguate {@link} and @param x {type}

They are ambiguous; previously the parser preferred the type
interpretation, but will now look ahead and parse links instead when the
prefix is `{@link`.

* Add explanatory comment in test

* fix location in richResponse in protocol

* update API baseline

* Address PR comments

1. Add a cross-file goto-def test.
2. Switch from per-message args to UserPreference.

* use arraysEqual from core

Author: sandersn

src/compiler/checker.ts

@@ -5187,7 +5187,7 @@ namespace ts {
                 function preserveCommentsOn<T extends Node>(node: T) {
                     if (some(propertySymbol.declarations, d => d.kind === SyntaxKind.JSDocPropertyTag)) {
                         const d = propertySymbol.declarations?.find(d => d.kind === SyntaxKind.JSDocPropertyTag)! as JSDocPropertyTag;
-                        const commentText = d.comment;
+                        const commentText = getTextOfJSDocComment(d.comment);
                         if (commentText) {
                             setSyntheticLeadingComments(node, [{ kind: SyntaxKind.MultiLineCommentTrivia, text: "*\n * " + commentText.replace(/\n/g, "\n * ") + "\n ", pos: -1, end: -1, hasTrailingNewLine: true }]);
                         }
@@ -6702,7 +6702,7 @@ namespace ts {
                     const typeParams = getSymbolLinks(symbol).typeParameters;
                     const typeParamDecls = map(typeParams, p => typeParameterToDeclaration(p, context));
                     const jsdocAliasDecl = symbol.declarations?.find(isJSDocTypeAlias);
-                    const commentText = jsdocAliasDecl ? jsdocAliasDecl.comment || jsdocAliasDecl.parent.comment : undefined;
+                    const commentText = getTextOfJSDocComment(jsdocAliasDecl ? jsdocAliasDecl.comment || jsdocAliasDecl.parent.comment : undefined);
                     const oldFlags = context.flags;
                     context.flags |= NodeBuilderFlags.InTypeAlias;
                     const oldEnclosingDecl = context.enclosingDeclaration;
@@ -38577,6 +38577,10 @@ namespace ts {
                 const meaning = SymbolFlags.Type | SymbolFlags.Namespace | SymbolFlags.Value;
                 return resolveEntityName(<EntityName>name, meaning, /*ignoreErrors*/ false, /*dontResolveAlias*/ true, getHostSignatureFromJSDoc(name));
             }
+            else if (isJSDocLink(name.parent)) {
+                const meaning = SymbolFlags.Type | SymbolFlags.Namespace | SymbolFlags.Value;
+                return resolveEntityName(<EntityName>name, meaning, /*ignoreErrors*/ true);
+            }
 
             if (name.parent.kind === SyntaxKind.TypePredicate) {
                 return resolveEntityName(<Identifier>name, /*meaning*/ SymbolFlags.FunctionScopedVariable);

src/compiler/emitter.ts

@@ -3565,13 +3565,16 @@ namespace ts {
         function emitJSDoc(node: JSDoc) {
             write("/**");
             if (node.comment) {
-                const lines = node.comment.split(/\r\n?|\n/g);
-                for (const line of lines) {
-                    writeLine();
-                    writeSpace();
-                    writePunctuation("*");
-                    writeSpace();
-                    write(line);
+                const text = getTextOfJSDocComment(node.comment);
+                if (text) {
+                    const lines = text.split(/\r\n?|\n/g);
+                    for (const line of lines) {
+                        writeLine();
+                        writeSpace();
+                        writePunctuation("*");
+                        writeSpace();
+                        write(line);
+                    }
                 }
             }
             if (node.tags) {
@@ -3704,10 +3707,11 @@ namespace ts {
             emit(tagName);
         }
 
-        function emitJSDocComment(comment: string | undefined) {
-            if (comment) {
+        function emitJSDocComment(comment: NodeArray<JSDocText | JSDocLink> | undefined) {
+            const text = getTextOfJSDocComment(comment);
+            if (text) {
                 writeSpace();
-                write(comment);
+                write(text);
             }
         }
 

src/compiler/factory/nodeFactory.ts

@@ -770,6 +770,10 @@ namespace ts {
         return node.kind === SyntaxKind.JSDocNameReference;
     }
 
+    export function isJSDocLink(node: Node): node is JSDocLink {
+        return node.kind === SyntaxKind.JSDocLink;
+    }
+
     export function isJSDocAllType(node: Node): node is JSDocAllType {
         return node.kind === SyntaxKind.JSDocAllType;
     }

src/compiler/factory/nodeTests.ts

@@ -896,6 +896,11 @@ namespace ts {
         return getJSDocTags(node).filter(doc => doc.kind === kind);
     }
 
+    /** Gets the text of a jsdoc comment, flattening links to their text. */
+    export function getTextOfJSDocComment(comment?: NodeArray<JSDocText | JSDocLink>) {
+        return comment?.map(c => c.kind === SyntaxKind.JSDocText ? c.text : `{@link ${c.name ? entityNameToString(c.name) + " " : ""}${c.text}}`).join("");
+    }
+
     /**
      * Gets the effective type parameters. If the node was parsed in a
      * JavaScript file, gets the type parameters from the `@template` tag from JSDoc.
@@ -1860,7 +1865,13 @@ namespace ts {
 
     /** True if node is of a kind that may contain comment text. */
     export function isJSDocCommentContainingNode(node: Node): boolean {
-        return node.kind === SyntaxKind.JSDocComment || node.kind === SyntaxKind.JSDocNamepathType || isJSDocTag(node) || isJSDocTypeLiteral(node) || isJSDocSignature(node);
+        return node.kind === SyntaxKind.JSDocComment
+            || node.kind === SyntaxKind.JSDocNamepathType
+            || node.kind === SyntaxKind.JSDocText
+            || node.kind === SyntaxKind.JSDocLink
+            || isJSDocTag(node)
+            || isJSDocTypeLiteral(node)
+            || isJSDocSignature(node);
     }
 
     // TODO: determine what this does before making it public.

src/compiler/parser.ts

@@ -1229,7 +1229,7 @@ namespace ts {
 
     /** @deprecated Use `factory.createJSDocParameterTag` or the factory supplied by your transformation context instead. */
     export const createJSDocParamTag = Debug.deprecate(function createJSDocParamTag(name: EntityName, isBracketed: boolean, typeExpression?: JSDocTypeExpression, comment?: string): JSDocParameterTag {
-        return factory.createJSDocParameterTag(/*tagName*/ undefined, name, isBracketed, typeExpression, /*isNameFirst*/ false, comment);
+        return factory.createJSDocParameterTag(/*tagName*/ undefined, name, isBracketed, typeExpression, /*isNameFirst*/ false, comment ? factory.createNodeArray([factory.createJSDocText(comment)]) : undefined);
     }, factoryDeprecation);
 
     /** @deprecated Use `factory.createComma` or the factory supplied by your transformation context instead. */
@@ -1374,4 +1374,4 @@ namespace ts {
     });
 
     // #endregion Renamed node Tests
-}
+}

src/compiler/types.ts

@@ -175,8 +175,8 @@ namespace ts.server {
                 kindModifiers: body.kindModifiers,
                 textSpan: this.decodeSpan(body, fileName),
                 displayParts: [{ kind: "text", text: body.displayString }],
-                documentation: [{ kind: "text", text: body.documentation }],
-                tags: body.tags
+                documentation: typeof body.documentation === "string" ? [{ kind: "text", text: body.documentation }] : body.documentation,
+                tags: this.decodeLinkDisplayParts(body.tags)
             };
         }
 
@@ -536,6 +536,13 @@ namespace ts.server {
                 this.lineOffsetToPosition(fileName, span.end, lineMap));
         }
 
+        private decodeLinkDisplayParts(tags: (protocol.JSDocTagInfo | JSDocTagInfo)[]): JSDocTagInfo[] {
+            return tags.map(tag => typeof tag.text === "string" ? {
+                ...tag,
+                text: [textPart(tag.text)]
+            } : (tag as JSDocTagInfo));
+        }
+
         getNameOrDottedNameSpan(_fileName: string, _startPos: number, _endPos: number): TextSpan {
             return notImplemented();
         }
@@ -554,9 +561,10 @@ namespace ts.server {
                 return undefined;
             }
 
-            const { items, applicableSpan: encodedApplicableSpan, selectedItemIndex, argumentIndex, argumentCount } = response.body;
+            const { items: encodedItems, applicableSpan: encodedApplicableSpan, selectedItemIndex, argumentIndex, argumentCount } = response.body;
 
-            const applicableSpan = this.decodeSpan(encodedApplicableSpan, fileName);
+            const applicableSpan = encodedApplicableSpan as unknown as TextSpan;
+            const items = (encodedItems as (SignatureHelpItem | protocol.SignatureHelpItem)[]).map(item => ({ ...item, tags: this.decodeLinkDisplayParts(item.tags) }));
 
             return { items, applicableSpan, selectedItemIndex, argumentIndex, argumentCount };
         }

src/compiler/utilitiesPublic.ts

@@ -1583,7 +1583,7 @@ namespace FourSlash {
             assert.equal(actualTags.length, (options.tags || ts.emptyArray).length, this.assertionMessageAtLastKnownMarker("signature help tags"));
             ts.zipWith((options.tags || ts.emptyArray), actualTags, (expectedTag, actualTag) => {
                 assert.equal(actualTag.name, expectedTag.name);
-                assert.equal(actualTag.text, expectedTag.text, this.assertionMessageAtLastKnownMarker("signature help tag " + actualTag.name));
+                assert.deepEqual(actualTag.text, expectedTag.text, this.assertionMessageAtLastKnownMarker("signature help tag " + actualTag.name));
             });
 
             const allKeys: readonly (keyof FourSlashInterface.VerifySignatureHelpOptions)[] = [

src/deprecatedCompat/deprecations.ts

@@ -979,6 +979,16 @@ namespace ts.server.protocol {
         file: string;
     }
 
+    export interface JSDocTagInfo {
+        /** Name of the JSDoc tag */
+        name: string;
+        /**
+         * Comment text after the JSDoc tag -- the text after the tag name until the next tag or end of comment
+         * Display parts when UserPreferences.displayPartsForJSDoc is true, flattened to string otherwise.
+         */
+        text?: string | SymbolDisplayPart[];
+    }
+
     export interface TextSpanWithContext extends TextSpan {
         contextStart?: Location;
         contextEnd?: Location;
@@ -1951,6 +1961,7 @@ namespace ts.server.protocol {
      */
     export interface QuickInfoRequest extends FileLocationRequest {
         command: CommandTypes.Quickinfo;
+        arguments: FileLocationRequestArgs;
     }
 
     /**
@@ -1984,8 +1995,9 @@ namespace ts.server.protocol {
 
         /**
          * Documentation associated with symbol.
+         * Display parts when UserPreferences.displayPartsForJSDoc is true, flattened to string otherwise.
          */
-        documentation: string;
+        documentation: string | SymbolDisplayPart[];
 
         /**
          * JSDoc tags associated with symbol.
@@ -2208,6 +2220,12 @@ namespace ts.server.protocol {
         kind: string;
     }
 
+    /** A part of a symbol description that links from a jsdoc @link tag to a declaration */
+    export interface JSDocLinkDisplayPart extends SymbolDisplayPart {
+        /** The location of the declaration that the @link tag links to. */
+        target: FileSpan;
+    }
+
     /**
      * An item found in a completion response.
      */
@@ -3301,6 +3319,7 @@ namespace ts.server.protocol {
         readonly allowRenameOfImportPath?: boolean;
         readonly includePackageJsonAutoImports?: "auto" | "on" | "off";
 
+        readonly displayPartsForJSDoc?: boolean;
         readonly generateReturnInDocTemplate?: boolean;
     }
 

src/harness/client.ts

@@ -1274,6 +1274,32 @@ namespace ts.server {
                 result;
         }
 
+        private mapJSDocTagInfo(tags: JSDocTagInfo[] | undefined, project: Project, richResponse: boolean): protocol.JSDocTagInfo[] {
+            return tags ? tags.map(tag => ({
+                ...tag,
+                text: richResponse ? this.mapDisplayParts(tag.text, project) : tag.text?.map(part => part.text).join("")
+            })) : [];
+        }
+
+        private mapDisplayParts(parts: SymbolDisplayPart[] | undefined, project: Project): protocol.SymbolDisplayPart[] {
+            if (!parts) {
+                return [];
+            }
+            return parts.map(part => part.kind !== "linkName" ? part : {
+                ...part,
+                target: this.toFileSpan((part as JSDocLinkDisplayPart).target.fileName, (part as JSDocLinkDisplayPart).target.textSpan, project),
+            });
+        }
+
+        private mapSignatureHelpItems(items: SignatureHelpItem[], project: Project, richResponse: boolean): protocol.SignatureHelpItem[] {
+            return items.map(item => ({
+                ...item,
+                documentation: this.mapDisplayParts(item.documentation, project),
+                parameters: item.parameters.map(p => ({ ...p, documentation: this.mapDisplayParts(p.documentation, project) })),
+                tags: this.mapJSDocTagInfo(item.tags, project, richResponse),
+            }));
+        }
+
         private mapDefinitionInfo(definitions: readonly DefinitionInfo[], project: Project): readonly protocol.FileSpanWithContext[] {
             return definitions.map(def => this.toFileSpanWithContext(def.fileName, def.textSpan, def.contextSpan, project));
         }
@@ -1685,22 +1711,24 @@ namespace ts.server {
                 return undefined;
             }
 
+            const useDisplayParts = !!this.getPreferences(file).displayPartsForJSDoc;
             if (simplifiedResult) {
                 const displayString = displayPartsToString(quickInfo.displayParts);
-                const docString = displayPartsToString(quickInfo.documentation);
-
                 return {
                     kind: quickInfo.kind,
                     kindModifiers: quickInfo.kindModifiers,
                     start: scriptInfo.positionToLineOffset(quickInfo.textSpan.start),
                     end: scriptInfo.positionToLineOffset(textSpanEnd(quickInfo.textSpan)),
                     displayString,
-                    documentation: docString,
-                    tags: quickInfo.tags || []
+                    documentation: useDisplayParts ? this.mapDisplayParts(quickInfo.documentation, project) : displayPartsToString(quickInfo.documentation),
+                    tags: this.mapJSDocTagInfo(quickInfo.tags, project, useDisplayParts),
                 };
             }
             else {
-                return quickInfo;
+                return useDisplayParts ? quickInfo : {
+                    ...quickInfo,
+                    tags: this.mapJSDocTagInfo(quickInfo.tags, project, /*useDisplayParts*/ false) as JSDocTagInfo[]
+                };
             }
         }
 
@@ -1830,19 +1858,25 @@ namespace ts.server {
             return res;
         }
 
-        private getCompletionEntryDetails(args: protocol.CompletionDetailsRequestArgs, simplifiedResult: boolean): readonly protocol.CompletionEntryDetails[] | readonly CompletionEntryDetails[] {
+        private getCompletionEntryDetails(args: protocol.CompletionDetailsRequestArgs, fullResult: boolean): readonly protocol.CompletionEntryDetails[] | readonly CompletionEntryDetails[] {
             const { file, project } = this.getFileAndProject(args);
             const scriptInfo = this.projectService.getScriptInfoForNormalizedPath(file)!;
             const position = this.getPosition(args, scriptInfo);
             const formattingOptions = project.projectService.getFormatCodeOptions(file);
+            const useDisplayParts = !!this.getPreferences(file).displayPartsForJSDoc;
 
             const result = mapDefined(args.entryNames, entryName => {
                 const { name, source, data } = typeof entryName === "string" ? { name: entryName, source: undefined, data: undefined } : entryName;
                 return project.getLanguageService().getCompletionEntryDetails(file, position, name, formattingOptions, source, this.getPreferences(file), data ? cast(data, isCompletionEntryData) : undefined);
             });
-            return simplifiedResult
-                ? result.map(details => ({ ...details, codeActions: map(details.codeActions, action => this.mapCodeAction(action)) }))
-                : result;
+            return fullResult
+                ? (useDisplayParts ? result : result.map(details => ({ ...details, tags: this.mapJSDocTagInfo(details.tags, project, /*richResponse*/ false) as JSDocTagInfo[] })))
+                : result.map(details => ({
+                    ...details,
+                    codeActions: map(details.codeActions, action => this.mapCodeAction(action)),
+                    documentation: this.mapDisplayParts(details.documentation, project),
+                    tags: this.mapJSDocTagInfo(details.tags, project, useDisplayParts),
+                }));
         }
 
         private getCompileOnSaveAffectedFileList(args: protocol.FileRequestArgs): readonly protocol.CompileOnSaveAffectedFileListSingleProject[] {
@@ -1902,26 +1936,27 @@ namespace ts.server {
             const scriptInfo = this.projectService.getScriptInfoForNormalizedPath(file)!;
             const position = this.getPosition(args, scriptInfo);
             const helpItems = project.getLanguageService().getSignatureHelpItems(file, position, args);
-            if (!helpItems) {
-                return undefined;
-            }
-
-            if (simplifiedResult) {
+            const useDisplayParts = !!this.getPreferences(file).displayPartsForJSDoc;
+            if (helpItems && simplifiedResult) {
                 const span = helpItems.applicableSpan;
                 return {
-                    items: helpItems.items,
+                    ...helpItems,
                     applicableSpan: {
                         start: scriptInfo.positionToLineOffset(span.start),
                         end: scriptInfo.positionToLineOffset(span.start + span.length)
                     },
-                    selectedItemIndex: helpItems.selectedItemIndex,
-                    argumentIndex: helpItems.argumentIndex,
-                    argumentCount: helpItems.argumentCount,
+                    items: this.mapSignatureHelpItems(helpItems.items, project, useDisplayParts),
                 };
             }
-            else {
+            else if (useDisplayParts || !helpItems) {
                 return helpItems;
             }
+            else {
+                return {
+                    ...helpItems,
+                    items: helpItems.items.map(item => ({ ...item, tags: this.mapJSDocTagInfo(item.tags, project, /*richResponse*/ false) as JSDocTagInfo[] }))
+                };
+            }
         }
 
         private toPendingErrorCheck(uncheckedFileName: string): PendingErrorCheck | undefined {
@@ -2700,10 +2735,10 @@ namespace ts.server {
                 return this.requiredResponse(this.getCompletions(request.arguments, CommandNames.CompletionsFull));
             },
             [CommandNames.CompletionDetails]: (request: protocol.CompletionDetailsRequest) => {
-                return this.requiredResponse(this.getCompletionEntryDetails(request.arguments, /*simplifiedResult*/ true));
+                return this.requiredResponse(this.getCompletionEntryDetails(request.arguments, /*fullResult*/ false));
             },
             [CommandNames.CompletionDetailsFull]: (request: protocol.CompletionDetailsRequest) => {
-                return this.requiredResponse(this.getCompletionEntryDetails(request.arguments, /*simplifiedResult*/ false));
+                return this.requiredResponse(this.getCompletionEntryDetails(request.arguments, /*fullResult*/ true));
             },
             [CommandNames.CompileOnSaveAffectedFileList]: (request: protocol.CompileOnSaveAffectedFileListRequest) => {
                 return this.requiredResponse(this.getCompileOnSaveAffectedFileList(request.arguments));

src/harness/fourslashImpl.ts

@@ -740,6 +740,9 @@ namespace ts {
                             pos = tag.end;
                             break;
                     }
+                    if (tag.comment) {
+                        pushCommentRange(tag.comment.pos, tag.comment.end - tag.comment.pos);
+                    }
                 }
             }