Repository navigation
chore(docs): normalize Storage_2 in generated API doc model - #3312
Open
lahirumaramba wants to merge 1 commit into
Open
lahirumaramba wants to merge 1 commit into
lahirumaramba wants to merge 1 commit into
Conversation
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.
Contributor
There was a problem hiding this comment.
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.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Newer
@types/nodereleases declare a global WebStorageinterface, which collides with theStorageclass exported byfirebase-admin/storage. To avoid the global name clash, API Extractor renames our class toStorage_2in the generated.api.jsondoc model, causingapi-documenterto publish aStorage_2class page and drop inline{@link Storage}links ingetStorage().This change normalizes
Storage_2back toStorageduring.api.jsonpost-processing beforeapi-documenterruns, restoring the cleanStorageclass name, page filename, and cross-links without altering the API Extractor.api.mdreports.Technical Details
stripHiddenDocsFromApiJsoningenerate-reports.jstopostProcessApiJsonand its inner walker tovisitNodeso it covers both@excludeFromDocsmember filtering and symbol normalization.Storage_2node names and!Storage_2canonical references acrossmembersandexcerptTokensin generatedtemp/*.api.jsonfiles.@microsoft/api-extractorloading intogenerateReportForEntryPointso it is only required when generating reports.