Update typedoc to v0.22.15

[Gudahtt]

TypeDoc has been updated to the latest version. This version supports later TypeScript versions, allowing us to update tsc in a later PR. It also includes improvements to document generation, most importantly in the case where parameters are destructured.

Versions v0.21.0 and v0.22.0 both included breaking changes, but none of them affect us.

This new version included new console warnings that alerted me to a pre-existing problem that was introduced with v0.20.0, which is that many types are missing from our documentation. This is because TypeDoc will only include types that are exported from the package, and many of our internal types aren't exported from the package itself (even when they are exported from the module they're declared in). The plugin typedoc-plugin-missing-exports was added to address this. This plugin ensures that any types referenced in the docs are included in the docs, even if they aren't exported.

[mcmire]

many of our internal types aren't exported from the package itself (even when they are exported from the module they're declared in). The plugin typedoc-plugin-missing-exports was added to address this. This plugin ensures that any types referenced in the docs are included in the docs, even if they aren't exported.

Since we are talking about updating tsc, just to plan ahead, I think we should consider making use of the exports property in package.json, which would allow us to prohibit consumers from importing arbitrary submodules (import AccountTrackerController from '@metamask/controllers/dist/assets/AccountTrackerController', let's say) and only allow importing the main module. This is already supported under Node >= v12.17.x (see "History" in https://nodejs.org/api/packages.html#packages_exports) but unfortunately not supported in TypeScript just yet (although it is coming in 4.7: https://devblogs.microsoft.com/typescript/announcing-typescript-4-7-beta/#package-json-exports-imports-and-self-referencing). Once we added this, though, we would not have to worry about supplying documentation for types that are not exported from the main module, as those types would be inaccessible, and we could remove typedoc-plugin-missing-exports. Thoughts?

[Gudahtt]

Once we added this, though, we would not have to worry about supplying documentation for types that are not exported from the main module, as those types would be inaccessible, and we could remove typedoc-plugin-missing-exports.

Sorry I don't follow what you mean here. There is no worry about "supplying documentation for types that are not exported" - that's not what this plugin fixes. TypeDoc by default excludes any types that aren't exported.

The problem is the opposite of that. It's that we use types in method signatures that aren't exported, so by default TypeDoc doesn't produce very useful documentation for those methods. The plugin ensures any types referenced also get included in the docs. This is a feature, not a bug.

Are you suggesting that we should prevent these types from showing up in the documentation? How then would we ensure the documentation for our exported methods/fields/classes are comprehensive?

[mcmire]

Ah, I see. This plugin makes it so that if a function/whatever refers to a type and that type isn't being exported anywhere, then we should still include documentation about that type. That makes more sense.

I am slightly worried that if people see a type in the documentation, they will think it is public and rely on it. I do see that in most cases, internal types are put under an <internal> namespace and/or prefixed with <internal>. where they are referenced, so at least there is some kind of indication. I wish it were more obvious, but I don't have a solution for this, so this works for me.

Sorry for the confusion, this looks good to me.

[Gudahtt]

Hmm. The other option would be to actually export any type that was represented in the signature. I'm not sure this would be better though.

For example, in cases where we define a type to make maintenance easier (e.g. to share a set of parameters between related methods), exporting the type would increase the package surface area and prevent "breaking" changes to that type that we'd otherwise be able to make without changing the method it's used by.

I think this is a better solution for now. This lets us use types in places where it's convenient, without worrying about the impact of exposing those types.