diff --git a/tools/api-markdown-documenter/CHANGELOG.md b/tools/api-markdown-documenter/CHANGELOG.md index adcb1946b04c..1c926086d39d 100644 --- a/tools/api-markdown-documenter/CHANGELOG.md +++ b/tools/api-markdown-documenter/CHANGELOG.md @@ -59,6 +59,10 @@ await MarkdownRenderer.renderApiModel({ - `RenderHtmlConfig` -> `RenderHtmlConfiguration` - `ToHtmlConfig` -> `ToHtmlConfiguration` +#### Utility function renames + +- `ApiItemUtilities.getQualifiedApiItemName` -> `ApiItemUtilities.getFileSafeNameForApiItem` + #### Configuration properties made `readonly` - `ApiItemTransformations` diff --git a/tools/api-markdown-documenter/api-report/api-markdown-documenter.alpha.api.md b/tools/api-markdown-documenter/api-report/api-markdown-documenter.alpha.api.md index 21d920080618..048d96b1e324 100644 --- a/tools/api-markdown-documenter/api-report/api-markdown-documenter.alpha.api.md +++ b/tools/api-markdown-documenter/api-report/api-markdown-documenter.alpha.api.md @@ -116,9 +116,9 @@ declare namespace ApiItemUtilities { getDefaultValueBlock, getDeprecatedBlock, getExampleBlocks, + getFileSafeNameForApiItem, getModifiers, getModifierTags, - getQualifiedApiItemName, getReleaseTag, getReturnsBlock, getSeeBlocks, @@ -395,6 +395,9 @@ function getDeprecatedBlock(apiItem: ApiItem): DocSection | undefined; // @public function getExampleBlocks(apiItem: ApiItem): readonly DocSection[] | undefined; +// @public +function getFileSafeNameForApiItem(apiItem: ApiItem): string; + // @public function getHeadingForApiItem(apiItem: ApiItem, config: ApiItemTransformationConfiguration, headingLevel?: number): Heading; @@ -407,9 +410,6 @@ function getModifiers(apiItem: ApiItem, modifiersToOmit?: ApiModifier[]): ApiMod // @public function getModifierTags(apiItem: ApiItem): ReadonlySet; -// @public -function getQualifiedApiItemName(apiItem: ApiItem): string; - // @public function getReleaseTag(apiItem: ApiItem): ReleaseTag | undefined; diff --git a/tools/api-markdown-documenter/api-report/api-markdown-documenter.beta.api.md b/tools/api-markdown-documenter/api-report/api-markdown-documenter.beta.api.md index 2629c5c8f5a3..d7c3c4006493 100644 --- a/tools/api-markdown-documenter/api-report/api-markdown-documenter.beta.api.md +++ b/tools/api-markdown-documenter/api-report/api-markdown-documenter.beta.api.md @@ -116,9 +116,9 @@ declare namespace ApiItemUtilities { getDefaultValueBlock, getDeprecatedBlock, getExampleBlocks, + getFileSafeNameForApiItem, getModifiers, getModifierTags, - getQualifiedApiItemName, getReleaseTag, getReturnsBlock, getSeeBlocks, @@ -395,6 +395,9 @@ function getDeprecatedBlock(apiItem: ApiItem): DocSection | undefined; // @public function getExampleBlocks(apiItem: ApiItem): readonly DocSection[] | undefined; +// @public +function getFileSafeNameForApiItem(apiItem: ApiItem): string; + // @public function getHeadingForApiItem(apiItem: ApiItem, config: ApiItemTransformationConfiguration, headingLevel?: number): Heading; @@ -407,9 +410,6 @@ function getModifiers(apiItem: ApiItem, modifiersToOmit?: ApiModifier[]): ApiMod // @public function getModifierTags(apiItem: ApiItem): ReadonlySet; -// @public -function getQualifiedApiItemName(apiItem: ApiItem): string; - // @public function getReleaseTag(apiItem: ApiItem): ReleaseTag | undefined; diff --git a/tools/api-markdown-documenter/api-report/api-markdown-documenter.public.api.md b/tools/api-markdown-documenter/api-report/api-markdown-documenter.public.api.md index f5212f9e5f60..cb0b02f27518 100644 --- a/tools/api-markdown-documenter/api-report/api-markdown-documenter.public.api.md +++ b/tools/api-markdown-documenter/api-report/api-markdown-documenter.public.api.md @@ -116,9 +116,9 @@ declare namespace ApiItemUtilities { getDefaultValueBlock, getDeprecatedBlock, getExampleBlocks, + getFileSafeNameForApiItem, getModifiers, getModifierTags, - getQualifiedApiItemName, getReleaseTag, getReturnsBlock, getSeeBlocks, @@ -395,6 +395,9 @@ function getDeprecatedBlock(apiItem: ApiItem): DocSection | undefined; // @public function getExampleBlocks(apiItem: ApiItem): readonly DocSection[] | undefined; +// @public +function getFileSafeNameForApiItem(apiItem: ApiItem): string; + // @public function getHeadingForApiItem(apiItem: ApiItem, config: ApiItemTransformationConfiguration, headingLevel?: number): Heading; @@ -407,9 +410,6 @@ function getModifiers(apiItem: ApiItem, modifiersToOmit?: ApiModifier[]): ApiMod // @public function getModifierTags(apiItem: ApiItem): ReadonlySet; -// @public -function getQualifiedApiItemName(apiItem: ApiItem): string; - // @public function getReleaseTag(apiItem: ApiItem): ReleaseTag | undefined; diff --git a/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts b/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts index a4ac8099e913..49882c369c86 100644 --- a/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts +++ b/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts @@ -20,9 +20,9 @@ export { getDefaultValueBlock, getDeprecatedBlock, getExampleBlocks, + getFileSafeNameForApiItem, getModifiers, getModifierTags, - getQualifiedApiItemName, getReleaseTag, getReturnsBlock, getSeeBlocks, diff --git a/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts b/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts index 2e5fcd2c619f..97ddf511fe70 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts @@ -10,7 +10,7 @@ import { type ApiItem, ApiItemKind, ReleaseTag } from "@microsoft/api-extractor- import type { Heading } from "../Heading.js"; import type { Link } from "../Link.js"; import { - getQualifiedApiItemName, + getFileSafeNameForApiItem, getReleaseTag, getApiItemKind, type ValidApiItemKind, @@ -280,7 +280,7 @@ function getHeadingIdForApiItem( // Generate ID information for everything back to that point let hierarchyItem = apiItem; while (!doesItemRequireOwnDocument(hierarchyItem, config.documentBoundaries)) { - const qualifiedName = getQualifiedApiItemName(hierarchyItem); + const qualifiedName = getFileSafeNameForApiItem(hierarchyItem); // Since we're walking up the tree, we'll build the string from the end for simplicity baseName = baseName === undefined ? qualifiedName : `${qualifiedName}-${baseName}`; diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuite.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuite.ts index bf44a274eafb..b0982296cbc2 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuite.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuite.ts @@ -13,14 +13,14 @@ import { import { type ApiMemberKind, - getQualifiedApiItemName, - getUnscopedPackageName, - getSafeFilenameForName, + getApiItemKind, getConciseSignature, + getFileSafeNameForApiItem, + getFileSafeNameForApiItemName, + getReleaseTag, getSingleLineExcerptText, + getUnscopedPackageName, isDeprecated, - getReleaseTag, - getApiItemKind, } from "../../utilities/index.js"; /** @@ -286,10 +286,10 @@ export namespace DefaultDocumentationSuiteOptions { return "index"; } case ApiItemKind.Package: { - return getSafeFilenameForName(getUnscopedPackageName(apiItem as ApiPackage)); + return getFileSafeNameForApiItemName(getUnscopedPackageName(apiItem as ApiPackage)); } default: { - return getQualifiedApiItemName(apiItem); + return getFileSafeNameForApiItem(apiItem); } } } diff --git a/tools/api-markdown-documenter/src/api-item-transforms/helpers/Helpers.ts b/tools/api-markdown-documenter/src/api-item-transforms/helpers/Helpers.ts index f4b51bf02661..bbc9b513012d 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/helpers/Helpers.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/helpers/Helpers.ts @@ -49,7 +49,7 @@ import { import { type ApiFunctionLike, injectSeparator, - getQualifiedApiItemName, + getFileSafeNameForApiItem, getSeeBlocks, getThrowsBlocks, getDeprecatedBlock, @@ -101,7 +101,7 @@ export function createSignatureSection( return wrapInSection(contents, { title: "Signature", - id: `${getQualifiedApiItemName(apiItem)}-signature`, + id: `${getFileSafeNameForApiItem(apiItem)}-signature`, }); } } @@ -138,7 +138,7 @@ export function createSeeAlsoSection( return wrapInSection(contents, { title: "See Also", - id: `${getQualifiedApiItemName(apiItem)}-see-also`, + id: `${getFileSafeNameForApiItem(apiItem)}-see-also`, }); } @@ -489,7 +489,7 @@ export function createRemarksSection( tsdocNodeTransformOptions, ), ], - { title: "Remarks", id: `${getQualifiedApiItemName(apiItem)}-remarks` }, + { title: "Remarks", id: `${getFileSafeNameForApiItem(apiItem)}-remarks` }, ); } @@ -525,7 +525,7 @@ export function createThrowsSection( return wrapInSection(paragraphs, { title: headingText, - id: `${getQualifiedApiItemName(apiItem)}-throws`, + id: `${getFileSafeNameForApiItem(apiItem)}-throws`, }); } @@ -609,7 +609,7 @@ export function createExamplesSection( return wrapInSection(exampleSections, { title: headingText, - id: `${getQualifiedApiItemName(apiItem)}-examples`, + id: `${getFileSafeNameForApiItem(apiItem)}-examples`, }); } @@ -727,7 +727,7 @@ function createExampleSection( exampleParagraph = stripTitleFromParagraph(exampleParagraph, exampleTitle, logger); } - const headingId = `${getQualifiedApiItemName(example.apiItem)}-example${ + const headingId = `${getFileSafeNameForApiItem(example.apiItem)}-example${ example.exampleNumber ?? "" }`; @@ -885,7 +885,7 @@ export function createParametersSection( [createParametersSummaryTable(apiFunctionLike.parameters, apiFunctionLike, config)], { title: "Parameters", - id: `${getQualifiedApiItemName(apiFunctionLike)}-parameters`, + id: `${getFileSafeNameForApiItem(apiFunctionLike)}-parameters`, }, ); } @@ -944,7 +944,7 @@ export function createReturnsSection( ? undefined : wrapInSection(children, { title: "Returns", - id: `${getQualifiedApiItemName(apiItem)}-returns`, + id: `${getFileSafeNameForApiItem(apiItem)}-returns`, }); } diff --git a/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts b/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts index c1b24fbe3135..cbd6fac3d847 100644 --- a/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts +++ b/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts @@ -166,15 +166,11 @@ export function getFilteredParent(apiItem: ApiItem): ApiItem | undefined { } /** - * Adjusts the name of the item as needed. - * Accounts for method overloads by adding a suffix such as "myMethod_2". - * - * @param apiItem - The API item for which the qualified name is being queried. - * - * @public + * Gets a qualified representation of the API item's display name, accounting for function/method overloads + * by adding a suffix (such as "myMethod_2") as needed to guarantee uniqueness. */ -export function getQualifiedApiItemName(apiItem: ApiItem): string { - let qualifiedName: string = getSafeFilenameForName(apiItem.displayName); +function getQualifiedDisplayName(apiItem: ApiItem): string { + let qualifiedName: string = apiItem.displayName; if (ApiParameterListMixin.isBaseClassOf(apiItem) && apiItem.overloadIndex > 1) { // Subtract one for compatibility with earlier releases of API Documenter. // (This will get revamped when we fix GitHub issue #1308) @@ -183,6 +179,40 @@ export function getQualifiedApiItemName(apiItem: ApiItem): string { return qualifiedName; } +/** + * Gets a filename-safe representation of the provided API item name. + * + * @remarks + * - Handles invalid filename characters. + */ +export function getFileSafeNameForApiItemName(apiItemName: string): string { + // eslint-disable-next-line unicorn/better-regex, no-useless-escape + const badFilenameCharsRegExp: RegExp = /[^a-z0-9_\-\.]/gi; + + // Note: This can introduce naming collisions. + // TODO: once the following issue has been resolved in api-extractor, we may be able to clean this up: + // https://github.com/microsoft/rushstack/issues/1308 + return apiItemName.replace(badFilenameCharsRegExp, "_").toLowerCase(); +} + +/** + * Gets a filename-safe representation of the API item's display name. + * + * @remarks + * - Handles invalid filename characters. + * + * - Qualifies the API item's name, accounting for function/method overloads by adding a suffix (such as "myMethod_2") + * as needed to guarantee uniqueness. + * + * @param apiItem - The API item for which the qualified name is being queried. + * + * @public + */ +export function getFileSafeNameForApiItem(apiItem: ApiItem): string { + const qualifiedDisplayName = getQualifiedDisplayName(apiItem); + return getFileSafeNameForApiItemName(qualifiedDisplayName); +} + /** * Gets the unscoped version of the provided package's name. * @@ -550,19 +580,6 @@ export function getConciseSignature(apiItem: ApiItem): string { return apiItem.displayName; } -/** - * Converts bad filename characters to underscores. - */ -export function getSafeFilenameForName(apiItemName: string): string { - // eslint-disable-next-line unicorn/better-regex, no-useless-escape - const badFilenameCharsRegExp: RegExp = /[^a-z0-9_\-\.]/gi; - - // Note: This can introduce naming collisions. - // TODO: once the following issue has been resolved in api-extractor, we may be able to clean this up: - // https://github.com/microsoft/rushstack/issues/1308 - return apiItemName.replace(badFilenameCharsRegExp, "_").toLowerCase(); -} - /** * Extracts the text from the provided excerpt and adjusts it to be on a single line. *