Support JS Doc In Trailing Trivia

Suggestion

🔍 Search Terms

JS Doc, JSDoc, Leading, Trailing, Comments, Link

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

JS Doc only seems to be parsed in leading comments, not in trailing comments.
However, sometimes putting multiple statements into one line can change a leading comment of one statement into a trailing comment of the statement before.

I suggest to check trailing comments for JS doc as well.

📃 Motivating Example

JS Doc references should be parsed everywhere, not just for trailing comments.

Currently, this function declaration:

const f2 = () => {
	/** @type string */
	let x;
	return x;
};

... and this function declaration:

const f1 = () => { /** @type string */ let x; return x; };

... have different types (() => string vs () => undefined), even though their only difference is formatting.

With this suggestion, they would both have the type () => string.

💻 Use Cases

I would assume that all these links work:

const x = () => /** {@link x} */ 1;
const y = () => { /** {@link y} */ return 1; };
const z = () => {
	/** {@link z} */
	return 1;
};

However, just the link to z works.
If this worked, @link could be used anywhere to (consistently) link to other elements in the source code.
This would enable interesting use-cases (e.g. for debugging), as JS allows to read a function body by using .toString() on a function value.

Reproduce the contrasting multiline and same-line examples, along with the three @link cases, to observe how leading and trailing comments are treated. Trace the compiler's JSDoc handling from those examples and add coverage showing that equivalent trailing trivia receives the same type and link behavior; done means all examples are handled consistently.