[api-extractor] Question: is it possible to generate documentation for augmented ambient types?

[jrnail23]

Just a question... I'm building a package of custom commands for Cypress, which generally extend a global variable (i.e., if I create a command called doSomething, you'd use it by calling cy.doSomething(), where cy is their built-in global variable).

In order to make them work with Typescript, you augment the existing Cypress interfaces by adding the appropriately typed method (relevant docs). Here's an example:

declare namespace Cypress {
  interface Chainable {
    /**
     * Custom command to select DOM element by data-cy attribute.
     * @example cy.dataCy('greeting')
    */
    dataCy(value: string): Chainable<Element>
  }
}

I'd like to figure out how to generate documentation from the typescript definitions, which, as you can see are generally ambient declarations, rather than exported types. Also, they may not generally be accessible via a single entry point.

Is it currently possible to generate docs for these types using api-extractor/api-documenter? If not, does anyone have any ideas for a clever workaround?

[octogonz]

Today, API Extractor doesn't support:

• ambient types (aka "global variables"). Issue [api-extractor] support ambient types #1176 discusses possible options, but there's historically not been too much interest, since global variables are not a great way to design an API.

• augmented types. Issue [api-extractor] improve the .d.ts rollup to handle augmented types #1709 is working on a solution for supporting that for ordinary exports.

Until both these problems are solved, I don't think we could consider implementing support for augmented ambient types.

I feel like the way to work around it would be to design a conventional API, and run API Extractor on that. Then have a entry point that converts it into a global variable. Take a look at @types/react for an example.