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
This commit is contained in:
Nathan Shively-Sanders authored and GitHub committed 2021-03-16 16:26:01 -07:00
1 parent 3da5982c9a
commit ec77bff332
155 files changed
+20286 -1432

No files matched your search

+1
View File
@@ -179,6 +179,7 @@
"unittests/tsserver/importHelpers.ts",
"unittests/tsserver/importSuggestionsCache.ts",
"unittests/tsserver/inferredProjects.ts",
"unittests/tsserver/jsdocTag.ts",
"unittests/tsserver/languageService.ts",
"unittests/tsserver/maxNodeModuleJsDepth.ts",
"unittests/tsserver/metadataInResponse.ts",
+16 -1
View File
@@ -312,8 +312,23 @@ namespace ts {
*/`);
parsesCorrectly("@link tags",
`/**
* {@link first link}
* {@link first }
* Inside {@link link text} thing
* @param foo See also {@link A.Reference}
* @param bar Or see {@link http://www.zombocom.com }
* {@link Standalone.Complex }
* This empty one: {@link} is OK.
* This double-space one: {@link doubled } is OK too.
* This should work, despite being badly formatted: {@link
oh.no
}
* Forgot to close this one {@link https://typescriptlang.org
* But it's still OK.
* Although it skips the newline so parses the asterisks in the wrong state.
* This shouldn't work: {@link
* nope
* }, because of the intermediate asterisks.
* @author Alfa Romero <a@parsing.com> See my home page: {@link https://example.com}
*/`);
parsesCorrectly("authorTag",
`/**
+3 -1
View File
@@ -67,7 +67,9 @@ function test() {}`;
const funcDec = testSourceFile.statements.find(ts.isFunctionDeclaration)!;
const tags = ts.getJSDocTags(funcDec);
assert.isDefined(tags[0].comment);
assert.equal(tags[0].comment, "Some\n text\r\n with newlines.");
assert.isDefined(tags[0].comment![0]);
assert.equal(tags[0].comment![0].kind, ts.SyntaxKind.JSDocText);
assert.equal(tags[0].comment![0].text, "Some\n text\r\n with newlines.");
});
});
@@ -69,7 +69,6 @@ namespace ts.projectSystem {
kindModifiers: ScriptElementKindModifier.exportedModifier,
name: "foo",
source: [{ text: "./a", kind: "text" }],
tags: undefined,
};
assert.deepEqual<readonly protocol.CompletionEntryDetails[] | undefined>(detailsResponse, [
{
@@ -91,6 +90,7 @@ namespace ts.projectSystem {
commands: undefined,
},
],
tags: [],
...detailsCommon,
},
]);
@@ -117,6 +117,7 @@ namespace ts.projectSystem {
commands: undefined,
}
],
tags: [],
...detailsCommon,
}
]);
@@ -0,0 +1,693 @@
namespace ts.projectSystem {
describe("unittests:: tsserver:: jsdoc @link ", () => {
const config: File = {
path: "/a/tsconfig.json",
content: `{
"compilerOptions": {
"checkJs": true,
"noEmit": true
}
"files": ["someFile1.js"]
}
`
};
function assertQuickInfoJSDoc(file: File, options: {
displayPartsForJSDoc: boolean,
command: protocol.CommandTypes,
tags: string | unknown[] | undefined,
documentation: string | unknown[]
}) {
const { command, displayPartsForJSDoc, tags, documentation } = options;
const session = createSession(createServerHost([file, config]));
session.getProjectService().setHostConfiguration({ preferences: { displayPartsForJSDoc } });
openFilesForSession([file], session);
const indexOfX = file.content.indexOf("x");
const quickInfo = session.executeCommandSeq<protocol.QuickInfoRequest>({
command: command as protocol.CommandTypes.Quickinfo,
arguments: {
file: file.path,
position: indexOfX,
} as protocol.FileLocationRequestArgs
}).response;
const summaryAndLocation = command === protocol.CommandTypes.Quickinfo ? {
displayString: "var x: number",
start: {
line: 3,
offset: 5,
},
end: {
line: 3,
offset: 6,
}
} : {
displayParts: [{
kind: "keyword",
text: "var",
}, {
kind: "space",
text: " ",
}, {
kind: "localName",
text: "x",
}, {
kind: "punctuation",
text: ":",
}, {
kind: "space",
text: " ",
}, {
kind: "keyword",
text: "number",
}],
textSpan: {
length: 1,
start: 38,
}
};
assert.deepEqual(quickInfo, {
kind: "var",
kindModifiers: "",
...summaryAndLocation,
documentation,
tags
});
}
const linkInTag: File = {
path: "/a/someFile1.js",
content: `class C { }
/** @wat {@link C} */
var x = 1`
};
const linkInComment: File = {
path: "/a/someFile1.js",
content: `class C { }
/** {@link C} */
var x = 1
;`
};
it("for quickinfo, should provide display parts plus a span for a working link in a tag", () => {
assertQuickInfoJSDoc(linkInTag, {
command: protocol.CommandTypes.Quickinfo,
displayPartsForJSDoc: true,
documentation: [],
tags: [{
name: "wat",
text: [{
kind: "text",
text: "",
}, {
kind: "link",
text: "{@link ",
}, {
kind: "linkName",
target: {
end: {
line: 1,
offset: 12,
},
file: "/a/someFile1.js",
start: {
line: 1,
offset: 1,
},
},
text: "C",
}, {
kind: "link",
text: "}",
}]
}],
});
});
it("for quickinfo, should provide a string for a working link in a tag", () => {
assertQuickInfoJSDoc(linkInTag, {
command: protocol.CommandTypes.Quickinfo,
displayPartsForJSDoc: false,
documentation: "",
tags: [{
name: "wat",
text: "{@link C}"
}],
});
});
it("for quickinfo, should provide display parts for a working link in a comment", () => {
assertQuickInfoJSDoc(linkInComment, {
command: protocol.CommandTypes.Quickinfo,
displayPartsForJSDoc: true,
documentation: [{
kind: "text",
text: "",
}, {
kind: "link",
text: "{@link ",
}, {
kind: "linkName",
target: {
end: {
line: 1,
offset: 12,
},
file: "/a/someFile1.js",
start: {
line: 1,
offset: 1,
},
},
text: "C",
}, {
kind: "link",
text: "}",
}],
tags: [],
});
});
it("for quickinfo, should provide a string for a working link in a comment", () => {
assertQuickInfoJSDoc(linkInComment, {
command: protocol.CommandTypes.Quickinfo,
displayPartsForJSDoc: false,
documentation: "{@link C}",
tags: [],
});
});
it("for quickinfo-full, should provide display parts plus a span for a working link in a tag", () => {
assertQuickInfoJSDoc(linkInTag, {
command: protocol.CommandTypes.QuickinfoFull,
displayPartsForJSDoc: true,
documentation: [],
tags: [{
name: "wat",
text: [{
kind: "text",
text: "",
}, {
kind: "link",
text: "{@link ",
}, {
kind: "linkName",
target: {
fileName: "/a/someFile1.js",
textSpan: {
length: 11,
start: 0
},
},
text: "C",
}, {
kind: "link",
text: "}",
}]
}],
});
});
it("for quickinfo-full, should provide a string for a working link in a tag", () => {
assertQuickInfoJSDoc(linkInTag, {
command: protocol.CommandTypes.QuickinfoFull,
displayPartsForJSDoc: false,
documentation: [],
tags: [{
name: "wat",
text: "{@link C}"
}],
});
});
it("for quickinfo-full, should provide display parts plus a span for a working link in a comment", () => {
assertQuickInfoJSDoc(linkInComment, {
command: protocol.CommandTypes.QuickinfoFull,
displayPartsForJSDoc: true,
documentation: [{
kind: "text",
text: "",
}, {
kind: "link",
text: "{@link ",
}, {
kind: "linkName",
target: {
fileName: "/a/someFile1.js",
textSpan: {
length: 11,
start: 0
},
},
text: "C",
}, {
kind: "link",
text: "}",
}],
tags: undefined,
});
});
it("for quickinfo-full, should provide a string for a working link in a comment", () => {
assertQuickInfoJSDoc(linkInComment, {
command: protocol.CommandTypes.QuickinfoFull,
displayPartsForJSDoc: false,
documentation: [{
kind: "text",
text: "",
}, {
kind: "link",
text: "{@link ",
}, {
kind: "linkName",
target: {
fileName: "/a/someFile1.js",
textSpan: {
length: 11,
start: 0
},
},
text: "C",
}, {
kind: "link",
text: "}",
}],
tags: [],
});
});
function assertSignatureHelpJSDoc(options: {
displayPartsForJSDoc: boolean,
command: protocol.CommandTypes,
documentation: string | unknown[],
tags: unknown[]
}) {
const linkInParamTag: File = {
path: "/a/someFile1.js",
content: `class C { }
/** @param y - {@link C} */
function x(y) { }
x(1)`
};
const { command, displayPartsForJSDoc, documentation, tags } = options;
const session = createSession(createServerHost([linkInParamTag, config]));
session.getProjectService().setHostConfiguration({ preferences: { displayPartsForJSDoc } });
openFilesForSession([linkInParamTag], session);
const indexOfX = linkInParamTag.content.lastIndexOf("1");
const signatureHelp = session.executeCommandSeq<protocol.SignatureHelpRequest>({
command: command as protocol.CommandTypes.SignatureHelp,
arguments: {
triggerReason: {
kind: "invoked"
},
file: linkInParamTag.path,
position: indexOfX,
} as protocol.SignatureHelpRequestArgs
}).response;
const applicableSpan = command === protocol.CommandTypes.SignatureHelp ? {
end: {
line: 4,
offset: 4
},
start: {
line: 4,
offset: 3
}
} : {
length: 1,
start: 60
};
assert.deepEqual(signatureHelp, {
applicableSpan,
argumentCount: 1,
argumentIndex: 0,
selectedItemIndex: 0,
items: [{
documentation: [],
isVariadic: false,
parameters: [{
displayParts: [{
kind: "parameterName",
text: "y"
}, {
kind: "punctuation",
text: ":"
}, {
kind: "space",
text: " "
}, {
kind: "keyword",
text: "any"
}],
documentation,
isOptional: false,
isRest: false,
name: "y"
}],
prefixDisplayParts: [
{
kind: "functionName",
text: "x",
},
{
kind: "punctuation",
text: "(",
},
],
separatorDisplayParts: [
{
kind: "punctuation",
text: ",",
},
{
kind: "space",
text: " ",
},
],
suffixDisplayParts: [
{
kind: "punctuation",
text: ")",
},
{
kind: "punctuation",
text: ":",
},
{
kind: "space",
text: " ",
},
{
kind: "keyword",
text: "void",
}
],
tags,
}],
});
}
it("for signature help, should provide a string for a working link in a comment", () => {
assertSignatureHelpJSDoc({
command: protocol.CommandTypes.SignatureHelp,
displayPartsForJSDoc: false,
tags: [{
name: "param",
text: "y - {@link C}"
}],
documentation: [{
kind: "text",
text: "- "
}, {
kind: "link",
text: "{@link "
}, {
kind: "linkName",
target: {
file: "/a/someFile1.js",
start: {
line: 1,
offset: 1
},
end: {
line: 1,
offset: 12
}
},
text: "C"
}, {
kind: "link",
text: "}"
}],
});
});
it("for signature help, should provide display parts for a working link in a comment", () => {
const tags = [{
name: "param",
text: [{
kind: "text",
text: "y"
}, {
kind: "space",
text: " "
}, {
kind: "text",
text: "- "
}, {
kind: "link",
text: "{@link "
}, {
kind: "linkName",
target: {
file: "/a/someFile1.js",
start: {
line: 1,
offset: 1
},
end: {
line: 1,
offset: 12
}
},
text: "C"
}, {
kind: "link",
text: "}"
}]
}];
assertSignatureHelpJSDoc({
command: protocol.CommandTypes.SignatureHelp,
displayPartsForJSDoc: true,
tags,
documentation: tags[0].text.slice(2)
});
});
it("for signature help-full, should provide a string for a working link in a comment", () => {
assertSignatureHelpJSDoc({
command: protocol.CommandTypes.SignatureHelpFull,
displayPartsForJSDoc: false,
tags: [{
name: "param",
text: "y - {@link C}"
}],
documentation: [{
kind: "text",
text: "- "
}, {
kind: "link",
text: "{@link "
}, {
kind: "linkName",
target: {
fileName: "/a/someFile1.js",
textSpan: {
length: 11,
start: 0
}
},
text: "C"
}, {
kind: "link",
text: "}"
}],
});
});
it("for signature help-full, should provide display parts for a working link in a comment", () => {
const tags = [{
name: "param",
text: [{
kind: "text",
text: "y"
}, {
kind: "space",
text: " "
}, {
kind: "text",
text: "- "
}, {
kind: "link",
text: "{@link "
}, {
kind: "linkName",
target: {
fileName: "/a/someFile1.js",
textSpan: {
length: 11,
start: 0
}
},
text: "C"
}, {
kind: "link",
text: "}"
}]
}];
assertSignatureHelpJSDoc({
command: protocol.CommandTypes.SignatureHelpFull,
displayPartsForJSDoc: true,
tags,
documentation: tags[0].text.slice(2),
});
});
function assertCompletionsJSDoc(options: {
displayPartsForJSDoc: boolean,
command: protocol.CommandTypes,
tags: unknown[]
}) {
const linkInParamJSDoc: File = {
path: "/a/someFile1.js",
content: `class C { }
/** @param x - see {@link C} */
function foo (x) { }
foo`
};
const { command, displayPartsForJSDoc, tags } = options;
const session = createSession(createServerHost([linkInParamJSDoc, config]));
session.getProjectService().setHostConfiguration({ preferences: { displayPartsForJSDoc } });
openFilesForSession([linkInParamJSDoc], session);
const indexOfFoo = linkInParamJSDoc.content.lastIndexOf("fo");
const completions = session.executeCommandSeq<protocol.CompletionDetailsRequest>({
command: command as protocol.CommandTypes.CompletionDetails,
arguments: {
entryNames: ["foo"],
file: linkInParamJSDoc.path,
position: indexOfFoo,
} as protocol.CompletionDetailsRequestArgs
}).response;
assert.deepEqual(completions, [{
codeActions: undefined,
displayParts: [{
kind: "keyword",
text: "function",
}, {
kind: "space",
text: " ",
}, {
kind: "functionName",
text: "foo",
}, {
kind: "punctuation",
text: "(",
}, {
kind: "parameterName",
text: "x",
}, {
kind: "punctuation",
text: ":",
}, {
kind: "space",
text: " ",
}, {
kind: "keyword",
text: "any",
}, {
kind: "punctuation",
text: ")",
}, {
kind: "punctuation",
text: ":",
}, {
kind: "space",
text: " ",
}, {
kind: "keyword",
text: "void",
}],
documentation: [],
kind: "function",
kindModifiers: "",
name: "foo",
source: undefined,
tags,
}]);
}
it("for completions, should provide display parts for a working link in a comment", () => {
assertCompletionsJSDoc({
command: protocol.CommandTypes.CompletionDetails,
displayPartsForJSDoc: true,
tags: [{
name: "param",
text: [{
kind: "text",
text: "x"
}, {
kind: "space",
text: " "
}, {
kind: "text",
text: "- see "
}, {
kind: "link",
text: "{@link "
}, {
kind: "linkName",
target: {
file: "/a/someFile1.js",
end: {
line: 1,
offset: 12,
},
start: {
line: 1,
offset: 1,
}
},
text: "C"
}, {
kind: "link",
text: "}"
}],
}],
});
});
it("for completions, should provide a string for a working link in a comment", () => {
assertCompletionsJSDoc({
command: protocol.CommandTypes.CompletionDetails,
displayPartsForJSDoc: false,
tags: [{
name: "param",
text: "x - see {@link C}",
}],
});
});
it("for completions-full, should provide display parts for a working link in a comment", () => {
assertCompletionsJSDoc({
command: protocol.CommandTypes.CompletionDetailsFull,
displayPartsForJSDoc: true,
tags: [{
name: "param",
text: [{
kind: "text",
text: "x"
}, {
kind: "space",
text: " "
}, {
kind: "text",
text: "- see "
}, {
kind: "link",
text: "{@link "
}, {
kind: "linkName",
target: {
fileName: "/a/someFile1.js",
textSpan: {
length: 11,
start: 0
}
},
text: "C"
}, {
kind: "link",
text: "}"
}],
}],
});
});
it("for completions-full, should provide a string for a working link in a comment", () => {
assertCompletionsJSDoc({
command: protocol.CommandTypes.CompletionDetailsFull,
displayPartsForJSDoc: false,
tags: [{
name: "param",
text: "x - see {@link C}",
}],
});
});
});
}