Using `@apilink` produces a warning from typedoc

I just found out some links dont work with the regular @link macro (namely those to inherited properties) but with @apilink it works fine. So wanted to switch all the links to use @apilink, but now the logs are flooded with warnings from typedoc about every single link that uses it. Would be great if we could somehow let typedoc know those are fine.

Example from the logs:

/Users/adamek/htdocs/apify/crawlee/packages/basic-crawler/src/internals/basic-crawler.ts:311:95 - warning Encountered an unknown inline tag "@apilink"

311         * A reference to the underlying {@apilink RequestQueue} class that manages the crawler's {@apilink Request|requests}.

/Users/adamek/htdocs/apify/crawlee/packages/basic-crawler/src/internals/basic-crawler.ts:317:38 - warning Encountered an unknown inline tag "@apilink"

317         * A reference to the underlying {@apilink SessionPool} class that manages the crawler's {@apilink Session|sessions}.

/Users/adamek/htdocs/apify/crawlee/packages/basic-crawler/src/internals/basic-crawler.ts:317:94 - warning Encountered an unknown inline tag "@apilink"

317         * A reference to the underlying {@apilink SessionPool} class that manages the crawler's {@apilink Session|sessions}.

/Users/adamek/htdocs/apify/crawlee/packages/basic-crawler/src/internals/basic-crawler.ts:323:38 - warning Encountered an unknown inline tag "@apilink"

323         * A reference to the underlying {@apilink AutoscaledPool} class that manages the concurrency of the crawler.

/Users/adamek/htdocs/apify/crawlee/packages/basic-crawler/src/internals/basic-crawler.ts:324:70 - warning Encountered an unknown inline tag "@apilink"

324         * > *NOTE:* This property is only initialized after calling the {@apilink BasicCrawler.run|`crawler.run()`} function.

/Users/adamek/htdocs/apify/crawlee/packages/basic-crawler/src/internals/basic-crawler.ts:326:40 - warning Encountered an unknown inline tag "@apilink"

326         * to pause the crawler by calling {@apilink AutoscaledPool.pause|`autoscaledPool.pause()`}

/Users/adamek/htdocs/apify/crawlee/packages/basic-crawler/src/internals/basic-crawler.ts:327:34 - warning Encountered an unknown inline tag "@apilink"

@B4nan - I found the same issue with @link in inherited properties, as well as with @link pointing to specific methods, e.g. {@link Class.method} doesn't seem to work.

So to work around it:

I replaced @link with @apiLink for inherited properties
I replaced @link with [[Class.method]] for links to methods

The above workaround does the trick for now, although it would be great if we could address the issue.

Could it be that in your case it doesn't work because of the lower case l? @apilink vs @apiLink?

I believe it should be @apilink, and it works fine for me with it, this issue is about typedoc warnings, not about things not working (they dont work with @link). {@apilink Class.method} works for me just fine, we have tons of such links.

edit: here is the site if you are interested in our setup: https://crawlee.dev/

@B4nan - nice website!

Yeah, you're right about @apilink, the regex is case insensitive, from what I see. (Makes me wonder where did I get that uppercase L from? 🤔 )

I summarised the issues I found with @link, @apilink and [[..]] in #66.

And yeah, I can confirm I'm seeing the warnings in my my output as well:

packages/web/src/screenplay/questions/Attribute.ts:59:26 - warning Encountered an unknown inline tag "@apilink"

Also, it looks like TypeDoc is also complaining about the deprecated [[..]] link style.

@B4nan @milesj - OK, so I did a bit of digging.

The warning about the unknown inline tag is caused by TypeDoc check here:

https://github.com/TypeStrong/typedoc/blob/7d71d354693cfbe26c911ac67d36dc79a25effd3/src/lib/converter/comments/parser.ts#L408-L410

Now, since docusaurus-plugin-typedoc-api lets us override TypeDoc configuration, we can expand the list of inline links known to TypeDoc in docusaurus.config.js:

    plugins: [
        [
            'docusaurus-plugin-typedoc-api',
            {
                typedocOptions: {
                    inlineTags: ['@link','@apilink']
                }
            },
        ],
    ]

This makes the warning go away since the inline tag is now recognised as known.

So this makes me wonder, should we provide a list of known tags (as per the regex) when bootstrapping TypeDoc here:

docusaurus-plugin-typedoc-api/packages/plugin/src/plugin/data.ts

Line 60 in 2063e3f

app.bootstrap({

inlineTags: [
 '@link',
 '@doclink',
 '@linkcode',
 '@linkplain',
 '@apilink'
]

I might actually just do it... ;-)