Open jan-molak opened 2 years ago
@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.
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
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.
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 🤔
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.@link
@apiLink
[[...]]
MyClass
MyClass
MyClass\|my descr
MyClass\|my descr
MyClass.method
MyClass.method
MyClass.method\|my descr
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!