Resolution failure

[HarelM]

Search terms

Failed to resolve, comment, link to

Expected Behavior

No warning or errors when running typedoc

Actual Behavior

I'm getting the following warnings:
[warning] Failed to resolve link to "PointLike" in comment for SetupMarkerOptions.offset
[warning] Failed to resolve link to "Marker#setLngLat" in comment for SetupMarkerOptions.anchor

Steps to reproduce the bug

I'm not sure I'll be able to create a minimal reproduction, but the following is what I currently have:
In the following repo (and commit) run:
npm ci
npm run build
npm run build:showcase
npm run docs

it should fail with the above warnings.
When I looked at the offending interface I was not able to understand what went wrong:
SetupMarkerOptions extends MarkerOptions which in turn has an offset: PointLike field, but PointLike is imported in this file, so it should be fine, shouldn't it?

Environment

• Typedoc version: 0.28.5
• TypeScript version: 5.8.3
• Node.js version: 20.19.2
• OS: MacOS, but also saw it on Linux.

Here's there relevant failing CI:
https://github.com/maplibre/ngx-maplibre-gl/actions/runs/15689019069/job/44199359734

Let me know what other info you might need.

As a workaround I've added @private above this interface to avoid this warning, but it felt like a patch...

[HarelM]

Forgot to thank you again for this truly awesome library! I use it wherever I can and try to spread the word.

[Gerrit0]

That error message is somewhat confusing, TypeDoc actually figures out where the link should go correctly, but because that item isn't included in your generated site, the link is rendered broken by not having a destination.

The error messaging for this could be much better without much work, I've made a small change to more accurately describe what went wrong

[HarelM]

Thanks! I've read the warning in the commit (which is very helpful!), but I'm still unable to solve one of the warnings.
I've added the following mapping in my typedoc.json:

"externalSymbolLinkMappings": {
        "maplibre-gl": {
            "PointLike": "https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/PointLike/",
            "Marker": "https://maplibre.org/maplibre-gl-js/docs/API/classes/Marker/",
            "Marker#setLngLat": "https://maplibre.org/maplibre-gl-js/docs/API/classes/Marker/#setlnglat"
        }
    }

But I'm still getting the following warning:

Failed to resolve link to "Marker#setLngLat" in comment for SetupMarkerOptions.anchor

I know I can add a "*", but I'd like to link to the relevant page in the docs when possible.

Also I'm not sure why I'm not getting other warnings.
For example, SetupMarkerOptions extends MarkerOptions, MarkerOptions is an external type that is part of maplibre-gl and not part of ngx-maplibre-gl.
If I add the wildcard ("*") then the generated docs would know that it can be linked and marks the link to the wildcard address:

But if I remove the "*" in the externalSymbolLinkMappings then I don't get a warning for this link, but there's also no link in the generated docs.

If I add a specific mapping in externalSymbolLinkMappings - i.e. "MarkerOptions": "https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MarkerOptions/", it links to the right place, so it seems that typedoc knows how to resolve this, but is not notifying me that I'm missing some links.

Let me know if you would like me to open a different issue for the things I mentioned above.

If there's anything I can test out, or help do let me know.

[Gerrit0]

You want Marker.setLngLat, not Marker#setLngLat in externalSymbolLinkMappings -- that option does not support #.

Also I'm not sure why I'm not getting other warnings.

This is working as intended - the export validation explicitly disables warning about heritage clauses (extends and implements) as (at least a few years ago... I haven't written much JS/TS lately) it was not uncommon to define base classes/interfaces which aren't intended as part of the public API/shouldn't be included in the docs.

Examples:

• TypeDoc's Application
• Babylon's Viewport
• Vue's Transition (not exactly "normal" inheritance, but the same idea)
• Web components which inherit from HTMLElement, HTMLDivElement, etc.

In all of these cases, it isn't important to the API user how it was implemented, so when implementing the warnings several years ago I decided the noise likely wasn't worth the stricter validation checks... I'd be open to a PR which adds an additional validation option alongside notExported to also check heritage clauses, it'd be easy to implement, essentially being the notExported version with one boolean flag swapped.

[HarelM]

I'll work on that to avoid inheritance for types as I don't think it's truely needed.

Yeah, I can understand the decision around reducing noise...

Should I be using "class.method" instead of "class#method" in the tsfics as well?

[Gerrit0]

Within doc comments # is supported, you can use either