Inconsistent behaviour of `@link`, `@apiLink` and `[[...]]`

[jan-molak]

Hey @milesj!

It seems like @link, @apiLink and [[...]] have a slightly inconsistent behaviour, so I thought I'd summarise it here.

In short, using @link with descriptions works fine when linking to classes in other modules of my monorepo, but fails when used to link to classes in the same module.

scenario	example	@link	@apiLink	[[...]]
Direct link to a class in the same module	MyClass	✅	✅	✅
Direct link to a class in a different module	MyClass	✅	✅	✅
Link to a class in the same module with description	MyClass\|my descr	🚫 - renders "descr", no "my", no link	✅	🚫
Link to a class in a different module with description	MyClass\|my descr	✅	✅	🚫
Link to a method of a class in the same module	MyClass.method	🚫 - renders "method", no link	✅	✅
Link to a method of a class in another module	MyClass.method	✅	✅	✅
Link to a method of a class in the same module, with description	MyClass.method\|my descr	🚫 - renders "descr", no link	✅	🚫
Link to a method of a class in another same module, with description	MyClass.method\|my descr	✅	✅	🚫

Would you say it's fair to conclude that using @apiLink is preferable over @link? Or am I missing something?

Also, would you expect {@apiLink MyClass} to work when used in Docusaurus docs? Or should a regular markdown link be used instead?

Thanks!

[milesj]

@jan-molak Both @link and @apilink use the exact same code: https://github.com/milesj/docusaurus-plugin-typedoc-api/blob/master/packages/plugin/src/utils/markdown.ts#L41 So unless TypeDoc is transforming the comments in someway, I'm surprised they're not consistent.

With that said, TypeDoc resolves entities in a much different way than this plugin does, as they have full context into the parsed data, while this plugin only has access to the raw JSON files. Because of this, we added @apilink to differentiate.

[jan-molak]

Both @link and @apilink use the exact same code:

Yeah, I noticed that. This makes me think that since TypeDoc also supports @link, perhaps it "gets to it first"? 🤔

I think that once #67 is released I'll just standardise on using @apilink

[B4nan]

I believe typedoc produces different shape for @link, i was opening another (now resolved) issue about that. Iirc they are different in the json def.

[kamranayub]

I just ran into this as I was trying to do this:

import { Actor } from "../Actor";

/**
  * An example {@link Actor | `actors`} link
  */

And it only outputted the plain actors text, it didn't link to it. The nice thing about this of course is that TypeDoc will validate these links.

If I switch it to @apilink, I don't need the import and it does work, but I don't love that it's not consistent.

FWIW the JSON output of the original looks like this:

{
  "kind": "inline-tag",
  "tag": "@link",
  "text": "`actors`",
  "target": 2828, // Actor class
  "tsLinkText": "`actors`"
},

It's too bad the plugin can't just use that for the comments to render since that has all the info 🤔