TypeDoc @link attribute

[matteobruni]

Search terms

link

Question

I had a lot of [[links]] in my comments, and since 0.24.0 is dropping the support to that, I tried migrating to {@link value} syntax without success. This issue happens in 0.23.x and 0.24.0-beta.3

Like this:

https://github.com/matteobruni/tsparticles/blob/075bfbcead80a456312f893152be6acf625a81c3/engine/src/Core/Loader.ts#L31

/**
 * Main class for creating the {@link Container} objects
 * @category Core
 */

The Container linked is a class imported and existing in the same folder

https://github.com/matteobruni/tsparticles/blob/075bfbcead80a456312f893152be6acf625a81c3/engine/src/Core/Loader.ts#L2
https://github.com/matteobruni/tsparticles/blob/v2/engine/src/Core/Container.ts

But when I build the docs I got errors like this:

[warning] Failed to resolve link to "Container" in comment for tsParticles Engine.Core/Loader.Loader.
[warning] Failed to resolve link to "Container" in comment for tsParticles Engine.Core/Loader.Loader.load.
[warning] Failed to resolve link to "Container" in comment for tsParticles Engine.Core/Loader.Loader.load.options.
[warning] Failed to resolve link to "Container" in comment for tsParticles Engine.Core/Loader.Loader.loadJSON.
[warning] Failed to resolve link to "Container" in comment for tsParticles Engine.Core/Loader.Loader.set.
[warning] Failed to resolve link to "Container" in comment for tsParticles Engine.Core/Loader.Loader.set.options.
[warning] Failed to resolve link to "Container" in comment for tsParticles Engine.Core/Loader.Loader.setJSON.

But I don't understand what's wrong with my link.

Other links tried without success:

{@link Container:class}
{@link Container:type}

[Gerrit0]

This is because [[Container]], if all else failed, was resolved by searching for an arbitrary declaration named Container and linking to that, which works fine, as long as there's only one Container in your exports. 0.23 removed the global declaration search, so your link would have to be {@link Core/Container!Container}. TypeDoc doesn't care what you have imported, because it's meant to be able to run on your built source, or later on the declaration files, and imports may be erased there, so can't be relied upon.

I'm looking at changing this behavior in 0.24 (tracking issue is #2141) so that if TypeScript resolves a @link, we use that symbol target, but haven't done that yet.

[matteobruni]

This is because [[Container]], if all else failed, was resolved by searching for an arbitrary declaration named Container and linking to that, which works fine, as long as there's only one Container in your exports. 0.23 removed the global declaration search, so your link would have to be {@link Core/Container!Container}. TypeDoc doesn't care what you have imported, because it's meant to be able to run on your built source, or later on the declaration files, and imports may be erased there, so can't be relied upon.

I'm looking at changing this behavior in 0.24 (tracking issue is #2141) so that if TypeScript resolves a @link, we use that symbol target, but haven't done that yet.

The {@link Core/Container!Container} solved partially. I can't reference Container` outside the library like here

I've checked the TSDoc reference about the @link attribute but there's no mention of the ! operator, even in the TypeDoc website. In the TSDoc they use # instead of !. Are they different or it's a missing feature?

[Gerrit0]

The TSDoc website isn't really complete. https://tsdoc.org/pages/spec/overview/ references the "new" spec, which is what TypeDoc implements (partially, because nobody wants to fully qualify every link), the relevant bit is here

I'd honestly recommend just using {@link Container}, and skipping 0.24 entirely. In 0.24. --useTsLinkResolution is on by default, and then TypeDoc will use the link that TypeScript sees, which will be correct since that is imported.

[Gerrit0]

v0.24.0 has been released, which should resolve your issues