Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Editor support for link tag #41877

Merged
merged 58 commits into from
Mar 16, 2021
Merged

Editor support for link tag #41877

merged 58 commits into from
Mar 16, 2021

Conversation

sandersn
Copy link
Member

@sandersn sandersn commented Dec 8, 2020 •
edited
Loading

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

  1. 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

  1. I parse @see {@link ...} as a @see with no reference and a link in its comment text. I think that's OK.
  2. 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

  1. 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.
@sandersn
Initial scribbles
72f19ef
@sandersn
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.
@sandersn
Switch to DocumentSpan
2f1d113 
In theory this is already better supported, but not sure practise bears
that out.
@sandersn
Merge branch 'master' into editor-support-for-links
256a60a
@sandersn
Builds w/protocol types + conversions
8ba5dc8
@sandersn
cleanup:better names and scrub TODOs
ca1b273
@sandersn
fix test harness too
867ab34
@sandersn
Misc
5d518d6 
1. Simplify protocol after talking to @mjbvz.
2. Add more tests.
3. Initial notes about where to add parsing.
@sandersn
Parse and store links in the compiler
c07fe40 
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.
@sandersn
Merge branch 'master' into editor-support-for-links
82c11fe
@sandersn
more tests and some fixes
90feb3e
@sandersn
Merge branch 'master' into editor-support-for-links
035bb4a
@sandersn
Fix other failing tests
fc813c2
@sandersn
Merge branch 'master' into editor-support-for-links
917314c
@sandersn
fix bad merge
7dd7cab
@sandersn
polish parser
c0e8d47
@sandersn
improve names and array types
8bbc8b4
@sandersn
slight tweaks
070da0b
@typescript-bot
Copy link
Collaborator

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
@typescript-bot typescript-bot added the For Uncommitted Bug PR for untriaged, rejected, closed or missing bug label Dec 8, 2020
@sandersn
Copy link
Member Author

sandersn commented Dec 8, 2020 •
edited
Loading

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

@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
Copy link
Collaborator

typescript-bot commented Dec 8, 2020 •
edited
Loading

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

sandersn commented Dec 8, 2020

@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.
@sandersn
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`.
@sandersn
Add explanatory comment in test
ab340f4
@sandersn
Merge branch 'master' into editor-support-for-links
3e5aa10
@sandersn
Merge branch 'master' into editor-support-for-links
618bcec
@sandersn
Copy link
Member Author

This is ready for review now.
@sandersn sandersn moved this from Waiting on author to Needs review in PR Backlog Mar 10, 2021
amcasey
amcasey approved these changes Mar 15, 2021
View reviewed changes
Copy link
Member

@amcasey amcasey left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The behavior and interface changes generally LGTM. Some suggestions below.
src/compiler/types.ts Show resolved Hide resolved
src/server/protocol.ts Outdated Show resolved Hide resolved
src/server/protocol.ts Show resolved Hide resolved
src/server/protocol.ts Outdated Show resolved Hide resolved
src/server/protocol.ts Outdated Show resolved Hide resolved
src/services/jsDoc.ts Show resolved Hide resolved
src/services/codefixes/inferFromUsage.ts Outdated Show resolved Hide resolved
tests/cases/fourslash/gotoDefinitionLinkTag1.ts Show resolved Hide resolved
PR Backlog automation moved this from Needs review to Needs merge Mar 15, 2021
@sandersn
Merge branch 'master' into editor-support-for-links
2da204a
@sandersn
Address PR comments
d0f3048 
1. Add a cross-file goto-def test.
2. Switch from per-message args to UserPreference.
@sandersn
use arraysEqual from core
4cfdaee
@sandersn
Copy link
Member Author

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.
@sandersn sandersn merged commit ec77bff into master Mar 16, 2021
PR Backlog automation moved this from Needs merge to Done Mar 16, 2021
@sandersn sandersn deleted the editor-support-for-links branch March 16, 2021 23:26
@Kingwl
Copy link
Contributor

Kingwl commented Mar 17, 2021

Cool!
sandersn added a commit that referenced this pull request Mar 18, 2021
@sandersn
Revert "Editor support for link tag (#41877)"
271c50c 
This reverts commit ec77bff.
sandersn added a commit that referenced this pull request Mar 18, 2021
@sandersn
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
@sandersn
Revert "Revert "Editor support for link tag (#41877)" (#43302)"
fb892f0 
This reverts commit 451d435.
@sandersn sandersn mentioned this pull request Mar 19, 2021
Merged
sandersn added a commit that referenced this pull request Mar 22, 2021
@sandersn
@link support, second try (#43312)
dcc27eb 
* 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
@tmair tmair mentioned this pull request May 10, 2021
Merged
@orta orta mentioned this pull request Jun 10, 2021
Open
@brendankenny brendankenny mentioned this pull request Aug 12, 2021
Merged
@caspardue caspardue mentioned this pull request Aug 29, 2021
Closed
@millsp
Copy link
Contributor

millsp commented Sep 30, 2021

Docs can be updated now https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html
@akudev akudev mentioned this pull request Dec 29, 2021
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Author: Team For Uncommitted Bug PR for untriaged, rejected, closed or missing bug
10 participants
@sandersn @typescript-bot @andrewbranch @mjbvz @minestarks @Kingwl @millsp @DanielRosenwasser @amcasey @jessetrinity