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

[cowwoc]

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 #2681

[Gerrit0]

TypeDoc should have been warning about this forever, but wasn't due to a bug in the validation.

Map isn't included in your documentation, so your documentation will not include a link to Map.size. If you use typedoc-plugin-mdn-links then that link would be resolved to a page on MDN, and would not produce this warning.

(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)

[cowwoc]

@Gerrit0 Hmm, either I'm configuring this wrong or the plugin does not work.

I added:

"typedoc-plugin-mdn-links": "^3.2.12"

into packages.json and "typedoc-plugin-mdn-links" into typedoc.json section plugin but I am getting the same warning messages. Any ideas?

[Gerrit0]

(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)

[HarelM]

Sorry to report on a closed issue, but I think there's still an issue here.
I have the following dependabot PR that fails to update from version 0.26.6 to 0.26.7:

• Bump typedoc from 0.26.6 to 0.26.7 maplibre/maplibre-gl-js#4678

I've looked at the failure and it looks like the warnings are not accurate.
The following are the warnings that you can see in the CI run (I'm treating warnings as errors):

[warning] Failed to resolve link to "ErrorEvent" in comment for Map.addControl
[warning] Failed to resolve link to "ErrorEvent" in comment for Map.removeControl
[warning] Failed to resolve link to "ErrorEvent" in comment for Map.setMinZoom
[warning] Failed to resolve link to "ErrorEvent" in comment for Map.setMaxZoom
[warning] Failed to resolve link to "ErrorEvent" in comment for Map.setMinPitch
[warning] Failed to resolve link to "ErrorEvent" in comment for Map.setMaxPitch
[warning] Failed to resolve link to "ErrorEvent" in comment for Map.isSourceLoaded
[warning] Failed to resolve link to "ErrorEvent" in comment for Map.addImage
[warning] Failed to resolve link to "ErrorEvent" in comment for Map.updateImage
[warning] Failed to resolve link to "ErrorEvent" in comment for Map.hasImage
[warning] Failed to resolve link to "ErrorEvent" in comment for Map.removeLayer
[warning] Failed to resolve link to "ProjectionSpecification" in comment for Map.getProjection
[warning] Failed to resolve link to "ProjectionSpecification" in comment for Map.setProjection
[warning] Failed to resolve link to "ErrorEvent" in comment for Style.removeLayer
[warning] Failed to resolve link to "LayerSpecification" in comment for AddLayerObject
[warning] Failed to resolve link to "SourceSpecification" in comment for AddLayerObject
[warning] Failed to resolve link to "Point" in comment for Offset
[warning] Failed to resolve link to "WorkerSource" in comment for Dispatcher
[warning] Found 0 errors and [18](https://github.com/maplibre/maplibre-gl-js/actions/runs/11149550021/job/30988676767?pr=4678#step:9:19) warnings

Let's assume that ErrorEvent is not exported and thus causing this warning, which is an easy fix I can do on my end.
So I'm left with the following warnings:

[warning] Failed to resolve link to "ProjectionSpecification" in comment for Map.getProjection
[warning] Failed to resolve link to "ProjectionSpecification" in comment for Map.setProjection
[warning] Failed to resolve link to "LayerSpecification" in comment for AddLayerObject
[warning] Failed to resolve link to "SourceSpecification" in comment for AddLayerObject
[warning] Failed to resolve link to "Point" in comment for Offset
[warning] Failed to resolve link to "WorkerSource" in comment for Dispatcher

Specifications are exported as part of the following "*" export here:
https://github.com/maplibre/maplibre-gl-js/blob/01e57c77ad6b211bbb0570cedc3b502f2b1b8e91/src/index.ts#L52

Point is exported here:
https://github.com/maplibre/maplibre-gl-js/blob/01e57c77ad6b211bbb0570cedc3b502f2b1b8e91/src/index.ts#L189

WorkerSource is imported especially in order to be available in the comment, here:
https://github.com/maplibre/maplibre-gl-js/blob/01e57c77ad6b211bbb0570cedc3b502f2b1b8e91/src/util/dispatcher.ts#L6

Please let me know if I'm doing something wrong here...

[stazz]

I can confirm that there is some kind of regression happened in 0.26.7. I've got a bunch of Failed to resolve link -errors when running 0.26.7/5.6.2 combination of Typedoc/TypeScript, respectively. I suspected the errors being false positives, since VSCode could resolve links just fine. The errors seemed to happen only for link targets residing in node_modules.

I then changed versions to 0.26.6/5.5.4, and did nothing else at all. After that, the Failed to resolve link -errors from Typedoc were gone.

FWIW, the 0.26.7/5.5.4 combination again started to produce false positive Failed to resolve link -errors.

[Gerrit0]

Versions before 0.26.7 had a bug where if a link was resolved to a symbol by TypeScript, TypeDoc would not report it as a broken link, even if it could not be resolved when producing output. So far, in every case I have investigated, the problem is that the referenced member is not included in the documentation, not that something is wrong with 0.26.7.

[warning] Failed to resolve link to "ProjectionSpecification" in comment for Map.getProjection
[warning] Failed to resolve link to "ProjectionSpecification" in comment for Map.setProjection
[warning] Failed to resolve link to "LayerSpecification" in comment for AddLayerObject
[warning] Failed to resolve link to "SourceSpecification" in comment for AddLayerObject

This is expected. These symbols are defined in node_modules/@maplibre/maplibre-gl-style-spec, and is not included in the documentation.

[warning] Failed to resolve link to "Point" in comment for Offset

This is expected. Point is defined in node_modules/@types/mapbox__point-geometry, and is not included in the documentation.

[warning] Failed to resolve link to "WorkerSource" in comment for Dispatcher

This is expected, it isn't exported from src/util/evented

---

I spent most of today building https://github.com/Gerrit0/typedoc-plugin-dt-links which can automatically take those @link tags and point your documentation to the source code on the DefinitelyTyped GitHub repo. TypeDoc's externalSymbolLinkMappings option could also be used to define mappings to a documentation site if @types/mapbox__point-geometry has better docs somewhere.

[HarelM]

Thanks for taking the time to look at this!

This is expected. These symbols are defined in node_modules/@maplibre/maplibre-gl-style-spec, and is not included in the documentation.

I'm not sure I understand this statement. 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.
I now understand this is not "out-of-the-box", but I'm not clear as to how to solve it.
Point definition is in DefinitelyTyped while spec objects have a d.ts inside the npm package.
So I need a pluging for one and configuration change for the other?

[stazz]

Versions before 0.26.7 had a bug where if a link was resolved to a symbol by TypeScript, TypeDoc would not report it as a broken link, even if it could not be resolved when producing output.

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.

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? Can I use * as export name in this mappings object?

[Gerrit0]

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 TypeStrong/typedoc-site@057ee7a

[stazz]

@Gerrit0 Thank you for the advice, highly appreciated! However, I am struggling a bit with how I am to make this work with 0.26.7.
Given I have this source code:

import * as random from "@pulumi/random";

/**
 * Blah blah {@link random.RandomPassword}.
 */
function someFunction() {}

And this typedoc.config.mjs:

/** @type {Partial<import('typedoc').TypeDocOptions>} */
const config = {
  ...,
  externalSymbolLinkMappings: {
    "@pulumi/random": {
      "*": "https://example.com"
    }
  },
};

export default config;

I am still getting the Failed to resolve link -errors (they are errors, as my config also has treatWarningsAsErrors: true,).

In VSCode all seems normal:

Any idea what is going on? 🤔