[v0.28.8] global.md is referenced in places it shouldn't

[HarelM]

Expected Behavior

functions should belong to their respective class...?

Actual Behavior

A lot of methods are now part of global.md

Steps to reproduce the bug

1. Clone maplibre/maplibre-gl-js
2. run npm i && npm run generate-docs
3. Check the docs/API/functions folder for "off.md" and others - they shouldn't be there.

Environment

• Typedoc version: 0.28.8
• TypeScript version: 5.8.3
• Node.js version: 22.13
• OS: macOS

I saw this issue as part of our dependabot package update.
The current docs can be found here, which are using version 0.28.7:
https://maplibre.org/maplibre-gl-js/docs/API/functions/addProtocol/
When building locally with latest version (0.28.8) I see a difference in what is being written in global.md file, which I believe is not correct, as most of the methods there are not really global and belong to a class (evented.ts in this case of off and on).

Let me know if there's any more information I can provide.
Here's the relevant PR that raised my attention to this change:

• chore(deps-dev): bump typedoc from 0.28.7 to 0.28.8 maplibre/maplibre-gl-js#6188

[Gerrit0]

If you turn off the not exported plugin, does this still happen? I suspect a bug in that plugin.

[HarelM]

Yes, I believe so, but if I remove the plugin I get like 69 warnings about types not included in the documentation.
I'm not sure anymore why I added it originally, I think it was to make the export of the index file simpler and avoid exporting stuff that "should" be exported because they are part of an exported class or method. Should I strive to avoid using it? It is considered bad practice to use it?

[Gerrit0]

I really need to put this in a FAQ at some point... There is #1657, which I've basically given up arguing with people in and just ignore new posts in now.

IMO, yes. It is bad practice to not export types which are potentially useful to downstream users. Grabbing a random one of your warnings:

[warning] NavigationControlOptions, defined in maplibre-gl/src/ui/control/navigation_control.ts, is referenced by NavigationControl.constructor.options but not included in the documentation

If I want to use your library, and have some function which is supposed to return the necessary arguments to construct a NavigationControl, what am I supposed to do?

function buildNavControlOptions(): ??? {
  return { ... };
}

If the type was exported, I could annotate the type of the function to both prevent mistakes where I include extra properties by accident. Doing so will also allow intellisense to give me useful autocomplete help. Because the type isn't exported, I either have to leave it unannotated and rely on errors when later passing the result into your class (not great, loses freshness checks and errors don't show up when I'm working on that function, just when I look at where it is used) or extract the type from your class: buildNavControlOptions(): ConstructorParameters<typeof NavigationControl>[0], which is ugly, and doesn't work if NavigationControl was generic or had an overloaded constructor.

Some of your types (Listener) are harder to argue with this about, as I don't really see a world in which a user would want to annotate a variable with that type, but if it was a less-any-filled type (e.g. if Evented was generic over the types of events that will show up), I could see it happening.

[HarelM]

I see your point, I think dts-bundle-generator exports the relevant referenced types using a flag as can be see here:
https://github.com/maplibre/maplibre-gl-js/blob/cc4dfc25d57d6cec656673dbb3c9d276d5144d26/package.json#L139

I do remember something about using its output as an input to this tool to "simplify" some of the stuff, I don't remember why I didn't follow up on that... Maybe that can solve some future problems.
There is a merit to including this plugin as part of this library (it doesn't have to be the default behavior, but can be a flag) as this is a common requirement, simply from an ease-of-use perspective, to remove the need to go over all the warnings and fix then manually, i.e. tell the tool to do it but instead of a plugin have this as a first class citizen (which, if I needed to guess, would have reduce the probability of this reported bug, although I might be wrong as I don't fully know the root cause of this bug).
I appreciate your point of view and your hard work on this amazing tool, feel free to ignore any of my inputs as I fully respect and value your opinion.