docs: add typedoc-plugin-missing-exports#109
Conversation
- Added plugin to recover internally referenced but unexported types. - Set excludeExternals: true to filter out Node/language built-ins. - Successfully recovered ~60 Webpack-specific internal types.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
avivkeller
left a comment
avivkeller
left a comment
There was a problem hiding this comment.
I think we should find a new home for these types, rather than <internal>. Similarly to how #91 added a system for moving types to the subsystems that they are actually used in, can we do that here>
- Move internal types from the <internal> module to the project root. - Apply strict filtering to expose only important types and exclude noise.
| }); | ||
| } | ||
| }); | ||
|
|
There was a problem hiding this comment.
Is it possible to adjust createTypePages() to also check <internal>, that way we reduce the code duplication?
There was a problem hiding this comment.
when I searched for where I will write the code, I found that Converter.EVENT_RESOLVE_END is much safer and cleaner, I think of it as Early Garbage Collection, The plugin actually extracts over 600+ types (mostly internal dependencies/noise), but we only need about ~300 (increased from ~60 to ~300). By filtering and deleting the noise before the routing phase, we prevent TypeDoc from wasting memory, building URLs, or assigning them to groups and categories.
And using Separation of Concerns keep things clean. This early hook handles the AST extraction and cleanup, while createTypePages() remains strictly focused on routing.
WDUT?
| }); | ||
| } | ||
|
|
||
| noiseTypes.forEach(noise => project.removeReflection(noise)); |
There was a problem hiding this comment.
We can probably be smarter if we remove the types during collection, and don't put them in an array
| const internalModules = project.children?.filter( | ||
| c => c.name === '<internal>' | ||
| ); | ||
| if (internalModules) { |
There was a problem hiding this comment.
| const internalModules = project.children?.filter( | |
| c => c.name === '<internal>' | |
| ); | |
| if (internalModules) { | |
| const internalModule = project.children.find( | |
| c => c.name === '<internal>' | |
| ); |
| if (internalModule.children) { | ||
| internalModule.children.forEach(child => { | ||
| if (categoryForReflection(child)) { | ||
| importantTypes.push(child); | ||
| } else { | ||
| noiseTypes.push(child); | ||
| } | ||
| }); | ||
| } |
There was a problem hiding this comment.
Why wouldn't it have children? If it exists, we know it'll have children
|
|
||
| if (internalModule.children) { | ||
| internalModule.children.forEach(child => { | ||
| if (categoryForReflection(child)) { |
There was a problem hiding this comment.
| if (categoryForReflection(child)) { | |
| // TODO: We are calling `categoryForReflection` here, and then again when routing | |
| // We should cache the result to avoid re-looking up that data | |
| if (categoryForReflection(child)) { |
2 participants
What does this PR do?
Integrates
typedoc-plugin-missing-exportsto recover internally used types/interfaces that were not explicitly exported, resolving missing references in the docs.I tried three different settings to find the best result:
Experiment 1: Default Plugin Behavior (~135 types)
Running the plugin with default settings recovered about 135 missing types. However, they were isolated in an
<internal>module thattypedocdidn't go throw them (Shallow Pass).Experiment 2: Using
excludeExternals: true(~60 types) -> [Current PR State]I added this option to ignore basic JavaScript/Node types. The number dropped to about 60 Webpack types. They are grouped in an
<internal>folder. I chose this approach because it keeps the docs clean and simple.Experiment 3: Using
excludeExternals: true&placeInternalsInOwningModule: true(~630 types)I tried this option to put the types inside their original modules instead of the
<internal>folder. But this made the plugingo into chain, as after get them out it started seaching to the internally used types/interfaces that were not explicitly exported and put them inside their original modules and do it again to them...
While highly detailed, I felt the 630+ inline types would create too much noise for the average reader, so I reverted to Experiment 2.
Fixes #92