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

[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.

[Gerrit0]

TypeDoc already tries to convert direct-exports for all entry points first, followed by converting re-exports. It sounds like you found a case where this doesn't quite work right... If you can provide a minimal repro I can look at, this should hopefully be fixable.

typedoc/src/lib/converter/converter.ts

Lines 488 to 503 in 0bad04c

	entries.forEach((e) => {
	context.setActiveProgram(e.entryPoint.program);
	e.context = this.convertExports(
	context,
	e.entryPoint,
	createModuleReflections,
	);
	});
	for (const { entryPoint, context } of entries) {
	// active program is already set on context
	// if we don't have a context, then this entry point is being ignored
	if (context) {
	this.convertReExports(context, entryPoint.sourceFile);
	}
	}
	context.setActiveProgram(undefined);

TypeDoc doesn't bother to try to determine the "length" of the re-export chain in in the case of multiple entry points re-exporting the same symbol, which might be what you're seeing. If that's what you're running into, it's definitely falling closer to the "don't care" level. (Haven't watched the video, this might be what you're seeing, can't handle those at night)

[typhonrt]

Yeah.. it's export import in ambient namespaces which is likely not getting involved in this process.

[Gerrit0]

Yeah, that's not actually a re-export according to the compiler API. It introduces a new symbol. I might be able to handle it specially anyways...

[typhonrt]

This is definitely one of those fine tuning things to perhaps consider for TypeDoc.

My framework is moving into the larger size territory with over 1k symbols / ~90 sub-path exports and I'm going through and organizing most superfluous types into ambient namespaces for organizational purposes. This is the first occurrence of re-exporting between ambient namespaces. It significantly improves the DX for end devs using the framework particularly those using JSDoc / ESM for typing, so a useful pattern.

No rush on this. Just a fine tuning backlog type of thing.

[Gerrit0]

I'm not a huge fan of how much it changed the conversion order, but that wasn't very difficult to do...

[Gerrit0]

... and doing so actually badly breaks TypeDoc's site, where I was relying on this feature to get TypeDoc to place doubly exported classes in the expected namespace.

// I want the documentation to be inside this namespace
export * as Models from "./src/lib/models/index.js"
// Members are also exported here for backwards compatibility...
// because of how TS handles `export * from`, these symbols get noticed first.
export * from "./src/lib/models/index.js"