`{@link Class.name}` resolves wrongly to `Function.name`

[Danielku15]

🔎 Search Terms

JSDoc, TSDoc, Link, Resolve, Name

🕗 Version & Regression Information

• This is the behavior in every version I tried, and I reviewed the FAQ for entries

⏯ Playground Link

https://www.typescriptlang.org/play/?ts=5.8.0-dev.20250215#code/MYGwhgzhAEAqCmEAu0DeBYAUNH0D0AVAVrjgdABLwggD2JpBeDOAdmALbwBcyATgEtWAc2gBeaACIEySVgC+WLIWLZyqAAIghAaziIkAOnZdFa5pgBmAV1bAkA2q2hgAFEm4ykASjQtofPBI1nzORibwANwKQA

💻 Code

class Test {
    /**
     * Hello
     */
    name:string = "Test"
}

/**
 * {@link Test.name}
 */
function a(t:Test) {
    return t.name;
}

🙁 Actual behavior

The Test.name reference in the JSDoc/TSDoc resolves to the symbol Function.name. This is not correct because the Test class has an own property declaration for name.

In my real world usecase am generating markdowns from my typescript code via TypeScript compiler API and I get the wrong symbol using typeChecker.getSymbolAtLocation(tsDocLinkNode.name) leading to wrong documentation links.

🙂 Expected behavior

The correct documentation of my name property should be shown.

The typeChecker should resolve this expression to the correct symbol to allow tooling to resolve these cross references and link to the respective documentation page.

Additional information about the issue

No response

[RyanCavanaugh]

The correct syntax to refer to that is Test#name, see https://jsdoc.app/tags-inline-link

[Danielku15]

The hash notation is not working in TypeScript. The dot notation instead, seem to work fine, TypeScript just resolves .name wrong. Do I miss something here?

https://www.typescriptlang.org/play/?ts=5.8.0-dev.20250215#code/MYGwhgzhAEAqCmEAu0DeBYAUNH0D0AVAVrjgdABLwggD2JpBeDOAdmALbwBcyATgEtWAc2gBeaACIEySVgC+WLIWLZyqAAIghAaziIkAYnZdFa6CXKWLa5pgBmAV1bAkA2q2hgAFEm4ykAEo0Fmg+eCRHPk8kADoTeABuBSA

It seems the TSDoc spec has this point still in discussion.
https://tsdoc.org/pages/tags/link/
microsoft/tsdoc#9

[RyanCavanaugh]

When I ctrl-click on Test#name it takes me to name; what do you mean by "not working" more specifically?

[Danielku15]

Now as you say it, something seems off. Generally I was triggered by the following behaviors that something is broken:

1. In VS Code: there are no hyperlinks in the rendered docs when using the # notation. While for . notation there are visual links to click. But they do not exist in the TS Playground at all. But also on stackblitz I get the same experience reducing the chance its a special extension triggering this behavior:

https://stackblitz.com/edit/vitejs-vite-7bzn4y19?file=src%2Ftest.ts&terminal=dev

I moved to the dot notation in my docs to provide a better developer experience when devs use my library.

2. The TypeScript TypeChecker (Compiler API) fails to resolve the symbol on a full ts.JSDocLink.name when using the Hash Notation. It appears to work when resolving the specific subnode though.

(side-by-side comparison of the different notations and the behavior)

I could extend my code to use # notation and handle the resolving differently in my Code. But I'd lose the nice Links in the preview window.

---

From a low level AST behavior:

1. For Hash-Notation ts.JSDocLink.name will contain a ts.JSDocMemberName node. If you resolve ts.JSDocLink.name you get no symbol. If you resolve ts.JSDocLink.name.right it resolves to the correct Track.name member.
2. For Dot-Notation ts.JSDocLink.name will contain a ts.QualifiedName node. If you resolve ts.JSDocLink.name you get a "wrong" symbol pointing to Function.name if you have a .name, but it works for other members as expected.

While JSDoc seem to promote # notation, TypeScript provides also support for . Notation but the QualifiedName resolves (IMO) wrongly for Class.name. (initial bug report).

---

I currently have this (ugly/hacky) workaround in place when using the Compiler API

if (comment.name.getText().endsWith(".name")) {
  // resolve parent
  if (ts.isQualifiedName(comment.name)) {
    symbol = context.checker.getSymbolAtLocation(
      comment.name.left
    );
  } else if (ts.isJSDocMemberName(comment.name)) {
    symbol = context.checker.getSymbolAtLocation(
      comment.name.left
    );
  }

  symbol = symbol?.members?.get(
    ts.escapeLeadingUnderscores("name")
  );
} else {
  symbol = context.checker.getSymbolAtLocation(comment.name);
}

---

Edit: I perpared a stackblitz reproduction to look at the situation (execute with npm run test). There we can see the discrepancy isolated.

https://stackblitz.com/edit/vitejs-vite-pnhqv3jq?file=compiler.ts