@link is Disconnected from VSCode - Makes @link near-impossible to use effectively

This issue has been tracked since 2023-01-12.

Search terms

  • @link
  • link
  • cross-file links

Expected Behavior

Provide a way to give users a good experience via linking both when using the package in IDE vs scanning the TypeDoc.

Actual Behavior

I want to provide links to types that make sense to use for various types. I want this to improve developer experience both for TypeDoc and when using the package itself via VSCode's inline documentation. We should be able to use them together without importing everything directly.

HOWEVER, this is impossible:

  1. In TypeDoc you CAN NOT use an imported variable which is in scope to link {@link enums.OrderTypes}
  2. In VSCode you MUST use an imported variable which is in scope to link {@link enums.OrderTypes}

So TypeDoc would REQUIRE {@link OrderTypes} and it will try to find things directly instead of realizing I imported enums and I am referring to the OrderTypes on the enums import.

Using {@link enums.OrderTypes}

import type * as enums from '../enums';

export interface Random {
  /**
   * @see enum {@link enums.OrderTypes}
   * @see type {@link enums.OrderType}
   */
  type: enums.OrderType;
}

When Using VSCode Documentation

image

What TypeDoc Generates

image

Using {@link OrderTypes}

import type * as enums from '../enums';

export interface Random {
  /**
   * @see enum {@link OrderTypes}
   * @see type {@link OrderType}
   */
  type: enums.OrderType;
}

When Using VSCode Documentation

image

What TypeDoc Generates

image

What is notable here is that it obviously understands this kind of linking... because I am using enums.OrderType for the type itself and typedoc links to it flawlessly in that situation.

Steps to reproduce the bug

  • Import a module as namespace
  • Try to link to it so both VSCode and TypeDoc work
    • importing direct without the import type * also doesn't work but that shouldn't matter regardless
    • Direct import instead of namespace importing not really acceptable when you have thousands of links and many of them are not used in that specific file anywhere but are being linked for developer convenience

Environment

  • Typedoc version: "typedoc": "^0.23.24",
  • TypeScript version:"typescript": "4.9.4"
  • Node.js version: 18
  • OS: 13.1
bradennapier wrote this answer on 2023-01-27

We can also see that a typescript team member seems to confirm this is a bug with TypeDoc microsoft/TypeScript#16498 (comment)

Gerrit0 wrote this answer on 2023-02-04

Welcome to the horrible world that is trying to build software that has conflicting requirements from several groups of people and trying to make one group happy breaks another. Something I've wanted to try for a while is see if links can be resolved by TS, and if not fall back to TypeDoc's current implementation, but have been busy recently, so haven't done anything on typedoc.

It's worth mentioning that "works in vscode" is also not good enough, because what works in your .ts files may no longer work once the comment is copied into a .d.ts file during compilation... so it might work for you, but not for your library's consumers. I suspect this is part of why the tsdoc team went with global resolution.

More Details About Repo
Owner Name TypeStrong
Repo Name typedoc
Full Name TypeStrong/typedoc
Language TypeScript
Created Date 2014-05-24
Updated Date 2023-03-19
Star Count 6487
Watcher Count 68
Fork Count 639
Issue Count 48

YOU MAY BE INTERESTED

Issue Title Created Date Updated Date