rushstack icon indicating copy to clipboard operation
rushstack copied to clipboard

[api-extractor] Doc Model always trims internal and alpha methods

Open SBLMikeDemone opened this issue 7 months ago • 0 comments

Summary

I'm trying to get a doc model (.api.json) to report all APIs: internal, alpha, beta, and public. By specifying "releaseTagsToTrim": []" config option in the doc model I can get most internal APIs to show up EXCEPT methods on classes.

Repro steps

  1. Set up an extremely barebones project based on this template: https://api-extractor.com/pages/setup/invoking/
  2. Set up index.ts:
/**
 * @public
 */
export class PublicClass {
    /**
     * @internal
     */
    internalMethod() {
    }
}

/**
 * @internal
 */
export function internalFunction() {
}
  1. Set up api-extractor.json with the default template and replace docModel with:
"docModel": {
    "enabled": true,
    "releaseTagsToTrim": []
}
  1. Run the api-extractor with api-extractor run --local
  2. Observe the generated doc model (temp/awesome-widgets.api.json)

Expected result: The doc model reports the existence of PublicClass.internalMethod and internalFunction.

Actual result: The doc model does not report the existence of PublicClass.internalMethod but it does report the existence of internalFunction.

Details

Diving into the code, it looks like there's a hardcoded if statement for methods that breaks early for internal and alpha and doesn't report them. See here: https://github.com/microsoft/rushstack/blob/main/apps/api-extractor/src/generators/ApiModelGenerator.ts#L770-L772

      if (releaseTag === ReleaseTag.Internal || releaseTag === ReleaseTag.Alpha) {
        return; // trim out items marked as "@internal" or "@alpha"
      }

I believe the solution is to just delete that if check because the check of the api tag against releaseTagsToTrim in _processDeclaration should cover this case.

Standard questions

Please answer these questions to help us investigate your issue more quickly:

Question Answer
@microsoft/api-extractor version? 7.52.8
Operating system? Windows
API Extractor scenario? docs (.api.json)
Would you consider contributing a PR? Yes
TypeScript compiler version? 5.8.2
Node.js version (node -v)? 22.14.0

SBLMikeDemone avatar Jun 20 '25 22:06 SBLMikeDemone