Uh oh!
There was an error while loading. Please reload this page.
Provide snippet completions for @param in JSDoc - #53260
Conversation
Nathan Shively-Sanders (sandersn)
left a comment
There was a problem hiding this comment.
Code looks good. Some questions about usage and whether related features will be needed.
Uh oh!
There was an error while loading. Please reload this page.
| // | * @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.
Uh oh!
There was an error while loading. Please reload this page.
| // | @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.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Gabriela Araujo Britto (@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 |
Gabriela Araujo Britto (gabritto)
commented
Apr 3, 2023
TypeScript Bot (@typescript-bot) test this |
Heya Gabriela Araujo Britto (@gabritto), I've started to run the extended test suite on this PR at 0e3ac3f. You can monitor the build here. |
Gabriela Araujo Britto (gabritto)
commented
Apr 3, 2023
TypeScript Bot (@typescript-bot) run DT |
Heya Gabriela Araujo Britto (@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 Gabriela Araujo Britto (@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 Gabriela Araujo Britto (@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 Gabriela Araujo Britto (@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 Gabriela Araujo Britto (@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 Gabriela Araujo Britto (@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! |
| 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
Uh oh!
There was an error while loading. Please reload this page.
TypeScript Bot (typescript-bot)
commented
Apr 3, 2023
Gabriela Araujo Britto (@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! |
TypeScript Bot (typescript-bot)
commented
Apr 3, 2023
Gabriela Araujo Britto (@gabritto) Here are the results of running the user test suite comparing Everything looks good! |
TypeScript Bot (typescript-bot)
commented
Apr 3, 2023
Gabriela Araujo Britto (@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: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
TypeScript Bot (typescript-bot)
commented
Apr 3, 2023
Hey Gabriela Araujo Britto (@gabritto), the results of running the DT tests are ready. |
TypeScript Bot (typescript-bot)
commented
Apr 3, 2023
Gabriela Araujo Britto (@gabritto) Here are the results of running the top-repos suite comparing Everything looks good! |
TypeScript Bot (typescript-bot)
commented
Apr 3, 2023
Gabriela Araujo Britto (@gabritto) Here are the results of running the top-repos suite comparing Everything looks good! |
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.