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

[bradennapier]

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

What TypeDoc Generates

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

What TypeDoc Generates

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]

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

[Gerrit0]

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.

[bradennapier]

I believe the @link concept is providing by TS, is it not? That was my understanding @Gerrit0 -- vscode resolves markdown style links previously but the @link I had thought waited for them. I could be wrong but I was involved in some early conversations on the concept in vscode and they decided to wait for symbol rresolutions for ts to provide it.

Can def imagine its a whole can of worms to collaborate all these things together though!

[Gerrit0]

I believe the @link concept is providing by TS, is it not?

How VSCode resolves links, yes. However, @link pre-dates TS. JSDoc introduced it AFAIK, then TypeDoc added support when it was first created, then a few years later, TypeScript added support with different semantics...

[pokey]

I'm strongly in support of having an option where we let the TypeScript compiler resolve links. In the meantime, would it be easy to support an option that just uses the old resolution behaviour from 0.22.x? A bunch of our links broke when we upgraded to 0.23.x

[Gerrit0]

would it be easy to support an option that just uses the old resolution behaviour from 0.22.x?

If a link fails to resolve with the new behavior in 0.23, it should fall back to 0.22's resolution. This is going to be removed in 0.24 as I don't want to continue maintaining the incredibly inefficient algorithm it uses.

In 0.24, I intend to try to use TypeScript's resolution of @link if it has been resolved, and use the declaration references specified by TSDoc otherwise -- in other words, write what VSCode will resolve, and TypeDoc should do the same thing.

[pokey]

Huh ok interesting. I'll try to see if I can figure out why our links are breaking 🤔.

Re 0.24 behaviour, that sounds awesome