Skip to content

Feature / Observation: Order matters in files processed regarding reflection generation for ambient namespace re-exports. #2856

Closed
@typhonrt

Description

@typhonrt

Search Terms

Re-exported symbols / reflections processed out of order causing incorrect associations in generated API Docs.

Problem

This is just an observation regarding the TypeDoc reflection generation processing. I have a larger framework that I generate API docs for from many bundled declaration files. When re-exporting symbols across these declaration files order matters in regard to where TypeDoc first processes a reference to reflection. If the re-exported declaration file is processed first then TypeDoc will make that the source of the reflections even though they are re-exports. If the actual source / declaration file of the real originating symbol is processed first then the correct re-export reflections are generated by TypeDoc.

I already have a custom build process for the API docs of my framework, so I was able to dig in and figure out a way to re-order the declaration files being processed by TypeDoc to correctly generate the re-exported reflections.

Perhaps there is an opportunity for fine tuning with TypeDoc in how re-exports are handled in the reflection generation process.

Overview video / example of how I analyzed / worked around this issue:
https://www.youtube.com/watch?v=yWI8l-_zqHA

Suggested Solution

Deferred reflection generation that isn't impacted by logical order of files being processed by TypeDoc. IE when a source / declaration file is clearly a re-export make sure to process the original source / reflections first if it is included in the entry points being processed.

Is it worth it? Not sure. There is a workaround by manually ordering the files being processed by TypeDoc, but it's non-obvious.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions