typedoc: [regression] @link to built-in methods fails since 0.26.7

Search terms

Typescript 5.6 @link built-in types

Steps to reproduce the bug

/**
 * Returns a validator for the map's {@link Map.size|size}.
 *
 * @returns a validator for the map's {@link Map.size|size}
 * @throws TypeError if the value is `undefined` or `null`
 */

Returns this warning: [warning] Failed to resolve link to "Map.keys|keys" in comment for index.MapValidator.keys

Environment

  • Typedoc version: 0.26.7 (version 0.26.6 works fine)
  • TypeScript version: 5.6.2
  • Node.js version: 22.8.0
  • OS: Microsoft Windows [Version 10.0.19045.4780]

@Gerrit0 I’m guessing it’s related to your change in https://github.com/TypeStrong/typedoc/issues/2681

About this issue

  • Original URL
  • State: closed
  • Created 2 years ago
  • Comments: 22 (6 by maintainers)

Commits related to this issue

Most upvoted comments

I realized later that the plugin really ought to only return a link if there is a symbol ID (e.g. TS has resolved the link)

// typedoc --plugin ./plugin.js
/** @param {import("typedoc").Application} app */
export function load(app) {
  app.converter.addUnknownSymbolResolver((_decl, _refl, _part, symbolId) => symbolId ? "https://example.com" : undefined);
}

Well that’s really annoying… that’s a bug with externalSymbolLinkMappings. Easy fix at least…

My understanding was that if I export something in my entry point (re-export in my case) I would get it in my docs, much like how I get it when I create a d.ts file for the project.

This is correct, unless you also tell TypeDoc to exclude that type, in your case with both "excludeExternals": true and "excludeNotDocumented": true

So I need a pluging for one and configuration change for the other?

You could use the configuration for everything, but yes, I’d recommend the plugin for DT links as it’ll keep them up to date.

This is kind of the worst possible case for typedoc unfortunately… Ideally I think TypeDoc would provide an “externals” section that you can configure so it generates docs for specified dependencies that you can link to, but hides all the warnings related to them as they likely aren’t under your control… hmm… I need to think about this some more.

In my usecase, this is not actually a bug. I use TypeDoc only to run validation (as part of a larger linting process) on my project, where I ensure that everything is documented and links point to symbols.

In that case, 0.26.6’s behavior wasn’t quite right for you either, as if TypeScript failed to resolve a link, but TypeDoc was able to resolve it with declaration references, it would not report a broken link. TypeDoc doesn’t have a way to only use links resolved by TypeScript.

Did I understand correctly that in order to get this behaviour back in 0.26.7, I need to further configure externalSymbolLinkMappings TypeDoc config option, to e.g. just some dummy URLs or something similar?

Yes, it’s a fair assumption that providing links to each package will effectively give you back the behavior in 0.26.6.

Can I use * as export name in this mappings object?

You can! Apparently that wasn’t documented as it came after the initial feature, added docs with https://github.com/TypeStrong/typedoc-site/commit/057ee7a3e96627af4e21fc027f32c0eb40fbdb43

(Well, it ought to be. I haven’t gotten around to making that plugin handle symbol ID links, but that’s a bug with that plugin, not TypeDoc)