[api-documenter] Documentation for re-exports from external packages

[hiranya911]

This is similar to #663, but focuses on the documentation aspects for external re-exports. Suppose you have an entry point that re-exports members of an external package:

export { Foo, Bar } from 'some-external-package';

I'd want to generate some documentation for Foo and Bar, ideally pointing to the documentation of the external package. Is this something that can be supported?

One somewhat hacky and restricted solution I thought of was, declaring local type aliases to the external types:

import {
  Foo as TFoo,
  Bar as TBar,
} from 'some-external-package';

/**
 * Type alias to {@link https://external.link | Foo}.
 */
export type Foo = TFoo;

But this downgrades my exports to type, which has other implications.

[hiranya911]

As per the discussion at #1002, it seems a conscious decision has been made to keep external exports out of the generated docs:

Reexported items from external packages should be handled in user side, not the api-extractor core. It's a special case to merge some packages' contents.

However, the re-exports from external packages do not appear in the API json file either, making it difficult to implement even some custom tools to handle this use case. Would it be possible to include external package re-exports in the API json file?

[tylerbutler]

I'm interested in writing a PR to include the external exports in the API.json file. Is that something the maintainers would accept?

[octogonz]

As per the discussion at #1002, it seems a conscious decision has been made to keep external exports out of the generated docs

@hiranya911 The person you are quoting seems to have misunderstood what I said. If you look at my earlier comment in that thread, I was saying that reexports SHOULD appear in the .api.json file, but represented as a new kind of item (rather than as a copy of the imported structure):

In my view, this sort of thing:

export { ExternalModule } from 'external-package';

...is its own kind of API item that is similar to a TypeScript type alias. The API reference web site will already have a full set documentation for ExternalModule and all of its members in the section for external-package. It would seem counterproductive to duplicate all of this content in the section for this-package. Besides being confusing for the human audience, and it might negatively impact other systems such as search engine optimization (SEO).

[octogonz]

I'm interested in writing a PR to include the external exports in the API.json file. Is that something the maintainers would accept?

@tylerbutler Yes. There's a note about it in the code here:

rushstack/apps/api-extractor/src/generators/ApiModelGenerator.ts

Lines 123 to 125 in 3ade23f

	// TODO: Figure out how to represent reexported AstImport objects. Basically we need to introduce a new
	// ApiItem subclass for "export alias", similar to a type alias, but representing declarations of the
	// form "export { X } from 'external-package'". We can also use this to solve GitHub issue #950.

The first step is to design the .api.json representation. Feel free to propose something.

[octogonz]

BTW if you want to discuss design ideas, the #api-extractor channel is a good place. (However I am on vacation next week FYI.)