Provide snippet completions for @param in JSDoc #53260
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
typescript-bot
added
Author: Team
For Milestone Bug
sandersn
requested changes
Mar 15, 2023
tests/baselines/reference/jsdocParameterTagSnippetCompletion1.baseline
Outdated
Show resolved
Hide resolved
| // | * @param {Object} param0.a | ||
| // | * @param {*} param0.a.b | ||
| // | * @param {*} param0.a.c | ||
| // | * @param {*} param0.d |
There was a problem hiding this comment.
one thing you could do for array binding patterns: generate [*, *] for the type, plus two tabstops. But that seems like a lot of unnecessarily fancy work.
tests/baselines/reference/jsdocParameterTagSnippetCompletion1.baseline
Outdated
Show resolved
Hide resolved
| // | @version | ||
| // | @virtual | ||
| // | @yields | ||
| // | @param {*} b |
There was a problem hiding this comment.
couple of display questions:
- Do these longer completions sort below all the other tag names in a real editor? It might not be important if the prefix is
@paand there are only 3 anyway. - In editors that create a jsdoc template upon typing
/**, what opportunities are there to show this completion? Do we also need to improve that template with this feature?
There was a problem hiding this comment.
Re 1.
They have the same sortText as the keywords, so it's up to vscode to filter and sort them first or not based on matching. I think they show up later in the baselines because they are last in the array of completion entries. I thought using the same sortText would be ok, since (1) we're also returning all of the possible jsdoc tags, so we're not sure which one you want, and (2) vscode is going to filter that list as you type, so typing @p already reduces the list of entries to something that fits in the display without needing to scroll.
There was a problem hiding this comment.
Re 2, if we want we could change the jsdoc comment template completion to reuse this code for destructuring in JS (and in TS depending on what we decide to do).
There was a problem hiding this comment.
I vote to make 2 happen at some point; the new code is better than that the template currently has.
sandersn
approved these changes
Mar 16, 2023
|
@gabritto is this ready to go? I can't remember if we discovered more things that needed to be added at the last editor meeting. |
|
As pointed out by Matt, the whole jsdoc comment completion goes through a transformation on the vscode side: https://github.com/microsoft/vscode/blob/53df0204ca3e0472d582d3c6e4504e1aa39533bb/extensions/typescript-language-features/src/languageFeatures/jsDocCompletions.ts#L103 |
|
@typescript-bot test this |
|
@typescript-bot run DT |
|
Heya @gabritto, I've started to run the diff-based top-repos suite on this PR at 0e3ac3f. You can monitor the build here. Update: The results are in! |
|
Heya @gabritto, I've started to run the diff-based user code test suite (tsserver) on this PR at 0e3ac3f. You can monitor the build here. Update: The results are in! |
|
Heya @gabritto, I've started to run the diff-based user code test suite on this PR at 0e3ac3f. You can monitor the build here. Update: The results are in! |
|
Heya @gabritto, I've started to run the diff-based top-repos suite (tsserver) on this PR at 0e3ac3f. You can monitor the build here. Update: The results are in! |
|
Heya @gabritto, I've started to run the parallelized Definitely Typed test suite on this PR at 0e3ac3f. You can monitor the build here. Update: The results are in! |
|
Heya @gabritto, I've started to run the perf test suite on this PR at 0e3ac3f. You can monitor the build here. Update: The results are in! |
src/services/completions.ts
Outdated
|
|
||
| const isJs = isSourceFileJS(sourceFile); | ||
| const isSnippet = preferences.includeCompletionsWithSnippetText || undefined; | ||
| const paramTagCount = jsDoc.tags?.filter(tag => isJSDocParameterTag(tag) && tag.getEnd() <= position).length; |
There was a problem hiding this comment.
We have a countWhere utility
|
@gabritto Here are the results of running the user test suite comparing There were infrastructure failures potentially unrelated to your change:
Otherwise... Everything looks good! |
|
@gabritto Here are the results of running the user test suite comparing Everything looks good! |
|
@gabritto Here they are:
CompilerComparison Report - main..53260
System
Hosts
Scenarios
TSServerComparison Report - main..53260
System
Hosts
Scenarios
StartupComparison Report - main..53260
System
Hosts
Scenarios
Developer Information: |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Hey @gabritto, the results of running the DT tests are ready. |
|
@gabritto Here are the results of running the top-repos suite comparing Everything looks good! |
sandersn
approved these changes
Apr 3, 2023
|
@gabritto Here are the results of running the top-repos suite comparing Everything looks good! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes #52370.
Possibly relevant things to pay attention to:
Destructuring is handled one way in JS files, with the multiline syntax e.g.
@param {Object} param0 @param {*} param0.a, but in TS files for now we just don't offer those detailed@paramcompletions, because that same syntax (minus type annotations) doesn't work, as reported in Non-Nullable Objects in params don't have properties parsed #32783. When/if we merge feat(33367): support destructuring parameter @param tag in tsdoc #50951, we could use that syntax instead for TS files.The completion is a snippet, with a placeholder on the type annotation when one is present (and when it's not
Objectin a destructuring), and a tab stop on the place where the comment should go. Should the made-up parameter names for destructured parameters also be a placeholder?The implementation takes parameter initializers into consideration and includes them in the generated
@paramcompletion, but I currently have a rule that we don't include the initializer if its text is too long (> 80 characters), or if it spans across multiple lines.