microsoft / microsoft/TypeScript
Feature Request: Display JSDoc Array of Objects as Array
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 111k
- Forks
- 14.4k
- Avg merge
- 1d 19h
- Merged PRs (30d)
- 117
Description
Hey guys,
I tried searching for a similar issue, but couldn't find one. If there is another, I'm happy to close this one. Essentially, when specifying that a particular entity is an array of objects with a definite shape, I would like it if those were displayed as an actual array. Given the following Javascript:
/**
* @param {Object} params
* @param {Object[]} params.items - Array of items
* @param {string} params.items[].name - Name of the item
* @param {string} params.items[].value - Value of the item
*/
function myFunc({ items = []}){
items.map(item => {
console.log(item.name, item.value)
})
}
Currently, on hover, VSCode displays the type hinting as:
function myFunc({ items }: {
items: {
name: string;
value: string;
};
}): void
However, this makes it appear that items is an object. That is incorrect because items is instead an array of objects, and is specified as such in the JSDoc. I would expect something akin to when you specify the properties inline:
JS:
/**
* @param {Object} params
* @param {{name: string, data: string}[]} params.items - Array of items
*/
function myFunc({ items = []}){
items.map(item => {
console.log(item.name, item.value)
})
}
Hover:
function myFunc({ items }: {
items: {
name: string;
data: string;
}[];
}): void
The problem with using the inline format is the lack of an explanation of individual properties, and some object shapes can get very long, and even be nested. Additionally, the above solution waits until the end of the object definition to denote that the property should be an array. It seems that it would be more user-friendly if it was denoted as an array at the beginning, like this:
function myFunc({ items }: {
items: [{
name: string;
data: string;
}];
}): void
Thanks for your time and the great product!!
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
No implementation file or test is named. Reproduce the JSDoc example in VSCode and inspect the TypeScript language-service hover output, then trace how documented array properties are represented and displayed. Done means the documented Object[] property appears as an array of objects while preserving individual property descriptions, with coverage for the example behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, typescript, vscode
- Domain
- developer-experience, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100