fix(valid-types): fix parsing of expressions like @returns {@link SomeType}; fixes #1381 (#1382)

Author: LukeAbby

docs/rules/valid-types.md

@@ -884,5 +884,9 @@ function quux() {
 /**
  * @import { TestOne, TestTwo } from "./types"
  */
+
+/**
+ * @returns {@link SomeType}
+ */
 ````
 

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`;

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}
+         */
+      `,
     }
   ],
 });