Skip to content

chore(docs): normalize Storage_2 in generated API doc model - #3312

Open
lahirumaramba wants to merge 1 commit into
mainfrom
lm-storage-docgen
Open

lahirumaramba wants to merge 1 commit into
mainfrom
lm-storage-docgen

Conversation

@lahirumaramba

Copy link
Copy Markdown
Member

Newer @types/node releases declare a global Web Storage interface, which collides with the Storage class exported by firebase-admin/storage. To avoid the global name clash, API Extractor renames our class to Storage_2 in the generated .api.json doc model, causing api-documenter to publish a Storage_2 class page and drop inline {@link Storage} links in getStorage().

This change normalizes Storage_2 back to Storage during .api.json post-processing before api-documenter runs, restoring the clean Storage class name, page filename, and cross-links without altering the API Extractor .api.md reports.

Technical Details

  • Renames stripHiddenDocsFromApiJson in generate-reports.js to postProcessApiJson and its inner walker to visitNode so it covers both @excludeFromDocs member filtering and symbol normalization.
  • Rewrites Storage_2 node names and !Storage_2 canonical references across members and excerptTokens in generated temp/*.api.json files.
  • Moves @microsoft/api-extractor loading into generateReportForEntryPoint so it is only required when generating reports.

Newer Node.js type definitions declare a global Web Storage interface, causing API Extractor to rename our exported Storage class to Storage_2 in the generated doc model. That rename leaks Storage_2 into published reference page URLs, headings, and table-of-contents entries, and breaks inline {@link Storage} links.

Normalize Storage_2 back to Storage when post-processing the generated .api.json files so API Documenter emits clean Storage class pages and working links.
@lahirumaramba
lahirumaramba requested a review from a team November 10, 2026 22:22

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates generate-reports.js to post-process the generated API JSON report by renaming stripHiddenDocsFromApiJson to postProcessApiJson and adding logic to normalize global name collisions (specifically renaming Storage_2 back to Storage in node.name and node.canonicalReference). The feedback suggests also normalizing node.text when it is 'Storage_2' to ensure that the rendered TypeScript signatures in the documentation (which rely on excerptTokens' text property) do not display Storage_2.

Comment thread generate-reports.js Resolved

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant