diff --git a/docs/rules/valid-types.md b/docs/rules/valid-types.md index 82c1b36a..57df7de0 100644 --- a/docs/rules/valid-types.md +++ b/docs/rules/valid-types.md @@ -884,5 +884,9 @@ function quux() { /** * @import { TestOne, TestTwo } from "./types" */ + +/** + * @returns {@link SomeType} + */ ```` diff --git a/src/rules/validTypes.js b/src/rules/validTypes.js index 7e3996e7..cf01f4df 100644 --- a/src/rules/validTypes.js +++ b/src/rules/validTypes.js @@ -291,6 +291,14 @@ export default iterateJsdoc(({ continue; } + // Documentation like `@returns {@link SomeType}` is technically ambiguous. Specifically it + // could either be intepreted as a type `"@link SomeType"` or a description `"{@link SomeType}"`. + // However this is a good heuristic. + if (tag.type.trim().startsWith('@')) { + tag.description = `{${tag.type}} ${tag.description}`; + tag.type = ''; + } + const mightHaveTypePosition = utils.tagMightHaveTypePosition(tag.tag, otherModeMaps); if (mightHaveTypePosition !== true && tag.type) { const modeInfo = mightHaveTypePosition === false ? '' : ` in "${mode}" mode`; diff --git a/test/rules/assertions/validTypes.js b/test/rules/assertions/validTypes.js index 19b83145..d52b13c2 100644 --- a/test/rules/assertions/validTypes.js +++ b/test/rules/assertions/validTypes.js @@ -1859,6 +1859,13 @@ export default /** @type {import('../index.js').TestCases} */ ({ * @import { TestOne, TestTwo } from "./types" */ `, + }, + { + code: ` + /** + * @returns {@link SomeType} + */ + `, } ], });