microsoft / microsoft/TypeScript
@description JSDoc tag interferes with callback parameter documentation
@orta is already working on this.
Since Sep 2, 2020.
- Dominant language
- Go
- Stars
- 111k
- Forks
- 14.3k
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 132
Description
TypeScript Version: 3.8.3
Search Terms: jsdoc param
Expected behavior:
Below code creates no errors, type of x is recognized as (value: number) => boolean
Actual behavior:
Type of x is () => boolean, the invocation creates a type error.
Removing the @description tag makes the code work as expected.
My interpretation of https://jsdoc.app/tags-description.html is that you should be able to place @description anywhere in the comment without interfering with other tags:
By using the @description tag, you can place the description anywhere in the JSDoc comment.
Related Issues: Ran into a crash #37265 while trying to repro this with template parameters.
Code
// @ts-check
/**
* @callback IterablePredicate
* @description return true if given element of iterable matches an internal condition
* @param {number} value the current item being evaluated
* @returns {boolean} true if the entry satisfies given condition
**/
/**
* @type {IterablePredicate}
*/
let x;
x(3) // Expected 0 arguments, but got 1.
Compiler Options
{
"compilerOptions": {
"noImplicitAny": true,
"strictFunctionTypes": true,
"strictPropertyInitialization": true,
"strictBindCallApply": true,
"noImplicitThis": true,
"noImplicitReturns": true,
"alwaysStrict": true,
"esModuleInterop": true,
"checkJs": true,
"allowJs": true,
"declaration": true,
"experimentalDecorators": true,
"emitDecoratorMetadata": true,
"moduleResolution": 2,
"target": "ES2017",
"jsx": "React",
"module": "ESNext"
}
}
Playground Link: Provided
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.
Assessment
This issue has not been assessed yet.