Skip to content

/ TypeScript

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.

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
+20,456 −1,602

Conversation

@sandersn
Copy link
Member

@sandersn sandersn commented Dec 8, 2020 •
edited

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 added 18 commits Sep 10, 2020
@sandersn
Initial scribbles
Loading status checks…
72f19ef
@sandersn
Compiles but provides spans instead of location pairs
Loading status checks…
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
Loading status checks…
2f1d113 
In theory this is already better supported, but not sure practise bears
that out.
@sandersn
Merge branch 'master' into editor-support-for-links
Loading status checks…
256a60a
@sandersn
Builds w/protocol types + conversions
Loading status checks…
8ba5dc8
@sandersn
cleanup:better names and scrub TODOs
Loading status checks…
ca1b273
@sandersn
fix test harness too
Loading status checks…
867ab34
@sandersn
Misc
Loading status checks…
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
Loading status checks…
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
Loading status checks…
82c11fe
@sandersn
more tests and some fixes
Loading status checks…
90feb3e
@sandersn
Merge branch 'master' into editor-support-for-links
Loading status checks…
035bb4a
@sandersn
Fix other failing tests
Loading status checks…
fc813c2
@sandersn
Merge branch 'master' into editor-support-for-links
Loading status checks…
917314c
@sandersn
fix bad merge
Loading status checks…
7dd7cab
@sandersn
polish parser
Loading status checks…
c0e8d47
@sandersn
improve names and array types
Loading status checks…
8bbc8b4
@sandersn
slight tweaks
Loading status checks…
070da0b
@typescript-bot
Copy link
Collaborator

@typescript-bot typescript-bot commented Dec 8, 2020

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 sandersn requested a review from sheetalkamat Dec 8, 2020
@sandersn sandersn requested a review from andrewbranch Dec 8, 2020
@sandersn
Copy link
Member Author

@sandersn sandersn commented Dec 8, 2020 •
edited

@mjbvz and @amcasey, you should maybe also look at this (at least the protocol part)
@sandersn
remove some done TODOs
Loading status checks…
fce33f1
@andrewbranch
Copy link
Member

@andrewbranch andrewbranch commented Dec 8, 2020

@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 typescript-bot commented Dec 8, 2020 •
edited

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 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
more tests + resulting fixes
Loading status checks…
7ac40d4
@sandersn
Copy link
Member Author

@sandersn sandersn commented Mar 5, 2021 •
edited

One thing I noticed while experimenting with emacs -- the changes of services' JSDocTagInfo to use displayparts is an unconditional change for clients that don't pass simplifiedResult: true. This seems bad, so I have a commit ready to fix it once I confirm with @amcasey or @sheetalkamat.

It also points out that I don't have tests for the protocol part of the code. As far as I can tell, the unit tests with code like

assert.deepEqual(project.getLanguageService(/*ensureSynchronized*/ true).getQuickInfoAtPosition(file.path, indexOfX), {

Are just testing the language service on its own. I'm not sure how to test the server protocol.
@sandersn
Provide JSDocTagInfo.text: string to full clients by default
Loading status checks…
89e4955 
Instead of upgrading them to displayparts.
@minestarks
Copy link
Member

@minestarks minestarks commented Mar 5, 2021

@jessetrinity any chance you could validate this doesn't break anything in VS? I don't think we'll just get @link tag support for free, but at least JSDoc tags and other stuff should continue to work (in plain .js / .html / .cshtml)
@sandersn
Copy link
Member Author

@sandersn sandersn commented Mar 5, 2021

The most recent commit avoids breaking VS, and I'm working on tests for all 4 possible combinations of the rich/full matrix.
sandersn added 5 commits Mar 8, 2021
@sandersn
Real server tests
Loading status checks…
52d64db
@sandersn
Disambiguate {@link} and @param x {type}
Loading status checks…
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
Loading status checks…
3e5aa10
@sandersn
Merge branch 'master' into editor-support-for-links
Loading status checks…
618bcec
@sandersn
Copy link
Member Author

@sandersn sandersn commented Mar 10, 2021

This is ready for review now.
@sandersn sandersn moved this from Waiting on author to Needs review in PR Backlog Mar 10, 2021
@jessetrinity
jessetrinity reviewed Mar 10, 2021
View changes
src/server/protocol.ts Outdated Show resolved Hide resolved
sandersn added 2 commits Mar 10, 2021
@sandersn
fix location in richResponse in protocol
5a29c2e
@sandersn
update API baseline
Loading status checks…
67c4966
@amcasey
amcasey approved these changes Mar 15, 2021
View changes
Copy link
Member

@amcasey amcasey left a comment

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 added 3 commits Mar 16, 2021
@sandersn
Merge branch 'master' into editor-support-for-links
Loading status checks…
2da204a
@sandersn
Address PR comments
Loading status checks…
d0f3048 
1. Add a cross-file goto-def test.
2. Switch from per-message args to UserPreference.
@sandersn
use arraysEqual from core
Loading status checks…
4cfdaee
@sandersn
Copy link
Member Author

@sandersn sandersn commented Mar 16, 2021

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
10 checks passed
10 checks passed
build (10.x)
Details
CodeQL-Build CodeQL-Build
Details
CodeQL-Build CodeQL-Build
Details
build (12.x)
Details
build (14.x)
Details
CodeQL 1 analysis not found
Details
license/cla All CLA requirements met.
Details
node10 Build #98631 succeeded
Details
node12 Build #98629 succeeded
Details
node14 Build #98630 succeeded
Details
PR Backlog automation moved this from Needs merge to Done Mar 16, 2021
@sandersn sandersn deleted the editor-support-for-links branch Mar 16, 2021
@Kingwl
Copy link
Member

@Kingwl 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)"
Loading status checks…
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)
Verified
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: 4AEE18F83AFDEB23 Learn about signing commits
Loading status checks…
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)
Verified
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: 4AEE18F83AFDEB23 Learn about signing commits
Loading status checks…
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@DanielRosenwasser DanielRosenwasser

@amcasey amcasey

@minestarks minestarks

@jessetrinity jessetrinity

@andrewbranch andrewbranch

@sheetalkamat sheetalkamat

Assignees

@sandersn sandersn

Labels
Author: Team For Uncommitted Bug
Projects
PR Backlog
  
Done
Milestone
No milestone
Linked issues

Successfully merging this pull request may close these issues.

Editor support for @see and {@link} in JSDoc comments tags
9 participants
@sandersn @typescript-bot @andrewbranch @mjbvz @minestarks @Kingwl @DanielRosenwasser @amcasey @jessetrinity