Typedoc: [Library Beta] TypeScript DOM lib types used in `Omit<>` aren't linked

[MasterKale]

Search terms

lib.dom.d.ts interfaces

Expected Behavior

DOM lib interfaces used in an Omit<> should be included in doc output and clickable to jump down to that section of the page.

Actual Behavior

Doc output does not include the base DOM lib interface I'm extending via an Omit<>:

export interface PublicKeyCredentialCreationOptionsJSON
  extends Omit<PublicKeyCredentialCreationOptions, 'challenge' | 'user' | 'excludeCredentials'> {
  // ...
}

TypeDoc handles basic extends just fine, though:

export interface AssertionCredential extends PublicKeyCredential {
  // ...
}

Both PublicKeyCredentialCreationOptions and PublicKeyCredential are declared in TypeScript's lib.dom.d.ts

Steps to reproduce the bug

I've created a minimal reproduction repo here: https://github.com/MasterKale/typedoc-bug-repro-1386

Environment

• Typedoc version: 0.20.0-beta.4
• TypeScript version: 3.9.7
• Node.js version: v14.9.0
• OS: macOS 10.15.7

[Gerrit0]

I spent a bit of time looking into this, and unfortunately making it work properly is going to be rather tricky... The way TypeDoc currently handles inheritance is... horrible. This will be first on my list for next week, but I doubt I'll get it this week.

[Gerrit0]

Well, a couple hours in... and this is a systematic problem. TypeDoc's converters work according to nodes, which is fine, until you start using more complicated types. Pick/Omit is bad enough. It's going to get worse with TS 4.1's key remapping features... I think to fix this I need to rework the converters to ask the type checker what properties a given symbol has, and work on that.

[Gerrit0]

v0.20.0-beta.9 fixes this :)

[MasterKale]

@Gerrit0 That's great progress! 🤩

Now, what would it take to get things like AttestationConveyancePreference and AuthenticatorSelectionCriteria in that screenshot clickable so that you can see what _those_ values are? Is that something devs like me would need to change about our code to get TypeDoc to include them in our docs? Ideally it'd be possible to click down until you get to the primitive types of the values that actually need to be specified without having to open up the TypeScript DOM lib separately.

[Gerrit0]

TypeDoc 0.20 documents items based on what you export, so you'd have to export those interfaces. Unfortunately... TS doesn't like that.

Error: C:/Users/gtbir/Desktop/library-tests/src/gh1386.ts(7)
 Cannot export 'PublicKeyCredentialCreationOptions'. Only local declarations can be exported from a module.

I don't have a good way around this yet. I'd really like to link dom values to MDN, @types/node values to the node docs... etc. But every single library has their own docs site, own link style... and those might change, which makes maintenance next to impossible. @bennypowers has a script that does this for MDN, but it's horribly hacky...

I think it should be possible to define a plugin which handles creating these links in a reasonable manner, with codegen that makes updates mostly automatic... but that's a project unto itself. It would make TypeDoc a much better tool though... Can't commit to looking into that right now. Maybe during end of year shutdown?