Editor support for link tag #41877

sandersn · 2020-12-08T17:12:43Z

Fixes #35524 (80% solution)

This PR makes the parser parse @link tag and the language service offer symbols for entity names found at the beginning of those tags. Links are stored redundantly with comment text, so they're only used to provide (1) a span to an editor to format in some way (2) a symbol for the declaration of the link's target.

Future PRs

Parse # as type-space element access: Class#method. As well as, possibly, the normal TS syntax Class["method"], which doesn't currently parse either.

Open questions

I parse @see {@link ...} as a @see with no reference and a link in its comment text. I think that's OK.
I intentionally do not parse { @link X}, with a space separating { and @. I saw this only twice in my corpus, but @amcasey points out that it's easy to support with an additional skipWhitespace call. I originally skipped it because I had slightly less lookahead when the next token after { was @, but that made the code unreadable, so I dropped it.

Resolved questions

I introduced JSDocText and JSDocLink nodes into the AST, which better reflects the semantic relation of comments to their tags. It is more expensive, though, it means that jsdoc comment text is treated as a first-class member of the parse tree now.

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

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

@mjbvz

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

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.

typescript-bot · 2020-12-08T17:12:47Z

Thanks for the PR! It looks like you've changed the TSServer protocol in some way. Please ensure that any changes here don't break consumers of the current TSServer API. For some extra review, we'll ping @sheetalkamat, @amcasey, @mjbvz, @minestarks for you. Feel free to loop in other consumers/maintainers if necessary

sandersn · 2020-12-08T17:13:42Z

@mjbvz and @amcasey, you should maybe also look at this (at least the protocol part)

andrewbranch · 2020-12-08T18:24:22Z

@typescript-bot pack this

Only thing I’m curious about is if there are some places where JSDoc can go, but otherwise entity names could not go, and therefore might expose a hole in getSymbolAtLocation.

typescript-bot · 2020-12-08T18:24:28Z

Heya @andrewbranch, I've started to run the tarball bundle task on this PR at fce33f1. You can monitor the build here.

sandersn · 2020-12-08T18:29:15Z

@andrewbranch I indeed tried writing more tests and discovered a hole. I'll put up a commit that makes getSymbolAtLocation work with identifiers in links.

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

sandersn · 2021-03-10T17:41:51Z

This is ready for review now.

src/server/protocol.ts

amcasey

The behavior and interface changes generally LGTM. Some suggestions below.

src/compiler/types.ts

src/server/protocol.ts

src/services/jsDoc.ts

src/services/codefixes/inferFromUsage.ts

tests/cases/fourslash/gotoDefinitionLinkTag1.ts

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

sandersn · 2021-03-16T23:25:52Z

I think this PR has had enough review to be ready to use. I'll merge it and address any follow-up in subsequent PRs.

Kingwl · 2021-03-17T03:10:20Z

Cool!

This reverts commit ec77bff.

This reverts commit 451d435.

* Revert "Revert "Editor support for link tag (#41877)" (#43302)" This reverts commit 451d435. * Fix parsing @link at end of comment * Parse comments as string when no @link occurs * fix lint

millsp · 2021-09-30T02:37:34Z

Docs can be updated now https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html

sandersn added 18 commits September 10, 2020 14:19

Initial scribbles

72f19ef

Compiles but provides spans instead of location pairs

c08258b

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

2f1d113

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

Merge branch 'master' into editor-support-for-links

256a60a

Builds w/protocol types + conversions

8ba5dc8

cleanup:better names and scrub TODOs

ca1b273

fix test harness too

867ab34

Misc

5d518d6

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

Merge branch 'master' into editor-support-for-links

82c11fe

more tests and some fixes

90feb3e

Merge branch 'master' into editor-support-for-links

035bb4a

Fix other failing tests

fc813c2

Merge branch 'master' into editor-support-for-links

917314c

fix bad merge

7dd7cab

polish parser

c0e8d47

improve names and array types

8bbc8b4

slight tweaks

070da0b

typescript-bot assigned sandersn Dec 8, 2020

typescript-bot added the Author: Team label Dec 8, 2020

sandersn requested a review from sheetalkamat December 8, 2020 17:12

typescript-bot added the For Uncommitted Bug PR for untriaged, rejected, closed or missing bug label Dec 8, 2020

sandersn requested a review from andrewbranch December 8, 2020 17:13

remove some done TODOs

fce33f1

more tests + resulting fixes

7ac40d4

sandersn added 4 commits March 8, 2021 12:14

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

5a21851

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

ab340f4

Merge branch 'master' into editor-support-for-links

3e5aa10

Merge branch 'master' into editor-support-for-links

618bcec

jessetrinity reviewed Mar 10, 2021

View reviewed changes

src/server/protocol.ts Outdated Show resolved Hide resolved

sandersn added 2 commits March 10, 2021 12:10

fix location in richResponse in protocol

5a29c2e

update API baseline

67c4966

amcasey approved these changes Mar 15, 2021

View reviewed changes

sandersn added 3 commits March 16, 2021 10:17

Merge branch 'master' into editor-support-for-links

2da204a

Address PR comments

d0f3048

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

use arraysEqual from core

4cfdaee

sandersn merged commit ec77bff into master Mar 16, 2021

sandersn deleted the editor-support-for-links branch March 16, 2021 23:26

sandersn added a commit that referenced this pull request Mar 18, 2021

Revert "Editor support for link tag (#41877)"

271c50c

This reverts commit ec77bff.

sandersn added a commit that referenced this pull request Mar 18, 2021

Revert "Editor support for link tag (#41877)" (#43302)

451d435

This reverts commit ec77bff.

sandersn added a commit that referenced this pull request Mar 19, 2021

Revert "Revert "Editor support for link tag (#41877)" (#43302)"

fb892f0

This reverts commit 451d435.

sandersn mentioned this pull request Mar 19, 2021

@link support, second try #43312

Merged

tmair mentioned this pull request May 10, 2021

docs: fix broken links in documentation ReactiveX/rxjs#6380

Merged

orta mentioned this pull request Jun 10, 2021

JSDoc @link not resolved across modules #43869

Open

brendankenny mentioned this pull request Aug 12, 2021

deps: update to typescript@4.4.1-rc GoogleChrome/lighthouse#12909

Merged

caspardue mentioned this pull request Aug 29, 2021

jsdoc/tsdoc not parsed correctly gund/eslint-plugin-deprecation#29

Closed

akudev mentioned this pull request Dec 29, 2021

@sapui5/ts-types-esm - broken links in docs SAP/ui5-typescript#303

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Editor support for link tag #41877

Editor support for link tag #41877

sandersn commented Dec 8, 2020 •

edited

Loading

typescript-bot commented Dec 8, 2020

sandersn commented Dec 8, 2020 •

edited

Loading

andrewbranch commented Dec 8, 2020

typescript-bot commented Dec 8, 2020 •

edited

Loading

sandersn commented Dec 8, 2020

sandersn commented Mar 10, 2021

amcasey left a comment

sandersn commented Mar 16, 2021

Kingwl commented Mar 17, 2021

millsp commented Sep 30, 2021

Editor support for link tag #41877

Editor support for link tag #41877

Conversation

sandersn commented Dec 8, 2020 • edited Loading

Future PRs

Open questions

Resolved questions

typescript-bot commented Dec 8, 2020

sandersn commented Dec 8, 2020 • edited Loading

andrewbranch commented Dec 8, 2020

typescript-bot commented Dec 8, 2020 • edited Loading

sandersn commented Dec 8, 2020

sandersn commented Mar 10, 2021

amcasey left a comment

Choose a reason for hiding this comment

sandersn commented Mar 16, 2021

Kingwl commented Mar 17, 2021

millsp commented Sep 30, 2021

sandersn commented Dec 8, 2020 •

edited

Loading

sandersn commented Dec 8, 2020 •

edited

Loading

typescript-bot commented Dec 8, 2020 •

edited

Loading