From db9d9f11e79a01d6072b9b0ec4c4e6e3b5cb0133 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Mon, 16 Dec 2024 23:05:53 +0000 Subject: [PATCH 01/54] WIP --- .../DocumentationSuiteOptions.ts | 190 ++++++++---------- 1 file changed, 89 insertions(+), 101 deletions(-) diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts index 31afad786110..c1eb76817675 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts @@ -23,70 +23,105 @@ import { } from "../../utilities/index.js"; /** - * List of item kinds for which separate documents should be generated. - * Items specified will be rendered to their own documents. - * Items not specified will be rendered into their parent's contents. - * - * @remarks Note that `Model` and `Package` items will *always* have separate documents generated for them, even if - * not specified. - * - * Also note that `EntryPoint` items will always be ignored by the system, even if specified here. - * - * @example - * - * A configuration like the following: - * - * ```typescript - * ... - * documentBoundaries: [ - * ApiItemKind.Namespace, - * ], - * ... - * ``` - * - * will result in separate documents being generated for `Namespace` items, but will not for other item kinds - * (`Classes`, `Interfaces`, etc.). + * Kind of documentation suite hierarchy. * * @public */ -export type DocumentBoundaries = ApiMemberKind[]; +export enum HierarchyKind { + /** + * The API item gets a section under the document representing an ancestor of the API item. + */ + Section = "Section", + + /** + * The API item gets its own document, in the folder for an ancestor of the API item. + */ + Document = "Document", + + /** + * The API item gets its own document, and generates folder hierarchy for all descendent API items. + */ + Folder = "Folder", +} /** - * List of item kinds for which sub-directories will be generated, and under which child item documents will be created. - * If not specified for an item kind, any children of items of that kind will be generated adjacent to the parent. - * - * @remarks Note that `Package` items will *always* have separate documents generated for them, even if - * not specified. - * - * @example + * {@link TODO} base interface. + */ +export interface HierarchyConfigBase { + /** + * {@inheritDoc HierarchyKind} + */ + readonly kind: THierarchyKind; +} + +/** + * {@link HierarchyKind.Section} hierarchy configuration options. * - * A configuration like the following: + * @public + */ +export interface SectionHierarchyOptions { + /** + * Heading text to use for the API item. + */ + readonly headingText?: string | ((apiItem: ApiItem) => string); +} + +/** + * The corresponding API item will be placed in a section under the document representing an ancestor of the API item. * - * ```typescript - * ... - * hierarchyBoundaries: [ - * ApiItemKind.Namespace, - * ], - * ... - * ``` + * @public + */ +export interface SectionHierarchyConfig extends HierarchyConfigBase, SectionHierarchyOptions {} + +/** + * {@link HierarchyKind.Document} hierarchy configuration options. * - * will result in documents rendered for children of the `Namespace` to be generated in a subdirectory named after - * the `Namespace` item. + * @public + */ +export interface DocumentHierarchyOptions { + /** + * Document name to use for the API item. + */ + readonly documentName?: string | ((apiItem: ApiItem) => string); +} + +/** + * The corresponding API item will get its own document, in the folder for an ancestor of the API item. * - * So for some namespace `Foo` with children `Bar` and `Baz` (assuming `Bar` and `Baz` are item kinds matching - * the configured {@link DocumentationSuiteOptions.documentBoundaries}), the resulting file structure would look like the - * following: + * @public + */ +export interface DocumentHierarchyConfig extends HierarchyConfigBase, SectionHierarchyOptions, DocumentHierarchyOptions {} + +/** + * {@link HierarchyKind.Document} hierarchy configuration options. * - * ``` - * foo.md - * foo - * | bar.md - * | baz.md - * ``` + * @public + */ +export interface FolderHierarchyOptions { + /** + * Placement of the API item's document relative to its generated folder. + * `inside`: The document is placed inside its folder. + * `outside`: The document is placed outside (adjacent to) its folder. + */ + readonly documentPlacement?: "inside" | "outside" | ((apiItem: ApiItem) => "inside" | "outside"); + + /** + * Folder name to use for the API item. + */ + readonly folderName?: string | ((apiItem: ApiItem) => string); +} + +/** + * The corresponding API item will get its own document, in the folder for an ancestor of the API item. * * @public */ -export type HierarchyBoundaries = ApiMemberKind[]; +export interface FolderHierarchyConfig extends HierarchyConfigBase, SectionHierarchyOptions, DocumentHierarchyOptions, FolderHierarchyOptions {} + +/** + * API item hierarchy configuration. + */ +export type HierarchyConfig = SectionHierarchyConfig | DocumentHierarchyConfig | FolderHierarchyConfig; /** * Options for configuring the documentation suite generated by the API Item -\> Documentation Domain transformation. @@ -109,46 +144,14 @@ export interface DocumentationSuiteOptions { * * @defaultValue `true` * - * @remarks Note: `Model` items will never have a breadcrumb rendered, even if this is specfied. + * @remarks Note: `Model` items will never have a breadcrumb rendered, even if this is specified. */ includeBreadcrumb?: boolean; /** - * See {@link DocumentBoundaries}. - * - * @defaultValue {@link DefaultDocumentationSuiteOptions.defaultDocumentBoundaries} - */ - documentBoundaries?: DocumentBoundaries; - - /** - * See {@link HierarchyBoundaries}. - * - * @defaultValue {@link DefaultDocumentationSuiteOptions.defaultHierarchyBoundaries} - */ - hierarchyBoundaries?: HierarchyBoundaries; - - /** - * Generate a file name for the provided `ApiItem`. - * - * @remarks - * - * Note that this is not the complete file name, but the "leaf" component of the final file name. - * Additional prefixes and suffixes will be appended to ensure file name collisions do not occur. - * - * This also does not contain the file extension. - * - * @example - * - * We are given a class API item "Bar" in package "Foo", and this returns "foo". - * The final file name in this case might be something like "foo-bar-class". - * - * @param apiItem - The API item for which the pre-modification file name is being generated. - * - * @returns The pre-modification file name for the API item. - * - * @defaultValue {@link DefaultDocumentationSuiteOptions.defaultGetFileNameForItem} + * {@link HierarchyConfig} to use for the provided API item. */ - getFileNameForItem?: (apiItem: ApiItem) => string; + hierarchyOptions?: HierarchyConfig | ((apiItem: ApiItem) => HierarchyConfig); /** * Optionally provide an override for the URI base used in links generated for the provided `ApiItem`. @@ -166,17 +169,6 @@ export interface DocumentationSuiteOptions { */ getUriBaseOverrideForItem?: (apiItem: ApiItem) => string | undefined; - /** - * Generate heading text for the provided `ApiItem`. - * - * @param apiItem - The API item for which the heading is being generated. - * - * @returns The heading title for the API item. - * - * @defaultValue {@link DefaultDocumentationSuiteOptions.defaultGetHeadingTextForItem} - */ - getHeadingTextForItem?: (apiItem: ApiItem) => string; - /** * Generate link text for the provided `ApiItem`. * @@ -393,11 +385,7 @@ export namespace DefaultDocumentationSuiteOptions { const defaultDocumentationSuiteOptions: Required = { includeTopLevelDocumentHeading: true, includeBreadcrumb: true, - documentBoundaries: DefaultDocumentationSuiteOptions.defaultDocumentBoundaries, - hierarchyBoundaries: DefaultDocumentationSuiteOptions.defaultHierarchyBoundaries, - getFileNameForItem: DefaultDocumentationSuiteOptions.defaultGetFileNameForItem, getUriBaseOverrideForItem: DefaultDocumentationSuiteOptions.defaultGetUriBaseOverrideForItem, - getHeadingTextForItem: DefaultDocumentationSuiteOptions.defaultGetHeadingTextForItem, getLinkTextForItem: DefaultDocumentationSuiteOptions.defaultGetLinkTextForItem, getAlertsForItem: DefaultDocumentationSuiteOptions.defaultGetAlertsForItem, skipPackage: DefaultDocumentationSuiteOptions.defaultSkipPackage, From f80e4a638da9c7892f8541d32a645a7ebe0db6d5 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Mon, 16 Dec 2024 23:08:25 +0000 Subject: [PATCH 02/54] chore: Add `DeepRequired` utility type --- .../src/utilities/TypeUtilities.ts | 11 +++++++++++ tools/api-markdown-documenter/src/utilities/index.ts | 7 ++++--- 2 files changed, 15 insertions(+), 3 deletions(-) create mode 100644 tools/api-markdown-documenter/src/utilities/TypeUtilities.ts diff --git a/tools/api-markdown-documenter/src/utilities/TypeUtilities.ts b/tools/api-markdown-documenter/src/utilities/TypeUtilities.ts new file mode 100644 index 000000000000..6d8c3b4156ae --- /dev/null +++ b/tools/api-markdown-documenter/src/utilities/TypeUtilities.ts @@ -0,0 +1,11 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +/** + * Recursive variant of the `Required` utility type. + */ +export type DeepRequired = { + [K in keyof T]: DeepRequired +} & Required; diff --git a/tools/api-markdown-documenter/src/utilities/index.ts b/tools/api-markdown-documenter/src/utilities/index.ts index bec47e1e4f08..d3e4969ef77e 100644 --- a/tools/api-markdown-documenter/src/utilities/index.ts +++ b/tools/api-markdown-documenter/src/utilities/index.ts @@ -3,7 +3,8 @@ * Licensed under the MIT License. */ -// All of the utilities here are meant to be used outside of this directory. -// eslint-disable-next-line no-restricted-syntax +/* eslint-disable no-restricted-syntax */ + export * from "./ApiItemUtilities.js"; -export { injectSeparator } from "./ArrayUtilities.js"; +export * from "./ArrayUtilities.js"; +export * from "./TypeUtilities.js"; From ec1242f6caac2f565eae5e41648a260429c0d9da Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Mon, 16 Dec 2024 23:42:30 +0000 Subject: [PATCH 03/54] chore: Type aliases and helper functions --- .../src/utilities/ApiItemUtilities.ts | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts b/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts index e3f126aeef47..a234fdbe731c 100644 --- a/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts +++ b/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts @@ -41,6 +41,28 @@ import type { Logger } from "../Logging.js"; * This module contains general `ApiItem`-related types and utilities. */ +/** + * Represents "valid" API item kinds. I.e., not `None`. + * + * @public + */ +export type ValidApiItemKind = Omit; + + +/** + * Gets the {@link ValidApiItemKind} for the provided API item. Throws if the item's kind is "None". + */ +export function getApiItemKind(apiItem: ApiItem): ValidApiItemKind { + switch (apiItem.kind) { + case ApiItemKind.None: { + throw new Error(`Encountered an API item with kind "None": "${apiItem.displayName}".`); + } + default:{ + return apiItem.kind as ValidApiItemKind; + } + } +} + /** * Represents "member" API item kinds. * These are the kinds of items the system supports generally for rendering, file-system configuration, etc. @@ -62,6 +84,22 @@ export type ApiMemberKind = Omit< ApiItemKind.EntryPoint | ApiItemKind.Model | ApiItemKind.None | ApiItemKind.Package >; +/** + * Gets the {@link ApiMemberKind} for the provided API item. Throws if the item's kind is not a valid member kind. + */ +export function getApiMemberKind(apiItem: ApiItem): ApiMemberKind { + switch (apiItem.kind) { + case ApiItemKind.EntryPoint: + case ApiItemKind.Model: + case ApiItemKind.Package: { + throw new Error(`Expected API item to be a member kind, but got "${apiItem.kind}": "${apiItem.displayName}".`); + } + default:{ + return getApiItemKind(apiItem) as ApiMemberKind; + } + } +} + /** * `ApiItem` union type representing function-like API kinds. * From 410049c78cc25529114bfc11c1010e08277df95a Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Mon, 16 Dec 2024 23:42:35 +0000 Subject: [PATCH 04/54] [WIP] --- .../DocumentationSuiteOptions.ts | 179 +++++++++++------- 1 file changed, 111 insertions(+), 68 deletions(-) diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts index c1eb76817675..a898f4ce2564 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts @@ -12,7 +12,6 @@ import { } from "@microsoft/api-extractor-model"; import { - type ApiMemberKind, getQualifiedApiItemName, getUnscopedPackageName, getSafeFilenameForName, @@ -20,6 +19,8 @@ import { getSingleLineExcerptText, isDeprecated, getReleaseTag, + type DeepRequired, + getApiItemKind, } from "../../utilities/index.js"; /** @@ -151,7 +152,7 @@ export interface DocumentationSuiteOptions { /** * {@link HierarchyConfig} to use for the provided API item. */ - hierarchyOptions?: HierarchyConfig | ((apiItem: ApiItem) => HierarchyConfig); + readonly hierarchyOptions?: HierarchyConfig | ((apiItem: ApiItem) => HierarchyConfig); /** * Optionally provide an override for the URI base used in links generated for the provided `ApiItem`. @@ -228,6 +229,96 @@ export interface DocumentationSuiteOptions { minimumReleaseLevel?: Omit; } +/** + * Default {@link SectionHierarchyOptions.headingText}. + * + * Uses the item's qualified API name, but is handled differently for the following items: + * + * - Model: Uses "index". + * + * - Package: Uses the unscoped package name. + */ +function defaultHeadingText(apiItem: ApiItem): string { + const kind = getApiItemKind(apiItem); + switch (kind) { + case ApiItemKind.Model: { + return "API Overview"; + } + case ApiItemKind.CallSignature: + case ApiItemKind.ConstructSignature: + case ApiItemKind.IndexSignature: { + // For signature items, the display-name is not particularly useful information + // ("(constructor)", "(call)", etc.). + // Instead, we will use a cleaned up variation on the type signature. + const excerpt = getSingleLineExcerptText((apiItem as ApiDeclaredItem).excerpt); + return trimTrailingSemicolon(excerpt); + } + default: { + return apiItem.displayName; + } + } +} + +const defaultSectionHierarchyConfig: DeepRequired = { + kind: HierarchyKind.Section, + headingText: defaultHeadingText, +} + +/** + * Default {@link DocumentHierarchyOptions.documentName} for non-folder hierarchy documents. + * + * Uses the item's qualified API name, but is handled differently for the following items: + * + * - Model: Uses "index". + * + * - Package: Uses the unscoped package name. + */ +function defaultDocumentName(apiItem: ApiItem): string { + const kind = getApiItemKind(apiItem); + switch (kind) { + case ApiItemKind.Model: { + return "model"; + } + case ApiItemKind.Package: { + return getSafeFilenameForName(getUnscopedPackageName(apiItem as ApiPackage)); + } + default: { + // TODO: append item kind postfix + return getQualifiedApiItemName(apiItem); + } + } +} + +const defaultDocumentHierarchyConfig: DeepRequired = { + kind: HierarchyKind.Document, + headingText: defaultHeadingText, + documentName: defaultDocumentName, +} + +function defaultFolderName(apiItem: ApiItem): string { + const kind = getApiItemKind(apiItem); + switch (kind) { + case ApiItemKind.Model: { + return "model"; + } + case ApiItemKind.Package: { + return getSafeFilenameForName(getUnscopedPackageName(apiItem as ApiPackage)); + } + default: { + // TODO: append item kind postfix + return getQualifiedApiItemName(apiItem); + } + } +} + +const defaultFolderHierarchyConfig: DeepRequired = { + kind: HierarchyKind.Folder, + headingText: defaultHeadingText, + documentPlacement: "inside", + documentName: "index", // Documents for items that get their own folder are always named "index" by default. + folderName: defaultFolderName, +} + /** * Contains a list of default documentation transformations, used by {@link DocumentationSuiteOptions}. * @@ -236,50 +327,26 @@ export interface DocumentationSuiteOptions { // eslint-disable-next-line @typescript-eslint/no-namespace export namespace DefaultDocumentationSuiteOptions { /** - * Default {@link DocumentationSuiteOptions.documentBoundaries}. - * - * Generates separate documents for the following API item kinds: - * - * - Class - * - * - Interface - * - * - Namespace + * Default {@link DocumentationSuiteOptions.hierarchyOptions}. */ - export const defaultDocumentBoundaries: ApiMemberKind[] = [ - ApiItemKind.Class, - ApiItemKind.Interface, - ApiItemKind.Namespace, - ]; + export function defaultHierarchyOptions(apiItem: ApiItem): HierarchyConfig { + const kind = getApiItemKind(apiItem); - /** - * Default {@link DocumentationSuiteOptions.hierarchyBoundaries}. - * - * Creates sub-directories for the following API item kinds: - * - * - Namespace - */ - export const defaultHierarchyBoundaries: ApiMemberKind[] = [ApiItemKind.Namespace]; - - /** - * Default {@link DocumentationSuiteOptions.getFileNameForItem}. - * - * Uses the item's qualified API name, but is handled differently for the following items: - * - * - Model: Uses "index". - * - * - Package: Uses the unscoped package name. - */ - export function defaultGetFileNameForItem(apiItem: ApiItem): string { - switch (apiItem.kind) { - case ApiItemKind.Model: { - return "index"; - } + // TODO: audit these + switch (kind) { + case ApiItemKind.Namespace: case ApiItemKind.Package: { - return getSafeFilenameForName(getUnscopedPackageName(apiItem as ApiPackage)); + return defaultFolderHierarchyConfig; + } + case ApiItemKind.Class: + case ApiItemKind.Interface: + case ApiItemKind.EntryPoint: + case ApiItemKind.Model: + case ApiItemKind.TypeAlias: { + return defaultDocumentHierarchyConfig; } default: { - return getQualifiedApiItemName(apiItem); + return defaultSectionHierarchyConfig; } } } @@ -293,31 +360,6 @@ export namespace DefaultDocumentationSuiteOptions { return undefined; } - /** - * Default {@link DocumentationSuiteOptions.getHeadingTextForItem}. - * - * Uses the item's `displayName`, except for `Model` items, in which case the text "API Overview" is displayed. - */ - export function defaultGetHeadingTextForItem(apiItem: ApiItem): string { - switch (apiItem.kind) { - case ApiItemKind.Model: { - return "API Overview"; - } - case ApiItemKind.CallSignature: - case ApiItemKind.ConstructSignature: - case ApiItemKind.IndexSignature: { - // For signature items, the display-name is not particularly useful information - // ("(constructor)", "(call)", etc.). - // Instead, we will use a cleaned up variation on the type signature. - const excerpt = getSingleLineExcerptText((apiItem as ApiDeclaredItem).excerpt); - return trimTrailingSemicolon(excerpt); - } - default: { - return apiItem.displayName; - } - } - } - /** * Default {@link DocumentationSuiteOptions.getLinkTextForItem}. * @@ -382,7 +424,8 @@ export namespace DefaultDocumentationSuiteOptions { /** * Default {@link DocumentationSuiteOptions} value. */ -const defaultDocumentationSuiteOptions: Required = { +const defaultDocumentationSuiteOptions: DeepRequired = { + hierarchyOptions: DefaultDocumentationSuiteOptions.defaultHierarchyOptions, includeTopLevelDocumentHeading: true, includeBreadcrumb: true, getUriBaseOverrideForItem: DefaultDocumentationSuiteOptions.defaultGetUriBaseOverrideForItem, @@ -398,7 +441,7 @@ const defaultDocumentationSuiteOptions: Required = { */ export function getDocumentationSuiteOptionsWithDefaults( inputOptions: DocumentationSuiteOptions, -): Required { +): DeepRequired { return { ...defaultDocumentationSuiteOptions, ...inputOptions, From 9d3ecb25f731b564164564b824e796a09d64a4bc Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Mon, 16 Dec 2024 23:42:54 +0000 Subject: [PATCH 05/54] style: Prettier --- .../DocumentationSuiteOptions.ts | 31 ++++++++++++++----- .../src/utilities/ApiItemUtilities.ts | 9 +++--- .../src/utilities/TypeUtilities.ts | 2 +- 3 files changed, 29 insertions(+), 13 deletions(-) diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts index a898f4ce2564..3cf198610f68 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts @@ -72,7 +72,9 @@ export interface SectionHierarchyOptions { * * @public */ -export interface SectionHierarchyConfig extends HierarchyConfigBase, SectionHierarchyOptions {} +export interface SectionHierarchyConfig + extends HierarchyConfigBase, + SectionHierarchyOptions {} /** * {@link HierarchyKind.Document} hierarchy configuration options. @@ -91,7 +93,10 @@ export interface DocumentHierarchyOptions { * * @public */ -export interface DocumentHierarchyConfig extends HierarchyConfigBase, SectionHierarchyOptions, DocumentHierarchyOptions {} +export interface DocumentHierarchyConfig + extends HierarchyConfigBase, + SectionHierarchyOptions, + DocumentHierarchyOptions {} /** * {@link HierarchyKind.Document} hierarchy configuration options. @@ -104,7 +109,10 @@ export interface FolderHierarchyOptions { * `inside`: The document is placed inside its folder. * `outside`: The document is placed outside (adjacent to) its folder. */ - readonly documentPlacement?: "inside" | "outside" | ((apiItem: ApiItem) => "inside" | "outside"); + readonly documentPlacement?: + | "inside" + | "outside" + | ((apiItem: ApiItem) => "inside" | "outside"); /** * Folder name to use for the API item. @@ -117,12 +125,19 @@ export interface FolderHierarchyOptions { * * @public */ -export interface FolderHierarchyConfig extends HierarchyConfigBase, SectionHierarchyOptions, DocumentHierarchyOptions, FolderHierarchyOptions {} +export interface FolderHierarchyConfig + extends HierarchyConfigBase, + SectionHierarchyOptions, + DocumentHierarchyOptions, + FolderHierarchyOptions {} /** * API item hierarchy configuration. */ -export type HierarchyConfig = SectionHierarchyConfig | DocumentHierarchyConfig | FolderHierarchyConfig; +export type HierarchyConfig = + | SectionHierarchyConfig + | DocumentHierarchyConfig + | FolderHierarchyConfig; /** * Options for configuring the documentation suite generated by the API Item -\> Documentation Domain transformation. @@ -262,7 +277,7 @@ function defaultHeadingText(apiItem: ApiItem): string { const defaultSectionHierarchyConfig: DeepRequired = { kind: HierarchyKind.Section, headingText: defaultHeadingText, -} +}; /** * Default {@link DocumentHierarchyOptions.documentName} for non-folder hierarchy documents. @@ -293,7 +308,7 @@ const defaultDocumentHierarchyConfig: DeepRequired = { kind: HierarchyKind.Document, headingText: defaultHeadingText, documentName: defaultDocumentName, -} +}; function defaultFolderName(apiItem: ApiItem): string { const kind = getApiItemKind(apiItem); @@ -317,7 +332,7 @@ const defaultFolderHierarchyConfig: DeepRequired = { documentPlacement: "inside", documentName: "index", // Documents for items that get their own folder are always named "index" by default. folderName: defaultFolderName, -} +}; /** * Contains a list of default documentation transformations, used by {@link DocumentationSuiteOptions}. diff --git a/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts b/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts index a234fdbe731c..e70f48f05fcb 100644 --- a/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts +++ b/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts @@ -48,7 +48,6 @@ import type { Logger } from "../Logging.js"; */ export type ValidApiItemKind = Omit; - /** * Gets the {@link ValidApiItemKind} for the provided API item. Throws if the item's kind is "None". */ @@ -57,7 +56,7 @@ export function getApiItemKind(apiItem: ApiItem): ValidApiItemKind { case ApiItemKind.None: { throw new Error(`Encountered an API item with kind "None": "${apiItem.displayName}".`); } - default:{ + default: { return apiItem.kind as ValidApiItemKind; } } @@ -92,9 +91,11 @@ export function getApiMemberKind(apiItem: ApiItem): ApiMemberKind { case ApiItemKind.EntryPoint: case ApiItemKind.Model: case ApiItemKind.Package: { - throw new Error(`Expected API item to be a member kind, but got "${apiItem.kind}": "${apiItem.displayName}".`); + throw new Error( + `Expected API item to be a member kind, but got "${apiItem.kind}": "${apiItem.displayName}".`, + ); } - default:{ + default: { return getApiItemKind(apiItem) as ApiMemberKind; } } diff --git a/tools/api-markdown-documenter/src/utilities/TypeUtilities.ts b/tools/api-markdown-documenter/src/utilities/TypeUtilities.ts index 6d8c3b4156ae..93eb903662ce 100644 --- a/tools/api-markdown-documenter/src/utilities/TypeUtilities.ts +++ b/tools/api-markdown-documenter/src/utilities/TypeUtilities.ts @@ -7,5 +7,5 @@ * Recursive variant of the `Required` utility type. */ export type DeepRequired = { - [K in keyof T]: DeepRequired + [K in keyof T]: DeepRequired; } & Required; From b8c8f83eb2a88685ef3b0311b02629fd88667664 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Tue, 17 Dec 2024 02:12:57 +0000 Subject: [PATCH 06/54] WIP --- .../src/ApiItemUtilitiesModule.ts | 2 + .../ApiItemTransformUtilities.ts | 129 ++----- .../DocumentationSuiteOptions.ts | 260 +------------- .../configuration/HierarchyOptions.ts | 323 ++++++++++++++++++ .../configuration/Utilities.ts | 14 + .../configuration/index.ts | 16 +- .../api-item-transforms/helpers/Helpers.ts | 2 +- .../src/api-item-transforms/index.ts | 13 +- tools/api-markdown-documenter/src/index.ts | 10 +- .../src/test/EndToEndTests.ts | 159 ++++++--- .../src/test/HtmlEndToEnd.test.ts | 65 ++-- .../src/test/MarkdownEndToEnd.test.ts | 51 +-- .../src/utilities/ApiItemUtilities.ts | 13 +- .../src/utilities/TypeUtilities.ts | 21 +- 14 files changed, 601 insertions(+), 477 deletions(-) create mode 100644 tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts create mode 100644 tools/api-markdown-documenter/src/api-item-transforms/configuration/Utilities.ts diff --git a/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts b/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts index a4ac8099e913..3fc7053aea85 100644 --- a/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts +++ b/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts @@ -16,10 +16,12 @@ export { } from "./api-item-transforms/index.js"; export { ancestryHasModifierTag, + getApiItemKind, getCustomBlockComments, getDefaultValueBlock, getDeprecatedBlock, getExampleBlocks, + getFileSafeNameForApiItem, getModifiers, getModifierTags, getQualifiedApiItemName, 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 c12eb4dd5711..16b559efb543 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts @@ -9,12 +9,13 @@ import { type ApiItem, ApiItemKind, ReleaseTag } from "@microsoft/api-extractor- import type { Heading } from "../Heading.js"; import type { Link } from "../Link.js"; -import { getQualifiedApiItemName, getReleaseTag } from "../utilities/index.js"; +import { getQualifiedApiItemName, getReleaseTag, getValueOrDerived, type DeepRequired } from "../utilities/index.js"; -import type { - ApiItemTransformationConfiguration, - DocumentBoundaries, - HierarchyBoundaries, +import { + HierarchyKind, + type ApiItemTransformationConfiguration, + type DocumentBoundaries, + type HierarchyBoundaries, } from "./configuration/index.js"; /** @@ -268,7 +269,7 @@ export function getHeadingForApiItem( */ function getHeadingIdForApiItem( apiItem: ApiItem, - config: Required, + config: DeepRequired, ): string { let baseName: string | undefined; const apiItemKind: ApiItemKind = apiItem.kind; @@ -295,7 +296,7 @@ function getHeadingIdForApiItem( } /** - * Gets the "filted" parent of the provided API item. + * Gets the "filtered" parent of the provided API item. * * @remarks This logic specifically skips items of the following kinds: * @@ -315,16 +316,16 @@ function getFilteredParent(apiItem: ApiItem): ApiItem | undefined { /** * Gets the ancestral hierarchy of the provided API item by walking up the parentage graph and emitting any items - * matching the `includePredecate` until it reaches an item that matches the `breakPredecate`. + * matching the `includePredicate` until it reaches an item that matches the `breakPredicate`. * * @remarks Notes: * - * - This will not include the provided item itself, even if it matches the `includePredecate`. + * - This will not include the provided item itself, even if it matches the `includePredicate`. * - * - This will not include the item matching the `breakPredecate`, even if they match the `includePredecate`. + * - This will not include the item matching the `breakPredicate`, even if they match the `includePredicate`. * * @param apiItem - The API item whose ancestral hierarchy is being queried. - * @param includePredecate - Predicate to determine which items in the hierarchy should be preserved in the + * @param includePredicate - Predicate to determine which items in the hierarchy should be preserved in the * returned list. The provided API item will not be included in the output, even if it would be included by this. * @param breakPredicate - Predicate to determine when to break from the traversal and return. * The item matching this predicate will not be included, even if it would be included by `includePredicate`. @@ -333,7 +334,7 @@ function getFilteredParent(apiItem: ApiItem): ApiItem | undefined { */ export function getAncestralHierarchy( apiItem: ApiItem, - includePredecate: (apiItem: ApiItem) => boolean, + includePredicate: (apiItem: ApiItem) => boolean, breakPredicate?: (apiItem: ApiItem) => boolean, ): ApiItem[] { const matches: ApiItem[] = []; @@ -343,7 +344,7 @@ export function getAncestralHierarchy( hierarchyItem !== undefined && (breakPredicate === undefined || !breakPredicate(hierarchyItem)) ) { - if (includePredecate(hierarchyItem)) { + if (includePredicate(hierarchyItem)) { matches.push(hierarchyItem); } hierarchyItem = getFilteredParent(hierarchyItem); @@ -352,116 +353,46 @@ export function getAncestralHierarchy( } /** - * Determines whether or not the specified API item kind is one that should be rendered to its own document. - * - * @remarks This is essentially a wrapper around {@link DocumentationSuiteOptions.documentBoundaries}, but also enforces - * system-wide invariants. - * - * Namely... - * - * - `Model` and `Package` items are *always* rendered to their own documents, regardless of the specified boundaries. - * - * - `EntryPoint` items are *never* rendered to their own documents (as they are completely ignored by this system), - * regardless of the specified boundaries. - * - * @param kind - The kind of API item. - * @param documentBoundaries - See {@link DocumentBoundaries} - * - * @returns `true` if the item should be rendered to its own document. `false` otherwise. - */ -export function doesItemKindRequireOwnDocument( - kind: ApiItemKind, - documentBoundaries: DocumentBoundaries, -): boolean { - if ( - kind === ApiItemKind.EntryPoint || - kind === ApiItemKind.Model || - kind === ApiItemKind.Package - ) { - return true; - } - return documentBoundaries.includes(kind); -} - -/** - * Determines whether or not the specified API item is one that should be rendered to its own document. - * - * @remarks - * - * This is essentially a wrapper around {@link DocumentationSuiteOptions.hierarchyBoundaries}, but also enforces - * system-wide invariants. - * - * Namely... - * - * - `Package` items are *always* rendered to their own documents, regardless of the specified boundaries. - * - * - `EntryPoint` items are *never* rendered to their own documents (as they are completely ignored by this system), - * regardless of the specified boundaries. + * Determines whether or not the specified API item is one that should be rendered to its own document + * (as opposed to being rendered to a section under some ancestor item's document). * * @param apiItem - The API being queried. - * @param documentBoundaries - See {@link DocumentBoundaries} + * @param config - See {@link ApiItemTransformationConfiguration}. * * @public */ export function doesItemRequireOwnDocument( apiItem: ApiItem, - documentBoundaries: DocumentBoundaries, + config: DeepRequired, ): boolean { - return doesItemKindRequireOwnDocument(apiItem.kind, documentBoundaries); + const hierarchy = getValueOrDerived(config.hierarchy, apiItem); + return hierarchy.kind !== HierarchyKind.Section; } /** - * Determines whether or not the specified API item kind is one that should generate directory-wise hierarchy + * Determines whether or not the specified API item is one that should generate directory-wise hierarchy * in the resulting documentation suite. * I.e. whether or not child item documents should be generated under a sub-directory adjacent to the item in question. * * @remarks - * - * This is essentially a wrapper around {@link DocumentationSuiteOptions.hierarchyBoundaries}, but also enforces - * system-wide invariants. - * - * Namely... - * - * - `Package` items are *always* rendered to their own documents, regardless of the specified boundaries. - * - * - `EntryPoint` items are *never* rendered to their own documents (as they are completely ignored by this system), + * `EntryPoint` items are *never* rendered to their own documents (as they are completely ignored by this system), * regardless of the specified boundaries. * - * @param kind - The kind of API item. - * @param hierarchyBoundaries - See {@link HierarchyBoundaries} - * - * @returns `true` if the item should contribute to directory-wise hierarchy in the output. `false` otherwise. + * @param apiItem - The API item being queried. + * @param config - See {@link ApiItemTransformationConfiguration}. */ -function doesItemKindGenerateHierarchy( - kind: ApiItemKind, - hierarchyBoundaries: HierarchyBoundaries, +function doesItemGenerateHierarchy( + apiItem: ApiItem, + config: DeepRequired, ): boolean { - if (kind === ApiItemKind.Package) { - return true; - } - if (kind === ApiItemKind.EntryPoint) { + if (apiItem.kind === ApiItemKind.EntryPoint) { // The same API item within a package can be included in multiple entry-points, so it doesn't make sense to // include it in generated hierarchy. return false; } - return hierarchyBoundaries.includes(kind); -} -/** - * Determines whether or not the specified API item is one that should generate directory-wise hierarchy - * in the resulting documentation suite. - * I.e. whether or not child item documents should be generated under a sub-directory adjacent to the item in question. - * - * @remarks This is based on the item's `kind`. See {@link doesItemKindGenerateHierarchy}. - * - * @param apiItem - The API item being queried. - * @param hierarchyBoundaries - See {@link HierarchyBoundaries} - */ -function doesItemGenerateHierarchy( - apiItem: ApiItem, - hierarchyBoundaries: HierarchyBoundaries, -): boolean { - return doesItemKindGenerateHierarchy(apiItem.kind, hierarchyBoundaries); + const hierarchy = getValueOrDerived(config.hierarchy, apiItem); + return hierarchy.kind === HierarchyKind.Folder; } /** diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts index 3cf198610f68..78a0375eeba4 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts @@ -12,132 +12,14 @@ import { } from "@microsoft/api-extractor-model"; import { - getQualifiedApiItemName, - getUnscopedPackageName, - getSafeFilenameForName, getConciseSignature, getSingleLineExcerptText, isDeprecated, getReleaseTag, - type DeepRequired, - getApiItemKind, } from "../../utilities/index.js"; -/** - * Kind of documentation suite hierarchy. - * - * @public - */ -export enum HierarchyKind { - /** - * The API item gets a section under the document representing an ancestor of the API item. - */ - Section = "Section", - - /** - * The API item gets its own document, in the folder for an ancestor of the API item. - */ - Document = "Document", - - /** - * The API item gets its own document, and generates folder hierarchy for all descendent API items. - */ - Folder = "Folder", -} - -/** - * {@link TODO} base interface. - */ -export interface HierarchyConfigBase { - /** - * {@inheritDoc HierarchyKind} - */ - readonly kind: THierarchyKind; -} - -/** - * {@link HierarchyKind.Section} hierarchy configuration options. - * - * @public - */ -export interface SectionHierarchyOptions { - /** - * Heading text to use for the API item. - */ - readonly headingText?: string | ((apiItem: ApiItem) => string); -} - -/** - * The corresponding API item will be placed in a section under the document representing an ancestor of the API item. - * - * @public - */ -export interface SectionHierarchyConfig - extends HierarchyConfigBase, - SectionHierarchyOptions {} - -/** - * {@link HierarchyKind.Document} hierarchy configuration options. - * - * @public - */ -export interface DocumentHierarchyOptions { - /** - * Document name to use for the API item. - */ - readonly documentName?: string | ((apiItem: ApiItem) => string); -} - -/** - * The corresponding API item will get its own document, in the folder for an ancestor of the API item. - * - * @public - */ -export interface DocumentHierarchyConfig - extends HierarchyConfigBase, - SectionHierarchyOptions, - DocumentHierarchyOptions {} - -/** - * {@link HierarchyKind.Document} hierarchy configuration options. - * - * @public - */ -export interface FolderHierarchyOptions { - /** - * Placement of the API item's document relative to its generated folder. - * `inside`: The document is placed inside its folder. - * `outside`: The document is placed outside (adjacent to) its folder. - */ - readonly documentPlacement?: - | "inside" - | "outside" - | ((apiItem: ApiItem) => "inside" | "outside"); - - /** - * Folder name to use for the API item. - */ - readonly folderName?: string | ((apiItem: ApiItem) => string); -} - -/** - * The corresponding API item will get its own document, in the folder for an ancestor of the API item. - * - * @public - */ -export interface FolderHierarchyConfig - extends HierarchyConfigBase, - SectionHierarchyOptions, - DocumentHierarchyOptions, - FolderHierarchyOptions {} - -/** - * API item hierarchy configuration. - */ -export type HierarchyConfig = - | SectionHierarchyConfig - | DocumentHierarchyConfig - | FolderHierarchyConfig; +import { defaultHierarchyOptions, type HierarchyOptions } from "./HierarchyOptions.js"; +import { trimTrailingSemicolon } from "./Utilities.js"; /** * Options for configuring the documentation suite generated by the API Item -\> Documentation Domain transformation. @@ -167,7 +49,7 @@ export interface DocumentationSuiteOptions { /** * {@link HierarchyConfig} to use for the provided API item. */ - readonly hierarchyOptions?: HierarchyConfig | ((apiItem: ApiItem) => HierarchyConfig); + readonly hierarchy?: Partial; /** * Optionally provide an override for the URI base used in links generated for the provided `ApiItem`. @@ -244,96 +126,6 @@ export interface DocumentationSuiteOptions { minimumReleaseLevel?: Omit; } -/** - * Default {@link SectionHierarchyOptions.headingText}. - * - * Uses the item's qualified API name, but is handled differently for the following items: - * - * - Model: Uses "index". - * - * - Package: Uses the unscoped package name. - */ -function defaultHeadingText(apiItem: ApiItem): string { - const kind = getApiItemKind(apiItem); - switch (kind) { - case ApiItemKind.Model: { - return "API Overview"; - } - case ApiItemKind.CallSignature: - case ApiItemKind.ConstructSignature: - case ApiItemKind.IndexSignature: { - // For signature items, the display-name is not particularly useful information - // ("(constructor)", "(call)", etc.). - // Instead, we will use a cleaned up variation on the type signature. - const excerpt = getSingleLineExcerptText((apiItem as ApiDeclaredItem).excerpt); - return trimTrailingSemicolon(excerpt); - } - default: { - return apiItem.displayName; - } - } -} - -const defaultSectionHierarchyConfig: DeepRequired = { - kind: HierarchyKind.Section, - headingText: defaultHeadingText, -}; - -/** - * Default {@link DocumentHierarchyOptions.documentName} for non-folder hierarchy documents. - * - * Uses the item's qualified API name, but is handled differently for the following items: - * - * - Model: Uses "index". - * - * - Package: Uses the unscoped package name. - */ -function defaultDocumentName(apiItem: ApiItem): string { - const kind = getApiItemKind(apiItem); - switch (kind) { - case ApiItemKind.Model: { - return "model"; - } - case ApiItemKind.Package: { - return getSafeFilenameForName(getUnscopedPackageName(apiItem as ApiPackage)); - } - default: { - // TODO: append item kind postfix - return getQualifiedApiItemName(apiItem); - } - } -} - -const defaultDocumentHierarchyConfig: DeepRequired = { - kind: HierarchyKind.Document, - headingText: defaultHeadingText, - documentName: defaultDocumentName, -}; - -function defaultFolderName(apiItem: ApiItem): string { - const kind = getApiItemKind(apiItem); - switch (kind) { - case ApiItemKind.Model: { - return "model"; - } - case ApiItemKind.Package: { - return getSafeFilenameForName(getUnscopedPackageName(apiItem as ApiPackage)); - } - default: { - // TODO: append item kind postfix - return getQualifiedApiItemName(apiItem); - } - } -} - -const defaultFolderHierarchyConfig: DeepRequired = { - kind: HierarchyKind.Folder, - headingText: defaultHeadingText, - documentPlacement: "inside", - documentName: "index", // Documents for items that get their own folder are always named "index" by default. - folderName: defaultFolderName, -}; - /** * Contains a list of default documentation transformations, used by {@link DocumentationSuiteOptions}. * @@ -341,31 +133,6 @@ const defaultFolderHierarchyConfig: DeepRequired = { */ // eslint-disable-next-line @typescript-eslint/no-namespace export namespace DefaultDocumentationSuiteOptions { - /** - * Default {@link DocumentationSuiteOptions.hierarchyOptions}. - */ - export function defaultHierarchyOptions(apiItem: ApiItem): HierarchyConfig { - const kind = getApiItemKind(apiItem); - - // TODO: audit these - switch (kind) { - case ApiItemKind.Namespace: - case ApiItemKind.Package: { - return defaultFolderHierarchyConfig; - } - case ApiItemKind.Class: - case ApiItemKind.Interface: - case ApiItemKind.EntryPoint: - case ApiItemKind.Model: - case ApiItemKind.TypeAlias: { - return defaultDocumentHierarchyConfig; - } - default: { - return defaultSectionHierarchyConfig; - } - } - } - /** * Default {@link DocumentationSuiteOptions.getUriBaseOverrideForItem}. * @@ -439,8 +206,8 @@ export namespace DefaultDocumentationSuiteOptions { /** * Default {@link DocumentationSuiteOptions} value. */ -const defaultDocumentationSuiteOptions: DeepRequired = { - hierarchyOptions: DefaultDocumentationSuiteOptions.defaultHierarchyOptions, +const defaultDocumentationSuiteOptions: Required = { + hierarchy: defaultHierarchyOptions, includeTopLevelDocumentHeading: true, includeBreadcrumb: true, getUriBaseOverrideForItem: DefaultDocumentationSuiteOptions.defaultGetUriBaseOverrideForItem, @@ -456,19 +223,14 @@ const defaultDocumentationSuiteOptions: DeepRequired */ export function getDocumentationSuiteOptionsWithDefaults( inputOptions: DocumentationSuiteOptions, -): DeepRequired { +): Required { + const hierarchy: Required = { + ...defaultHierarchyOptions, + ...inputOptions.hierarchy, + } return { ...defaultDocumentationSuiteOptions, ...inputOptions, + hierarchy, }; } - -/** - * Trims a trailing semicolon from the provided text, if the text contains one. - */ -function trimTrailingSemicolon(text: string): string { - if (text.endsWith(";")) { - return text.slice(0, text.length - 1); - } - return text; -} diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts new file mode 100644 index 000000000000..75075b931cdb --- /dev/null +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts @@ -0,0 +1,323 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +import { type ApiDeclaredItem, type ApiItem, ApiItemKind } from "@microsoft/api-extractor-model"; + +import { + getQualifiedApiItemName, + getFileSafeNameForApiItem, + getSingleLineExcerptText, + getApiItemKind, + type ValidApiItemKind, +} from "../../utilities/index.js"; + +import { trimTrailingSemicolon } from "./Utilities.js"; + +/** + * Kind of documentation suite hierarchy. + * + * @public + */ +export enum HierarchyKind { + /** + * The API item gets a section under the document representing an ancestor of the API item. + */ + Section = "section", + + /** + * The API item gets its own document, in the folder for an ancestor of the API item. + */ + Document = "document", + + /** + * The API item gets its own document, and generates folder hierarchy for all descendent API items. + */ + Folder = "folder", +} + +/** + * {@link HierarchyConfig} base interface. + * + * @remarks + * Not intended for external use. + * Only exists to share common properties between hierarchy configuration types. + */ +export interface HierarchyConfigBase { + /** + * {@inheritDoc HierarchyKind} + */ + readonly kind: THierarchyKind; +} + +/** + * {@link HierarchyKind.Section} hierarchy configuration options. + * + * @public + */ +export interface SectionHierarchyOptions { + /** + * Heading text to use for the API item. + */ + readonly headingText: string | ((apiItem: ApiItem) => string); +} + +/** + * The corresponding API item will be placed in a section under the document representing an ancestor of the API item. + * + * @public + */ +export interface SectionHierarchyConfig + extends HierarchyConfigBase, + SectionHierarchyOptions {} + +/** + * {@link HierarchyKind.Document} hierarchy configuration options. + * + * @public + */ +export interface DocumentHierarchyOptions { + /** + * Document name to use for the API item. + */ + readonly documentName: string | ((apiItem: ApiItem) => string); +} + +/** + * The corresponding API item will get its own document, in the folder for an ancestor of the API item. + * + * @public + */ +export interface DocumentHierarchyConfig + extends HierarchyConfigBase, + SectionHierarchyOptions, + DocumentHierarchyOptions {} + +/** + * Placement of the API item's document relative to its generated folder. + * + * @remarks Used by {@link FolderHierarchyOptions}. + * + * @public + */ +export enum FolderDocumentPlacement { + /** + * The document is placed inside its folder. + */ + Inside = "inside", + + /** + * The document is placed outside (adjacent to) its folder. + */ + Outside = "outside", +} + +/** + * {@link HierarchyKind.Document} hierarchy configuration options. + * + * @public + */ +export interface FolderHierarchyOptions { + /** + * Placement of the API item's document relative to its generated folder. + * `inside`: The document is placed inside its folder. + * `outside`: The document is placed outside (adjacent to) its folder. + */ + readonly documentPlacement: + | FolderDocumentPlacement + | ((apiItem: ApiItem) => FolderDocumentPlacement); + + /** + * Folder name to use for the API item. + */ + readonly folderName: string | ((apiItem: ApiItem) => string); +} + +/** + * The corresponding API item will get its own document, in the folder for an ancestor of the API item. + * + * @public + */ +export interface FolderHierarchyConfig + extends HierarchyConfigBase, + SectionHierarchyOptions, + DocumentHierarchyOptions, + FolderHierarchyOptions {} + +/** + * API item hierarchy configuration. + */ +export type HierarchyConfig = + | SectionHierarchyConfig + | DocumentHierarchyConfig + | FolderHierarchyConfig; + +/** + * Default {@link SectionHierarchyOptions.headingText}. + * + * Uses the item's qualified API name, but is handled differently for the following items: + * + * - Model: Uses "index". + * + * - Package: Uses the unscoped package name. + */ +function defaultHeadingText(apiItem: ApiItem): string { + const kind = getApiItemKind(apiItem); + switch (kind) { + case ApiItemKind.Model: { + return "API Overview"; + } + case ApiItemKind.CallSignature: + case ApiItemKind.ConstructSignature: + case ApiItemKind.IndexSignature: { + // For signature items, the display-name is not particularly useful information + // ("(constructor)", "(call)", etc.). + // Instead, we will use a cleaned up variation on the type signature. + const excerpt = getSingleLineExcerptText((apiItem as ApiDeclaredItem).excerpt); + return trimTrailingSemicolon(excerpt); + } + default: { + return apiItem.displayName; + } + } +} + +const defaultSectionHierarchyConfig: SectionHierarchyConfig = { + kind: HierarchyKind.Section, + headingText: defaultHeadingText, +}; + +/** + * Default {@link DocumentHierarchyOptions.documentName} for non-folder hierarchy documents. + * + * Uses the item's qualified API name, but is handled differently for the following items: + * + * - Package: Uses the unscoped package name. + */ +function defaultDocumentName(apiItem: ApiItem): string { + const kind = getApiItemKind(apiItem); + switch (kind) { + case ApiItemKind.Package: { + return getFileSafeNameForApiItem(apiItem); + } + default: { + // TODO: append item kind postfix + return getQualifiedApiItemName(apiItem); + } + } +} + +const defaultDocumentHierarchyConfig: DocumentHierarchyConfig = { + kind: HierarchyKind.Document, + headingText: defaultHeadingText, + documentName: defaultDocumentName, +}; + +function defaultFolderName(apiItem: ApiItem): string { + const kind = getApiItemKind(apiItem); + switch (kind) { + case ApiItemKind.Package: { + return getFileSafeNameForApiItem(apiItem); + } + default: { + // TODO: append item kind postfix + return getQualifiedApiItemName(apiItem); + } + } +} + +const defaultFolderHierarchyConfig: FolderHierarchyConfig = { + kind: HierarchyKind.Folder, + headingText: defaultHeadingText, + documentPlacement: FolderDocumentPlacement.Inside, + documentName: "index", // Documents for items that get their own folder are always named "index" by default. + folderName: defaultFolderName, +}; + + +/** + * Hierarchy options by API item kind. + */ +export type HierarchyOptions = { + /** + * Hierarchy configuration for the API item kind. + */ + [Kind in Exclude]: HierarchyConfig; +} & { + /** + * Hierarchy configuration for the `Model` API item kind. + * + * @remarks Always its own document. Never introduces folder hierarchy. + */ + [ApiItemKind.Model]: DocumentHierarchyConfig; + + /** + * Hierarchy configuration for the `Package` API item kind. + * + * @remarks Always introduces folder hierarchy. + * @privateRemarks TODO: Make this fully configurable - there is no real reason for this policy to be baked in. + */ + [ApiItemKind.Package]: FolderHierarchyConfig; + + // TODO: Allow entry-point configuration? +} + +/** + * Default {@link HierarchyOptions}. + */ +export const defaultHierarchyOptions: HierarchyOptions = { + [ApiItemKind.Model]: { + kind: HierarchyKind.Document, + headingText: "API Overview", + documentName: "index", + }, + + // Items that introduce folder hierarchy: + [ApiItemKind.Namespace]: defaultFolderHierarchyConfig, + [ApiItemKind.Package]: defaultFolderHierarchyConfig, + + // Items that get their own document, but do not introduce folder hierarchy: + [ApiItemKind.Class]: defaultDocumentHierarchyConfig, + [ApiItemKind.Enum]: defaultDocumentHierarchyConfig, + [ApiItemKind.Interface]: defaultDocumentHierarchyConfig, + [ApiItemKind.TypeAlias]: defaultDocumentHierarchyConfig, + + // Items that get a section under the document representing an ancestor of the API item: + [ApiItemKind.CallSignature]: defaultSectionHierarchyConfig, + [ApiItemKind.Constructor]: defaultSectionHierarchyConfig, + [ApiItemKind.ConstructSignature]: defaultSectionHierarchyConfig, + [ApiItemKind.EnumMember]: defaultSectionHierarchyConfig, + [ApiItemKind.Function]: defaultSectionHierarchyConfig, + [ApiItemKind.IndexSignature]: defaultSectionHierarchyConfig, + [ApiItemKind.Method]: defaultSectionHierarchyConfig, + [ApiItemKind.MethodSignature]: defaultSectionHierarchyConfig, + [ApiItemKind.Property]: defaultSectionHierarchyConfig, + [ApiItemKind.PropertySignature]: defaultSectionHierarchyConfig, + [ApiItemKind.Variable]: defaultSectionHierarchyConfig, +} + +/** + * Default {@link DocumentationSuiteOptions.hierarchyOptions}. + */ +export const defaultHierarchyConfig = (apiItem: ApiItem): HierarchyConfig => { + const kind = getApiItemKind(apiItem); + + // TODO: audit these + switch (kind) { + case ApiItemKind.Namespace: + case ApiItemKind.Package: { + return defaultFolderHierarchyConfig; + } + case ApiItemKind.Class: + case ApiItemKind.Interface: + case ApiItemKind.EntryPoint: + case ApiItemKind.Model: + case ApiItemKind.TypeAlias: { + return defaultDocumentHierarchyConfig; + } + default: { + return defaultSectionHierarchyConfig; + } + } +}; diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Utilities.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Utilities.ts new file mode 100644 index 000000000000..66ebb0cea6e2 --- /dev/null +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Utilities.ts @@ -0,0 +1,14 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +/** + * Trims a trailing semicolon from the provided text, if the text contains one. + */ +export function trimTrailingSemicolon(text: string): string { + if (text.endsWith(";")) { + return text.slice(0, text.length - 1); + } + return text; +} diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts index da6db4d0575d..06bd4412ab68 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts @@ -8,13 +8,23 @@ export { getApiItemTransformationConfigurationWithDefaults, } from "./Configuration.js"; export { - // Consumers should not use this, it exists externally for documentation purposes only. type DefaultDocumentationSuiteOptions, - type DocumentBoundaries, type DocumentationSuiteOptions, getDocumentationSuiteOptionsWithDefaults, - type HierarchyBoundaries, } from "./DocumentationSuiteOptions.js"; +export { + HierarchyKind, + type HierarchyConfigBase, + type SectionHierarchyOptions, + type SectionHierarchyConfig, + type DocumentHierarchyOptions, + type DocumentHierarchyConfig, + FolderDocumentPlacement, + type FolderHierarchyOptions, + type FolderHierarchyConfig, + type HierarchyConfig, + defaultHierarchyConfig, +} from "./HierarchyOptions.js"; export { type ApiItemTransformationOptions, getApiItemTransformationOptionsWithDefaults, 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 5865ecfed0e5..78573bd70353 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 @@ -997,7 +997,7 @@ export function createChildDetailsSection( // (i.e. it does not get rendered to its own document). // Also only render the section if it actually has contents to render (to avoid empty headings). if ( - !doesItemKindRequireOwnDocument(childItem.itemKind, config.documentBoundaries) && + !doesItemRequireOwnDocument(childItem.itemKind, config) && childItem.items.length > 0 ) { const childContents: DocumentationNode[] = []; diff --git a/tools/api-markdown-documenter/src/api-item-transforms/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/index.ts index 0fb73f836ef1..29d11b1ad178 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/index.ts @@ -18,10 +18,19 @@ export { type ApiItemTransformationConfiguration, type ApiItemTransformationOptions, type DefaultDocumentationSuiteOptions, + defaultHierarchyConfig, + type DocumentHierarchyConfig, + type DocumentHierarchyOptions, type DocumentationSuiteOptions, - type DocumentBoundaries, + FolderDocumentPlacement, + type FolderHierarchyConfig, + type FolderHierarchyOptions, getApiItemTransformationConfigurationWithDefaults, - type HierarchyBoundaries, + type HierarchyConfig, + type HierarchyConfigBase, + HierarchyKind, + type SectionHierarchyConfig, + type SectionHierarchyOptions, type TransformApiItemWithChildren, type TransformApiItemWithoutChildren, } from "./configuration/index.js"; diff --git a/tools/api-markdown-documenter/src/index.ts b/tools/api-markdown-documenter/src/index.ts index 5e336ff66f46..23a32a7aa744 100644 --- a/tools/api-markdown-documenter/src/index.ts +++ b/tools/api-markdown-documenter/src/index.ts @@ -4,11 +4,11 @@ */ /** - * Contains a programatic API for generating {@link https://en.wikipedia.org/wiki/Markdown | Markdown} documentation + * Contains a programmatic API for generating {@link https://en.wikipedia.org/wiki/Markdown | Markdown} documentation * from an API report generated by {@link https://api-extractor.com/ | API-Extractor}. * * @remarks Akin to {@link https://github.com/microsoft/rushstack/tree/main/apps/api-documenter | API-Documenter} and - * is heavily based upon it, but is designed to be more extensible and to be be used programatically. + * is heavily based upon it, but is designed to be more extensible and to be be used programmatically. * * @packageDocumentation */ @@ -18,10 +18,11 @@ export { type ApiItemTransformationOptions, type DefaultDocumentationSuiteOptions, type DocumentationSuiteOptions, - type DocumentBoundaries, + FolderDocumentPlacement, // TODO: remove this once utility APIs can be called with partial configs. getApiItemTransformationConfigurationWithDefaults, - type HierarchyBoundaries, + type HierarchyConfig, + HierarchyKind, type TransformApiItemWithChildren, type TransformApiItemWithoutChildren, transformApiModel, @@ -72,6 +73,7 @@ export { type ApiModifier, type ApiModuleLike, type ApiSignatureLike, + type DeepRequired, } from "./utilities/index.js"; // #region Scoped exports diff --git a/tools/api-markdown-documenter/src/test/EndToEndTests.ts b/tools/api-markdown-documenter/src/test/EndToEndTests.ts index 26a71239774d..4a7069593e40 100644 --- a/tools/api-markdown-documenter/src/test/EndToEndTests.ts +++ b/tools/api-markdown-documenter/src/test/EndToEndTests.ts @@ -5,25 +5,44 @@ import Path from "node:path"; -import type { ApiModel } from "@microsoft/api-extractor-model"; +import { + ApiItemContainerMixin, + ApiItemKind, + type ApiItem, + type ApiModel, +} from "@microsoft/api-extractor-model"; import { FileSystem } from "@rushstack/node-core-library"; import { expect } from "chai"; import { compare } from "dir-compare"; import type { Suite } from "mocha"; -import { loadModel } from "../LoadModel.js"; import { + ApiItemUtilities, + loadModel, + type DocumentNode, + FolderDocumentPlacement, + HierarchyKind, transformApiModel, + type HierarchyConfig, + type DeepRequired, + type MarkdownRenderer, + type HtmlRenderer, type ApiItemTransformationConfiguration, -} from "../api-item-transforms/index.js"; -import type { DocumentNode } from "../documentation-domain/index.js"; +} from "../index.js"; + +/** + * Supported render configuration types. + */ +export type RenderConfig = + | MarkdownRenderer.RenderDocumentsOptions + | HtmlRenderer.RenderDocumentsOptions; /** * End-to-end snapshot test configuration. * * @remarks Generates a test suite with a test for each combination of API Model and test configuration. */ -export interface EndToEndSuiteConfig { +export interface EndToEndSuiteConfig { /** * Name of the outer test suite. */ @@ -49,11 +68,7 @@ export interface EndToEndSuiteConfig { * The end-to-end test scenario to run against the API model. * Writes the output to the specified directory for snapshot comparison. */ - render( - document: DocumentNode, - renderConfig: TRenderConfig, - outputDirectoryPath: string, - ): Promise; + render(document: DocumentNode, config: TRenderConfig): Promise; /** * The models to test. @@ -84,21 +99,17 @@ export interface ApiModelTestOptions { /** * API Item transformation options for a test. */ -export interface EndToEndTestConfig { +export interface EndToEndTestConfig { /** * Test name */ readonly testName: string; /** - * The transformation configuration to use. - */ - readonly transformConfig: Omit; - - /** - * Render configuration. + * Transformation / render configuration */ - readonly renderConfig: TRenderConfig; + readonly renderConfig: Omit & + Omit; } /** @@ -112,7 +123,7 @@ export interface EndToEndTestConfig { * * - Snapshot test comparing the final rendered output against checked-in snapshots. */ -export function endToEndTests( +export function endToEndTests( suiteConfig: EndToEndSuiteConfig, ): Suite { return describe(suiteConfig.suiteName, () => { @@ -125,13 +136,7 @@ export function endToEndTests( }); for (const testConfig of suiteConfig.testConfigs) { - const { - testName, - transformConfig: partialTransformConfig, - renderConfig, - } = testConfig; - - const testOutputPath = Path.join(modelName, testName); + const testOutputPath = Path.join(modelName, testConfig.testName); const temporaryDirectoryPath = Path.resolve( suiteConfig.temporaryOutputDirectoryPath, testOutputPath, @@ -141,19 +146,20 @@ export function endToEndTests( testOutputPath, ); - describe(testName, () => { - let apiItemTransformConfig: ApiItemTransformationConfiguration; + describe(testConfig.testName, () => { + let config: ApiItemTransformationConfiguration & TRenderConfig; before(async () => { - apiItemTransformConfig = { - ...partialTransformConfig, + config = { + ...testConfig.renderConfig, apiModel, - }; + outputDirectoryPath: temporaryDirectoryPath, + } as unknown as ApiItemTransformationConfiguration & TRenderConfig; }); // Run a sanity check to ensure that the suite did not generate multiple documents with the same // output file path. This either indicates a bug in the system, or an bad configuration. it("Ensure no duplicate file paths", () => { - const documents = transformApiModel(apiItemTransformConfig); + const documents = transformApiModel(config); const pathMap = new Map(); for (const document of documents) { @@ -176,15 +182,11 @@ export function endToEndTests( // Clear any existing test_temp data await FileSystem.ensureEmptyFolderAsync(temporaryDirectoryPath); - const documents = transformApiModel(apiItemTransformConfig); + const documents = transformApiModel(config); await Promise.all( documents.map(async (document) => - suiteConfig.render( - document, - renderConfig, - temporaryDirectoryPath, - ), + suiteConfig.render(document, config), ), ); @@ -200,6 +202,87 @@ export function endToEndTests( }); } +/** + * Test hierarchy configs + */ +// eslint-disable-next-line @typescript-eslint/no-namespace +export namespace HierarchyConfigs { + /** + * "Flat" hierarchy: Packages get their own documents, and all descendent API items are rendered as sections under that document. + * @remarks Results in a small number of documents, but can lead to relatively large documents. + */ + export const flat = (apiItem: ApiItem): DeepRequired => { + const kind = ApiItemUtilities.getApiItemKind(apiItem); + + switch (kind) { + case ApiItemKind.Package: { + return { + kind: HierarchyKind.Document, + documentName: ApiItemUtilities.getFileSafeNameForApiItem(apiItem), + headingText: apiItem.displayName, + }; + } + default: { + return { + kind: HierarchyKind.Section, + headingText: apiItem.displayName, + }; + } + } + }; + + /** + * "Sparse" hierarchy: Packages yield folder hierarchy, and all descendent items get their own document under that folder. + * @remarks Leads to many documents, but each document is likely to be relatively small. + */ + export const sparse = (apiItem: ApiItem): DeepRequired => { + const kind = ApiItemUtilities.getApiItemKind(apiItem); + + switch (kind) { + case ApiItemKind.Package: { + const name = ApiItemUtilities.getFileSafeNameForApiItem(apiItem); + return { + kind: HierarchyKind.Folder, + documentPlacement: FolderDocumentPlacement.Outside, + documentName: name, + folderName: name, + headingText: apiItem.displayName, + }; + } + default: { + return { + kind: HierarchyKind.Document, + headingText: apiItem.displayName, + documentName: apiItem.displayName, + }; + } + } + }; + + /** + * "Deep" hierarchy: All "parent" API items generate hierarchy. All other items are rendered as documents under their parent hierarchy. + * @remarks Leads to many documents, but each document is likely to be relatively small. + */ + export const deep = (apiItem: ApiItem): DeepRequired => { + if (ApiItemContainerMixin.isBaseClassOf(apiItem)) { + const name = ApiItemUtilities.getFileSafeNameForApiItem(apiItem); + return { + kind: HierarchyKind.Folder, + documentPlacement: FolderDocumentPlacement.Inside, + documentName: name, + folderName: name, + headingText: apiItem.displayName, + }; + } else { + return { + kind: HierarchyKind.Document, + headingText: apiItem.displayName, + documentName: apiItem.displayName, + }; + } + }; +} + /** * Compares "expected" to "actual" documentation test suite output. * Succeeds the Mocha test if the directory contents match. diff --git a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts index 6a28afe7b443..7ab24d10b44a 100644 --- a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts @@ -6,14 +6,14 @@ import * as Path from "node:path"; import { fileURLToPath } from "node:url"; -import { ApiItemKind, ReleaseTag } from "@microsoft/api-extractor-model"; +import { ReleaseTag } from "@microsoft/api-extractor-model"; import { FileSystem, NewlineKind } from "@rushstack/node-core-library"; -import type { DocumentNode } from "../documentation-domain/index.js"; -import { type RenderDocumentAsHtmlConfig, renderDocumentAsHtml } from "../renderers/index.js"; +import { type DocumentNode, HtmlRenderer } from "../index.js"; import { endToEndTests, + HierarchyConfigs, type ApiModelTestOptions, type EndToEndTestConfig, } from "./EndToEndTests.js"; @@ -50,16 +50,15 @@ const apiModels: ApiModelTestOptions[] = [ // TODO: add other models ]; -const testConfigs: EndToEndTestConfig[] = [ +const testConfigs: EndToEndTestConfig[] = [ /** - * A sample "flat" configuration, which renders every item kind under a package to the package parent document. + * A sample "default" configuration, which renders every item kind under a package to the package parent document. */ { testName: "default-config", - transformConfig: { + renderConfig: { uriRoot: ".", }, - renderConfig: {}, }, /** @@ -67,15 +66,13 @@ const testConfigs: EndToEndTestConfig[] = [ */ { testName: "flat-config", - transformConfig: { + renderConfig: { uriRoot: "docs", includeBreadcrumb: true, includeTopLevelDocumentHeading: false, - documentBoundaries: [], // Render everything to package documents - hierarchyBoundaries: [], // No additional hierarchy beyond the package level + hierarchy: HierarchyConfigs.flat, minimumReleaseLevel: ReleaseTag.Beta, // Only include `@public` and `beta` items in the docs suite }, - renderConfig: {}, }, /** @@ -83,34 +80,29 @@ const testConfigs: EndToEndTestConfig[] = [ */ { testName: "sparse-config", - transformConfig: { + renderConfig: { uriRoot: "docs", includeBreadcrumb: false, includeTopLevelDocumentHeading: true, - // Render everything to its own document - documentBoundaries: [ - ApiItemKind.CallSignature, - ApiItemKind.Class, - ApiItemKind.ConstructSignature, - ApiItemKind.Constructor, - ApiItemKind.Enum, - ApiItemKind.EnumMember, - ApiItemKind.Function, - ApiItemKind.IndexSignature, - ApiItemKind.Interface, - ApiItemKind.Method, - ApiItemKind.MethodSignature, - ApiItemKind.Namespace, - ApiItemKind.Property, - ApiItemKind.PropertySignature, - ApiItemKind.TypeAlias, - ApiItemKind.Variable, - ], - hierarchyBoundaries: [], // No additional hierarchy beyond the package level + hierarchy: HierarchyConfigs.sparse, minimumReleaseLevel: ReleaseTag.Public, // Only include `@public` items in the docs suite skipPackage: (apiPackage) => apiPackage.name === "test-suite-b", // Skip test-suite-b package + startingHeadingLevel: 2, }, + }, + + /** + * A sample "deep" configuration, which generates folder hierarchy for any "container" API items. + */ + { + testName: "sparse-config", renderConfig: { + uriRoot: "docs", + includeBreadcrumb: false, + includeTopLevelDocumentHeading: true, + hierarchy: HierarchyConfigs.sparse, + minimumReleaseLevel: ReleaseTag.Public, // Only include `@public` items in the docs suite + skipPackage: (apiPackage) => apiPackage.name === "test-suite-b", // Skip test-suite-b package startingHeadingLevel: 2, }, }, @@ -118,19 +110,18 @@ const testConfigs: EndToEndTestConfig[] = [ async function renderDocumentToFile( document: DocumentNode, - renderConfig: RenderDocumentAsHtmlConfig, - outputDirectoryPath: string, + renderConfig: HtmlRenderer.RenderDocumentsOptions, ): Promise { - const renderedDocument = renderDocumentAsHtml(document, renderConfig); + const renderedDocument = HtmlRenderer.renderDocument(document, renderConfig); - const filePath = Path.join(outputDirectoryPath, `${document.documentPath}.html`); + const filePath = Path.join(renderConfig.outputDirectoryPath, `${document.documentPath}.html`); await FileSystem.writeFileAsync(filePath, renderedDocument, { convertLineEndings: NewlineKind.Lf, ensureFolderExists: true, }); } -endToEndTests({ +endToEndTests({ suiteName: "Markdown End-to-End Tests", temporaryOutputDirectoryPath: testTemporaryDirectoryPath, snapshotsDirectoryPath, diff --git a/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts index 40d9dfda0a7d..eef5be885190 100644 --- a/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts @@ -6,14 +6,14 @@ import * as Path from "node:path"; import { fileURLToPath } from "node:url"; -import { ApiItemKind, ReleaseTag } from "@microsoft/api-extractor-model"; +import { ReleaseTag } from "@microsoft/api-extractor-model"; import { FileSystem, NewlineKind } from "@rushstack/node-core-library"; -import type { DocumentNode } from "../documentation-domain/index.js"; -import { type MarkdownRenderConfiguration, renderDocumentAsMarkdown } from "../renderers/index.js"; +import { type DocumentNode, MarkdownRenderer } from "../index.js"; import { endToEndTests, + HierarchyConfigs, type ApiModelTestOptions, type EndToEndTestConfig, } from "./EndToEndTests.js"; @@ -50,16 +50,15 @@ const apiModels: ApiModelTestOptions[] = [ // TODO: add other models ]; -const testConfigs: EndToEndTestConfig[] = [ +const testConfigs: EndToEndTestConfig[] = [ /** * A sample "flat" configuration, which renders every item kind under a package to the package parent document. */ { testName: "default-config", - transformConfig: { + renderConfig: { uriRoot: ".", }, - renderConfig: {}, }, /** @@ -67,15 +66,13 @@ const testConfigs: EndToEndTestConfig[] = [ */ { testName: "flat-config", - transformConfig: { + renderConfig: { uriRoot: "docs", includeBreadcrumb: true, includeTopLevelDocumentHeading: false, - documentBoundaries: [], // Render everything to package documents - hierarchyBoundaries: [], // No additional hierarchy beyond the package level + hierarchy: HierarchyConfigs.sparse, minimumReleaseLevel: ReleaseTag.Beta, // Only include `@public` and `beta` items in the docs suite }, - renderConfig: {}, }, /** @@ -83,34 +80,13 @@ const testConfigs: EndToEndTestConfig[] = [ */ { testName: "sparse-config", - transformConfig: { + renderConfig: { uriRoot: "docs", includeBreadcrumb: false, includeTopLevelDocumentHeading: true, - // Render everything to its own document - documentBoundaries: [ - ApiItemKind.CallSignature, - ApiItemKind.Class, - ApiItemKind.ConstructSignature, - ApiItemKind.Constructor, - ApiItemKind.Enum, - ApiItemKind.EnumMember, - ApiItemKind.Function, - ApiItemKind.IndexSignature, - ApiItemKind.Interface, - ApiItemKind.Method, - ApiItemKind.MethodSignature, - ApiItemKind.Namespace, - ApiItemKind.Property, - ApiItemKind.PropertySignature, - ApiItemKind.TypeAlias, - ApiItemKind.Variable, - ], - hierarchyBoundaries: [], // No additional hierarchy beyond the package level + hierarchy: HierarchyConfigs.sparse, minimumReleaseLevel: ReleaseTag.Public, // Only include `@public` items in the docs suite skipPackage: (apiPackage) => apiPackage.name === "test-suite-b", // Skip test-suite-b package - }, - renderConfig: { startingHeadingLevel: 2, }, }, @@ -118,19 +94,18 @@ const testConfigs: EndToEndTestConfig[] = [ async function renderDocumentToFile( document: DocumentNode, - renderConfig: MarkdownRenderConfiguration, - outputDirectoryPath: string, + renderConfig: MarkdownRenderer.RenderDocumentsOptions, ): Promise { - const renderedDocument = renderDocumentAsMarkdown(document, renderConfig); + const renderedDocument = MarkdownRenderer.renderDocument(document, renderConfig); - const filePath = Path.join(outputDirectoryPath, `${document.documentPath}.md`); + const filePath = Path.join(renderConfig.outputDirectoryPath, `${document.documentPath}.md`); await FileSystem.writeFileAsync(filePath, renderedDocument, { convertLineEndings: NewlineKind.Lf, ensureFolderExists: true, }); } -endToEndTests({ +endToEndTests({ suiteName: "Markdown End-to-End Tests", temporaryOutputDirectoryPath: testTemporaryDirectoryPath, snapshotsDirectoryPath, diff --git a/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts b/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts index e70f48f05fcb..04a290757a4c 100644 --- a/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts +++ b/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts @@ -46,7 +46,7 @@ import type { Logger } from "../Logging.js"; * * @public */ -export type ValidApiItemKind = Omit; +export type ValidApiItemKind = Exclude; /** * Gets the {@link ValidApiItemKind} for the provided API item. Throws if the item's kind is "None". @@ -544,10 +544,19 @@ export function getConciseSignature(apiItem: ApiItem): string { return apiItem.displayName; } +/** + * Gets a filename-safe representation of the API item's display name. + */ +export function getFileSafeNameForApiItem(apiItem: ApiItem): string { + return apiItem.kind === ApiItemKind.Package + ? getSafeFilenameForName(getUnscopedPackageName(apiItem as ApiPackage)) + : getSafeFilenameForName(apiItem.displayName); +} + /** * Converts bad filename characters to underscores. */ -export function getSafeFilenameForName(apiItemName: string): string { +function getSafeFilenameForName(apiItemName: string): string { // eslint-disable-next-line unicorn/better-regex, no-useless-escape const badFilenameCharsRegExp: RegExp = /[^a-z0-9_\-\.]/gi; diff --git a/tools/api-markdown-documenter/src/utilities/TypeUtilities.ts b/tools/api-markdown-documenter/src/utilities/TypeUtilities.ts index 93eb903662ce..65ec24bc4ed0 100644 --- a/tools/api-markdown-documenter/src/utilities/TypeUtilities.ts +++ b/tools/api-markdown-documenter/src/utilities/TypeUtilities.ts @@ -4,8 +4,21 @@ */ /** - * Recursive variant of the `Required` utility type. + * Represents a value that can be either a direct value of type `T` or a function that returns a value of type `T` given some parameters. */ -export type DeepRequired = { - [K in keyof T]: DeepRequired; -} & Required; +// eslint-disable-next-line @typescript-eslint/no-explicit-any +export type ValueOrDerived = T | ((..._arguments: TArguments) => T); + +/** + * Returns the value of a `ValueOrDerived` object, either by directly returning the value or by calling the function with the provided arguments. + */ +// eslint-disable-next-line @typescript-eslint/no-explicit-any +export function getValueOrDerived( + valueOrDerived: ValueOrDerived, + ..._arguments: TArguments +): T { + if (typeof valueOrDerived === "function") { + return (valueOrDerived as (..._arguments: TArguments) => T)(..._arguments); + } + return valueOrDerived; +} From a67cf98e8f8d54f167cea86a74febbafcd0df754 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 18 Dec 2024 00:13:25 +0000 Subject: [PATCH 07/54] More WIP --- .../api-markdown-documenter.alpha.api.md | 167 ++++++++---- .../api-markdown-documenter.beta.api.md | 169 ++++++++---- .../api-markdown-documenter.public.api.md | 169 ++++++++---- .../src/ApiItemUtilitiesModule.ts | 2 +- .../src/ConfigurationBase.ts | 2 + .../src/FileSystemConfiguration.ts | 2 +- .../api-markdown-documenter/src/RenderHtml.ts | 27 +- .../src/RenderMarkdown.ts | 23 +- .../ApiItemTransformUtilities.ts | 258 +++++++----------- .../api-item-transforms/TransformApiItem.ts | 6 +- .../api-item-transforms/TransformApiModel.ts | 29 +- .../src/api-item-transforms/Utilities.ts | 10 +- .../configuration/Configuration.ts | 46 +++- .../DocumentationSuiteOptions.ts | 37 ++- .../configuration/HierarchyOptions.ts | 82 ++---- ...formationOptions.ts => Transformations.ts} | 46 ++-- .../configuration/index.ts | 13 +- .../CreateDefaultLayout.ts | 2 +- .../TransformApiClass.ts | 2 +- .../TransformApiInterface.ts | 2 +- .../TransformApiModuleLike.ts | 2 +- .../api-item-transforms/helpers/Helpers.ts | 52 ++-- .../src/api-item-transforms/index.ts | 7 +- .../test/Transformation.test.ts | 7 +- tools/api-markdown-documenter/src/index.ts | 25 +- .../src/test/EndToEndTests.ts | 160 ++++++----- .../src/test/HtmlEndToEnd.test.ts | 2 +- .../src/utilities/ApiItemUtilities.ts | 17 +- 28 files changed, 763 insertions(+), 603 deletions(-) rename tools/api-markdown-documenter/src/api-item-transforms/configuration/{TransformationOptions.ts => Transformations.ts} (77%) 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 555dc21496da..7cd5ff932b72 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 @@ -48,43 +48,53 @@ export { ApiItem } export { ApiItemKind } // @public -export interface ApiItemTransformationConfiguration extends ApiItemTransformationOptions, DocumentationSuiteOptions, ConfigurationBase { - apiModel: ApiModel; +export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, Required, DocumentationSuiteConfiguration, Required { +} + +// @public +export interface ApiItemTransformationConfigurationBase { + readonly apiModel: ApiModel; readonly uriRoot: string; } // @public -export interface ApiItemTransformationOptions { - createDefaultLayout?: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: Required) => SectionNode[]; - transformApiCallSignature?: TransformApiItemWithoutChildren; - transformApiClass?: TransformApiItemWithChildren; - transformApiConstructor?: TransformApiItemWithoutChildren; - transformApiEntryPoint?: TransformApiItemWithChildren; - transformApiEnum?: TransformApiItemWithChildren; - transformApiEnumMember?: TransformApiItemWithoutChildren; - transformApiFunction?: TransformApiItemWithoutChildren; - transformApiIndexSignature?: TransformApiItemWithoutChildren; - transformApiInterface?: TransformApiItemWithChildren; - transformApiMethod?: TransformApiItemWithoutChildren; - transformApiModel?: TransformApiItemWithoutChildren; - transformApiNamespace?: TransformApiItemWithChildren; - transformApiProperty?: TransformApiItemWithoutChildren; - transformApiTypeAlias?: TransformApiItemWithoutChildren; - transformApiVariable?: TransformApiItemWithoutChildren; +export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, ApiItemTransformations, DocumentationSuiteOptions, ConfigurationBase { +} + +// @public +export interface ApiItemTransformations { + readonly createDefaultLayout?: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: Required) => SectionNode[]; + readonly transformApiCallSignature?: TransformApiItemWithoutChildren; + readonly transformApiClass?: TransformApiItemWithChildren; + readonly transformApiConstructor?: TransformApiItemWithoutChildren; + readonly transformApiEntryPoint?: TransformApiItemWithChildren; + readonly transformApiEnum?: TransformApiItemWithChildren; + readonly transformApiEnumMember?: TransformApiItemWithoutChildren; + readonly transformApiFunction?: TransformApiItemWithoutChildren; + readonly transformApiIndexSignature?: TransformApiItemWithoutChildren; + readonly transformApiInterface?: TransformApiItemWithChildren; + readonly transformApiMethod?: TransformApiItemWithoutChildren; + readonly transformApiModel?: TransformApiItemWithoutChildren; + readonly transformApiNamespace?: TransformApiItemWithChildren; + readonly transformApiProperty?: TransformApiItemWithoutChildren; + readonly transformApiTypeAlias?: TransformApiItemWithoutChildren; + readonly transformApiVariable?: TransformApiItemWithoutChildren; } declare namespace ApiItemUtilities { export { - doesItemRequireOwnDocument, + doesItemKindRequireOwnDocument, filterItems, getHeadingForApiItem, getLinkForApiItem, shouldItemBeIncluded, ancestryHasModifierTag, + getApiItemKind, getCustomBlockComments, getDefaultValueBlock, getDeprecatedBlock, getExampleBlocks, + getFileSafeNameForApiItem, getModifiers, getModifierTags, getQualifiedApiItemName, @@ -104,7 +114,7 @@ declare namespace ApiItemUtilities { export { ApiItemUtilities } // @public -export type ApiMemberKind = Omit; +export type ApiMemberKind = Exclude; export { ApiModel } @@ -149,7 +159,7 @@ export interface ConfigurationBase { } // @public -function createBreadcrumbParagraph(apiItem: ApiItem, config: Required): ParagraphNode; +function createBreadcrumbParagraph(apiItem: ApiItem, config: ApiItemTransformationConfiguration): ParagraphNode; // @public function createDeprecationNoticeSection(apiItem: ApiItem, config: Required): ParagraphNode | undefined; @@ -186,11 +196,7 @@ export const defaultConsoleLogger: Logger; // @public export namespace DefaultDocumentationSuiteOptions { - const defaultDocumentBoundaries: ApiMemberKind[]; - const defaultHierarchyBoundaries: ApiMemberKind[]; export function defaultGetAlertsForItem(apiItem: ApiItem): string[]; - export function defaultGetFileNameForItem(apiItem: ApiItem): string; - export function defaultGetHeadingTextForItem(apiItem: ApiItem): string; export function defaultGetLinkTextForItem(apiItem: ApiItem): string; export function defaultGetUriBaseOverrideForItem(): string | undefined; export function defaultSkipPackage(): boolean; @@ -278,23 +284,31 @@ export abstract class DocumentationParentNodeBase, "hierarchy"> & { + readonly hierarchy: Required; +}; + // @public export interface DocumentationSuiteOptions { - documentBoundaries?: DocumentBoundaries; - getAlertsForItem?: (apiItem: ApiItem) => string[]; - getFileNameForItem?: (apiItem: ApiItem) => string; - getHeadingTextForItem?: (apiItem: ApiItem) => string; - getLinkTextForItem?: (apiItem: ApiItem) => string; - getUriBaseOverrideForItem?: (apiItem: ApiItem) => string | undefined; - hierarchyBoundaries?: HierarchyBoundaries; - includeBreadcrumb?: boolean; - includeTopLevelDocumentHeading?: boolean; - minimumReleaseLevel?: Omit; - skipPackage?: (apiPackage: ApiPackage) => boolean; + readonly getAlertsForItem?: (apiItem: ApiItem) => string[]; + readonly getLinkTextForItem?: (apiItem: ApiItem) => string; + readonly getUriBaseOverrideForItem?: (apiItem: ApiItem) => string | undefined; + readonly hierarchy?: Partial; + readonly includeBreadcrumb?: boolean; + readonly includeTopLevelDocumentHeading?: boolean; + readonly minimumReleaseLevel?: Exclude; + readonly skipPackage?: (apiPackage: ApiPackage) => boolean; } // @public -export type DocumentBoundaries = ApiMemberKind[]; +export interface DocumentHierarchyConfig extends HierarchyConfigBase, DocumentHierarchyOptions { +} + +// @public +export interface DocumentHierarchyOptions extends SectionHierarchyOptions { + readonly documentName: string | ((apiItem: ApiItem) => string); +} // @public export class DocumentNode implements Parent, DocumentNodeProps { @@ -334,7 +348,7 @@ export namespace DocumentWriter { } // @public -function doesItemRequireOwnDocument(apiItem: ApiItem, documentBoundaries: DocumentBoundaries): boolean; +function doesItemKindRequireOwnDocument(apiItemKind: ValidApiItemKind, hierarchyConfig: Required): boolean; // @public export class FencedCodeBlockNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { @@ -348,14 +362,33 @@ export class FencedCodeBlockNode extends DocumentationParentNodeBase implements // @public export interface FileSystemConfiguration { readonly newlineKind?: NewlineKind; - outputDirectoryPath: string; + readonly outputDirectoryPath: string; } // @public function filterItems(apiItems: readonly ApiItem[], config: Required): ApiItem[]; // @public -export function getApiItemTransformationConfigurationWithDefaults(inputOptions: ApiItemTransformationConfiguration): Required; +export enum FolderDocumentPlacement { + Inside = "inside", + Outside = "outside" +} + +// @public +export interface FolderHierarchyConfig extends HierarchyConfigBase, FolderHierarchyOptions { +} + +// @public +export interface FolderHierarchyOptions extends DocumentHierarchyOptions { + readonly documentPlacement: FolderDocumentPlacement | ((apiItem: ApiItem) => FolderDocumentPlacement); + readonly folderName: string | ((apiItem: ApiItem) => string); +} + +// @public +function getApiItemKind(apiItem: ApiItem): ValidApiItemKind; + +// @public +export function getApiItemTransformationConfigurationWithDefaults(inputOptions: ApiItemTransformationOptions): Required; // @public function getCustomBlockComments(apiItem: ApiItem): ReadonlyMap; @@ -370,10 +403,13 @@ function getDeprecatedBlock(apiItem: ApiItem): DocSection | undefined; function getExampleBlocks(apiItem: ApiItem): readonly DocSection[] | undefined; // @public -function getHeadingForApiItem(apiItem: ApiItem, config: Required, headingLevel?: number): Heading; +function getFileSafeNameForApiItem(apiItem: ApiItem): string; + +// @public +function getHeadingForApiItem(apiItem: ApiItem, config: ApiItemTransformationConfiguration, headingLevel?: number): Heading; // @public -function getLinkForApiItem(apiItem: ApiItem, config: Required, textOverride?: string): Link; +function getLinkForApiItem(apiItem: ApiItem, config: ApiItemTransformationConfiguration, textOverride?: string): Link; // @public function getModifiers(apiItem: ApiItem, modifiersToOmit?: ApiModifier[]): ApiModifier[]; @@ -423,7 +459,28 @@ export class HeadingNode extends DocumentationParentNodeBase { + readonly kind: THierarchyKind; +} + +// @public +export enum HierarchyKind { + Document = "document", + Folder = "folder", + Section = "section" +} + +// @public +export type HierarchyOptions = { + [Kind in Exclude]: HierarchyConfig; +} & { + [ApiItemKind.Model]: DocumentHierarchyConfig; + [ApiItemKind.Package]: FolderHierarchyConfig; + [ApiItemKind.EntryPoint]: SectionHierarchyConfig; +}; // @public export class HorizontalRuleNode implements MultiLineDocumentationNode { @@ -619,15 +676,15 @@ export { ReleaseTag } // @alpha function renderApiModelAsHtml(options: RenderApiModelAsHtmlOptions): Promise; -// @public -interface RenderApiModelAsHtmlOptions extends ApiItemTransformationConfiguration, RenderDocumentAsHtmlConfig, FileSystemConfiguration { +// @alpha +interface RenderApiModelAsHtmlOptions extends ApiItemTransformationOptions, RenderDocumentAsHtmlConfig, FileSystemConfiguration { } // @public function renderApiModelAsMarkdown(options: RenderApiModelAsMarkdownOptions): Promise; // @public -interface RenderApiModelAsMarkdownOptions extends ApiItemTransformationConfiguration, MarkdownRenderConfiguration, FileSystemConfiguration { +interface RenderApiModelAsMarkdownOptions extends ApiItemTransformationOptions, MarkdownRenderConfiguration, FileSystemConfiguration { } // @public @@ -643,7 +700,7 @@ export interface RenderDocumentAsHtmlConfig extends ToHtmlConfig, RenderHtmlConf // @alpha function renderDocumentsAsHtml(documents: DocumentNode[], options: RenderDocumentsAsHtmlOptions): Promise; -// @public +// @alpha interface RenderDocumentsAsHtmlOptions extends RenderDocumentAsHtmlConfig, FileSystemConfiguration { } @@ -670,6 +727,15 @@ function renderNode(node: DocumentationNode, writer: DocumentWriter, context: Ma // @public function renderNodes(children: DocumentationNode[], writer: DocumentWriter, childContext: MarkdownRenderContext): void; +// @public +export interface SectionHierarchyConfig extends HierarchyConfigBase, SectionHierarchyOptions { +} + +// @public +export interface SectionHierarchyOptions { + readonly headingText: string | ((apiItem: ApiItem) => string); +} + // @public export class SectionNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { constructor(children: DocumentationNode[], heading?: HeadingNode); @@ -802,7 +868,7 @@ export type TransformApiItemWithChildren = (apiItem: T export type TransformApiItemWithoutChildren = (apiItem: TApiItem, config: Required) => SectionNode[]; // @public -export function transformApiModel(transformConfig: ApiItemTransformationConfiguration): DocumentNode[]; +export function transformApiModel(transformConfig: ApiItemTransformationOptions): DocumentNode[]; // @public export function transformTsdocNode(node: DocNode, contextApiItem: ApiItem, config: Required): DocumentationNode | undefined; @@ -819,6 +885,9 @@ export class UnorderedListNode extends DocumentationParentNodeBase; + // @public export const verboseConsoleLogger: Logger; 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 7437331deb24..f6bc06b9094a 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 @@ -48,43 +48,53 @@ export { ApiItem } export { ApiItemKind } // @public -export interface ApiItemTransformationConfiguration extends ApiItemTransformationOptions, DocumentationSuiteOptions, ConfigurationBase { - apiModel: ApiModel; +export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, Required, DocumentationSuiteConfiguration, Required { +} + +// @public +export interface ApiItemTransformationConfigurationBase { + readonly apiModel: ApiModel; readonly uriRoot: string; } // @public -export interface ApiItemTransformationOptions { - createDefaultLayout?: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: Required) => SectionNode[]; - transformApiCallSignature?: TransformApiItemWithoutChildren; - transformApiClass?: TransformApiItemWithChildren; - transformApiConstructor?: TransformApiItemWithoutChildren; - transformApiEntryPoint?: TransformApiItemWithChildren; - transformApiEnum?: TransformApiItemWithChildren; - transformApiEnumMember?: TransformApiItemWithoutChildren; - transformApiFunction?: TransformApiItemWithoutChildren; - transformApiIndexSignature?: TransformApiItemWithoutChildren; - transformApiInterface?: TransformApiItemWithChildren; - transformApiMethod?: TransformApiItemWithoutChildren; - transformApiModel?: TransformApiItemWithoutChildren; - transformApiNamespace?: TransformApiItemWithChildren; - transformApiProperty?: TransformApiItemWithoutChildren; - transformApiTypeAlias?: TransformApiItemWithoutChildren; - transformApiVariable?: TransformApiItemWithoutChildren; +export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, ApiItemTransformations, DocumentationSuiteOptions, ConfigurationBase { +} + +// @public +export interface ApiItemTransformations { + readonly createDefaultLayout?: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: Required) => SectionNode[]; + readonly transformApiCallSignature?: TransformApiItemWithoutChildren; + readonly transformApiClass?: TransformApiItemWithChildren; + readonly transformApiConstructor?: TransformApiItemWithoutChildren; + readonly transformApiEntryPoint?: TransformApiItemWithChildren; + readonly transformApiEnum?: TransformApiItemWithChildren; + readonly transformApiEnumMember?: TransformApiItemWithoutChildren; + readonly transformApiFunction?: TransformApiItemWithoutChildren; + readonly transformApiIndexSignature?: TransformApiItemWithoutChildren; + readonly transformApiInterface?: TransformApiItemWithChildren; + readonly transformApiMethod?: TransformApiItemWithoutChildren; + readonly transformApiModel?: TransformApiItemWithoutChildren; + readonly transformApiNamespace?: TransformApiItemWithChildren; + readonly transformApiProperty?: TransformApiItemWithoutChildren; + readonly transformApiTypeAlias?: TransformApiItemWithoutChildren; + readonly transformApiVariable?: TransformApiItemWithoutChildren; } declare namespace ApiItemUtilities { export { - doesItemRequireOwnDocument, + doesItemKindRequireOwnDocument, filterItems, getHeadingForApiItem, getLinkForApiItem, shouldItemBeIncluded, ancestryHasModifierTag, + getApiItemKind, getCustomBlockComments, getDefaultValueBlock, getDeprecatedBlock, getExampleBlocks, + getFileSafeNameForApiItem, getModifiers, getModifierTags, getQualifiedApiItemName, @@ -104,7 +114,7 @@ declare namespace ApiItemUtilities { export { ApiItemUtilities } // @public -export type ApiMemberKind = Omit; +export type ApiMemberKind = Exclude; export { ApiModel } @@ -149,7 +159,7 @@ export interface ConfigurationBase { } // @public -function createBreadcrumbParagraph(apiItem: ApiItem, config: Required): ParagraphNode; +function createBreadcrumbParagraph(apiItem: ApiItem, config: ApiItemTransformationConfiguration): ParagraphNode; // @public function createDeprecationNoticeSection(apiItem: ApiItem, config: Required): ParagraphNode | undefined; @@ -186,11 +196,7 @@ export const defaultConsoleLogger: Logger; // @public export namespace DefaultDocumentationSuiteOptions { - const defaultDocumentBoundaries: ApiMemberKind[]; - const defaultHierarchyBoundaries: ApiMemberKind[]; export function defaultGetAlertsForItem(apiItem: ApiItem): string[]; - export function defaultGetFileNameForItem(apiItem: ApiItem): string; - export function defaultGetHeadingTextForItem(apiItem: ApiItem): string; export function defaultGetLinkTextForItem(apiItem: ApiItem): string; export function defaultGetUriBaseOverrideForItem(): string | undefined; export function defaultSkipPackage(): boolean; @@ -278,23 +284,31 @@ export abstract class DocumentationParentNodeBase, "hierarchy"> & { + readonly hierarchy: Required; +}; + // @public export interface DocumentationSuiteOptions { - documentBoundaries?: DocumentBoundaries; - getAlertsForItem?: (apiItem: ApiItem) => string[]; - getFileNameForItem?: (apiItem: ApiItem) => string; - getHeadingTextForItem?: (apiItem: ApiItem) => string; - getLinkTextForItem?: (apiItem: ApiItem) => string; - getUriBaseOverrideForItem?: (apiItem: ApiItem) => string | undefined; - hierarchyBoundaries?: HierarchyBoundaries; - includeBreadcrumb?: boolean; - includeTopLevelDocumentHeading?: boolean; - minimumReleaseLevel?: Omit; - skipPackage?: (apiPackage: ApiPackage) => boolean; + readonly getAlertsForItem?: (apiItem: ApiItem) => string[]; + readonly getLinkTextForItem?: (apiItem: ApiItem) => string; + readonly getUriBaseOverrideForItem?: (apiItem: ApiItem) => string | undefined; + readonly hierarchy?: Partial; + readonly includeBreadcrumb?: boolean; + readonly includeTopLevelDocumentHeading?: boolean; + readonly minimumReleaseLevel?: Exclude; + readonly skipPackage?: (apiPackage: ApiPackage) => boolean; +} + +// @public +export interface DocumentHierarchyConfig extends HierarchyConfigBase, DocumentHierarchyOptions { } // @public -export type DocumentBoundaries = ApiMemberKind[]; +export interface DocumentHierarchyOptions extends SectionHierarchyOptions { + readonly documentName: string | ((apiItem: ApiItem) => string); +} // @public export class DocumentNode implements Parent, DocumentNodeProps { @@ -334,7 +348,7 @@ export namespace DocumentWriter { } // @public -function doesItemRequireOwnDocument(apiItem: ApiItem, documentBoundaries: DocumentBoundaries): boolean; +function doesItemKindRequireOwnDocument(apiItemKind: ValidApiItemKind, hierarchyConfig: Required): boolean; // @public export class FencedCodeBlockNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { @@ -348,14 +362,33 @@ export class FencedCodeBlockNode extends DocumentationParentNodeBase implements // @public export interface FileSystemConfiguration { readonly newlineKind?: NewlineKind; - outputDirectoryPath: string; + readonly outputDirectoryPath: string; } // @public function filterItems(apiItems: readonly ApiItem[], config: Required): ApiItem[]; // @public -export function getApiItemTransformationConfigurationWithDefaults(inputOptions: ApiItemTransformationConfiguration): Required; +export enum FolderDocumentPlacement { + Inside = "inside", + Outside = "outside" +} + +// @public +export interface FolderHierarchyConfig extends HierarchyConfigBase, FolderHierarchyOptions { +} + +// @public +export interface FolderHierarchyOptions extends DocumentHierarchyOptions { + readonly documentPlacement: FolderDocumentPlacement | ((apiItem: ApiItem) => FolderDocumentPlacement); + readonly folderName: string | ((apiItem: ApiItem) => string); +} + +// @public +function getApiItemKind(apiItem: ApiItem): ValidApiItemKind; + +// @public +export function getApiItemTransformationConfigurationWithDefaults(inputOptions: ApiItemTransformationOptions): Required; // @public function getCustomBlockComments(apiItem: ApiItem): ReadonlyMap; @@ -370,10 +403,13 @@ function getDeprecatedBlock(apiItem: ApiItem): DocSection | undefined; function getExampleBlocks(apiItem: ApiItem): readonly DocSection[] | undefined; // @public -function getHeadingForApiItem(apiItem: ApiItem, config: Required, headingLevel?: number): Heading; +function getFileSafeNameForApiItem(apiItem: ApiItem): string; // @public -function getLinkForApiItem(apiItem: ApiItem, config: Required, textOverride?: string): Link; +function getHeadingForApiItem(apiItem: ApiItem, config: ApiItemTransformationConfiguration, headingLevel?: number): Heading; + +// @public +function getLinkForApiItem(apiItem: ApiItem, config: ApiItemTransformationConfiguration, textOverride?: string): Link; // @public function getModifiers(apiItem: ApiItem, modifiersToOmit?: ApiModifier[]): ApiModifier[]; @@ -423,7 +459,28 @@ export class HeadingNode extends DocumentationParentNodeBase { + readonly kind: THierarchyKind; +} + +// @public +export enum HierarchyKind { + Document = "document", + Folder = "folder", + Section = "section" +} + +// @public +export type HierarchyOptions = { + [Kind in Exclude]: HierarchyConfig; +} & { + [ApiItemKind.Model]: DocumentHierarchyConfig; + [ApiItemKind.Package]: FolderHierarchyConfig; + [ApiItemKind.EntryPoint]: SectionHierarchyConfig; +}; // @public export class HorizontalRuleNode implements MultiLineDocumentationNode { @@ -616,15 +673,11 @@ export class PlainTextNode extends DocumentationLiteralNodeBase implemen export { ReleaseTag } -// @public -interface RenderApiModelAsHtmlOptions extends ApiItemTransformationConfiguration, RenderDocumentAsHtmlConfig, FileSystemConfiguration { -} - // @public function renderApiModelAsMarkdown(options: RenderApiModelAsMarkdownOptions): Promise; // @public -interface RenderApiModelAsMarkdownOptions extends ApiItemTransformationConfiguration, MarkdownRenderConfiguration, FileSystemConfiguration { +interface RenderApiModelAsMarkdownOptions extends ApiItemTransformationOptions, MarkdownRenderConfiguration, FileSystemConfiguration { } // @public @@ -637,10 +690,6 @@ function renderDocument_2(document: DocumentNode, config: MarkdownRenderConfigur export interface RenderDocumentAsHtmlConfig extends ToHtmlConfig, RenderHtmlConfig { } -// @public -interface RenderDocumentsAsHtmlOptions extends RenderDocumentAsHtmlConfig, FileSystemConfiguration { -} - // @public function renderDocumentsAsMarkdown(documents: DocumentNode[], options: RenderDocumentsAsMarkdownOptions): Promise; @@ -664,6 +713,15 @@ function renderNode(node: DocumentationNode, writer: DocumentWriter, context: Ma // @public function renderNodes(children: DocumentationNode[], writer: DocumentWriter, childContext: MarkdownRenderContext): void; +// @public +export interface SectionHierarchyConfig extends HierarchyConfigBase, SectionHierarchyOptions { +} + +// @public +export interface SectionHierarchyOptions { + readonly headingText: string | ((apiItem: ApiItem) => string); +} + // @public export class SectionNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { constructor(children: DocumentationNode[], heading?: HeadingNode); @@ -796,7 +854,7 @@ export type TransformApiItemWithChildren = (apiItem: T export type TransformApiItemWithoutChildren = (apiItem: TApiItem, config: Required) => SectionNode[]; // @public -export function transformApiModel(transformConfig: ApiItemTransformationConfiguration): DocumentNode[]; +export function transformApiModel(transformConfig: ApiItemTransformationOptions): DocumentNode[]; // @public export function transformTsdocNode(node: DocNode, contextApiItem: ApiItem, config: Required): DocumentationNode | undefined; @@ -813,6 +871,9 @@ export class UnorderedListNode extends DocumentationParentNodeBase; + // @public export const verboseConsoleLogger: Logger; 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 fe1ac0a43dd3..180a0bf37422 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 @@ -48,43 +48,53 @@ export { ApiItem } export { ApiItemKind } // @public -export interface ApiItemTransformationConfiguration extends ApiItemTransformationOptions, DocumentationSuiteOptions, ConfigurationBase { - apiModel: ApiModel; +export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, Required, DocumentationSuiteConfiguration, Required { +} + +// @public +export interface ApiItemTransformationConfigurationBase { + readonly apiModel: ApiModel; readonly uriRoot: string; } // @public -export interface ApiItemTransformationOptions { - createDefaultLayout?: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: Required) => SectionNode[]; - transformApiCallSignature?: TransformApiItemWithoutChildren; - transformApiClass?: TransformApiItemWithChildren; - transformApiConstructor?: TransformApiItemWithoutChildren; - transformApiEntryPoint?: TransformApiItemWithChildren; - transformApiEnum?: TransformApiItemWithChildren; - transformApiEnumMember?: TransformApiItemWithoutChildren; - transformApiFunction?: TransformApiItemWithoutChildren; - transformApiIndexSignature?: TransformApiItemWithoutChildren; - transformApiInterface?: TransformApiItemWithChildren; - transformApiMethod?: TransformApiItemWithoutChildren; - transformApiModel?: TransformApiItemWithoutChildren; - transformApiNamespace?: TransformApiItemWithChildren; - transformApiProperty?: TransformApiItemWithoutChildren; - transformApiTypeAlias?: TransformApiItemWithoutChildren; - transformApiVariable?: TransformApiItemWithoutChildren; +export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, ApiItemTransformations, DocumentationSuiteOptions, ConfigurationBase { +} + +// @public +export interface ApiItemTransformations { + readonly createDefaultLayout?: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: Required) => SectionNode[]; + readonly transformApiCallSignature?: TransformApiItemWithoutChildren; + readonly transformApiClass?: TransformApiItemWithChildren; + readonly transformApiConstructor?: TransformApiItemWithoutChildren; + readonly transformApiEntryPoint?: TransformApiItemWithChildren; + readonly transformApiEnum?: TransformApiItemWithChildren; + readonly transformApiEnumMember?: TransformApiItemWithoutChildren; + readonly transformApiFunction?: TransformApiItemWithoutChildren; + readonly transformApiIndexSignature?: TransformApiItemWithoutChildren; + readonly transformApiInterface?: TransformApiItemWithChildren; + readonly transformApiMethod?: TransformApiItemWithoutChildren; + readonly transformApiModel?: TransformApiItemWithoutChildren; + readonly transformApiNamespace?: TransformApiItemWithChildren; + readonly transformApiProperty?: TransformApiItemWithoutChildren; + readonly transformApiTypeAlias?: TransformApiItemWithoutChildren; + readonly transformApiVariable?: TransformApiItemWithoutChildren; } declare namespace ApiItemUtilities { export { - doesItemRequireOwnDocument, + doesItemKindRequireOwnDocument, filterItems, getHeadingForApiItem, getLinkForApiItem, shouldItemBeIncluded, ancestryHasModifierTag, + getApiItemKind, getCustomBlockComments, getDefaultValueBlock, getDeprecatedBlock, getExampleBlocks, + getFileSafeNameForApiItem, getModifiers, getModifierTags, getQualifiedApiItemName, @@ -104,7 +114,7 @@ declare namespace ApiItemUtilities { export { ApiItemUtilities } // @public -export type ApiMemberKind = Omit; +export type ApiMemberKind = Exclude; export { ApiModel } @@ -149,7 +159,7 @@ export interface ConfigurationBase { } // @public -function createBreadcrumbParagraph(apiItem: ApiItem, config: Required): ParagraphNode; +function createBreadcrumbParagraph(apiItem: ApiItem, config: ApiItemTransformationConfiguration): ParagraphNode; // @public function createDeprecationNoticeSection(apiItem: ApiItem, config: Required): ParagraphNode | undefined; @@ -186,11 +196,7 @@ export const defaultConsoleLogger: Logger; // @public export namespace DefaultDocumentationSuiteOptions { - const defaultDocumentBoundaries: ApiMemberKind[]; - const defaultHierarchyBoundaries: ApiMemberKind[]; export function defaultGetAlertsForItem(apiItem: ApiItem): string[]; - export function defaultGetFileNameForItem(apiItem: ApiItem): string; - export function defaultGetHeadingTextForItem(apiItem: ApiItem): string; export function defaultGetLinkTextForItem(apiItem: ApiItem): string; export function defaultGetUriBaseOverrideForItem(): string | undefined; export function defaultSkipPackage(): boolean; @@ -278,23 +284,31 @@ export abstract class DocumentationParentNodeBase, "hierarchy"> & { + readonly hierarchy: Required; +}; + // @public export interface DocumentationSuiteOptions { - documentBoundaries?: DocumentBoundaries; - getAlertsForItem?: (apiItem: ApiItem) => string[]; - getFileNameForItem?: (apiItem: ApiItem) => string; - getHeadingTextForItem?: (apiItem: ApiItem) => string; - getLinkTextForItem?: (apiItem: ApiItem) => string; - getUriBaseOverrideForItem?: (apiItem: ApiItem) => string | undefined; - hierarchyBoundaries?: HierarchyBoundaries; - includeBreadcrumb?: boolean; - includeTopLevelDocumentHeading?: boolean; - minimumReleaseLevel?: Omit; - skipPackage?: (apiPackage: ApiPackage) => boolean; + readonly getAlertsForItem?: (apiItem: ApiItem) => string[]; + readonly getLinkTextForItem?: (apiItem: ApiItem) => string; + readonly getUriBaseOverrideForItem?: (apiItem: ApiItem) => string | undefined; + readonly hierarchy?: Partial; + readonly includeBreadcrumb?: boolean; + readonly includeTopLevelDocumentHeading?: boolean; + readonly minimumReleaseLevel?: Exclude; + readonly skipPackage?: (apiPackage: ApiPackage) => boolean; +} + +// @public +export interface DocumentHierarchyConfig extends HierarchyConfigBase, DocumentHierarchyOptions { } // @public -export type DocumentBoundaries = ApiMemberKind[]; +export interface DocumentHierarchyOptions extends SectionHierarchyOptions { + readonly documentName: string | ((apiItem: ApiItem) => string); +} // @public export class DocumentNode implements Parent, DocumentNodeProps { @@ -334,7 +348,7 @@ export namespace DocumentWriter { } // @public -function doesItemRequireOwnDocument(apiItem: ApiItem, documentBoundaries: DocumentBoundaries): boolean; +function doesItemKindRequireOwnDocument(apiItemKind: ValidApiItemKind, hierarchyConfig: Required): boolean; // @public export class FencedCodeBlockNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { @@ -348,14 +362,33 @@ export class FencedCodeBlockNode extends DocumentationParentNodeBase implements // @public export interface FileSystemConfiguration { readonly newlineKind?: NewlineKind; - outputDirectoryPath: string; + readonly outputDirectoryPath: string; } // @public function filterItems(apiItems: readonly ApiItem[], config: Required): ApiItem[]; // @public -export function getApiItemTransformationConfigurationWithDefaults(inputOptions: ApiItemTransformationConfiguration): Required; +export enum FolderDocumentPlacement { + Inside = "inside", + Outside = "outside" +} + +// @public +export interface FolderHierarchyConfig extends HierarchyConfigBase, FolderHierarchyOptions { +} + +// @public +export interface FolderHierarchyOptions extends DocumentHierarchyOptions { + readonly documentPlacement: FolderDocumentPlacement | ((apiItem: ApiItem) => FolderDocumentPlacement); + readonly folderName: string | ((apiItem: ApiItem) => string); +} + +// @public +function getApiItemKind(apiItem: ApiItem): ValidApiItemKind; + +// @public +export function getApiItemTransformationConfigurationWithDefaults(inputOptions: ApiItemTransformationOptions): Required; // @public function getCustomBlockComments(apiItem: ApiItem): ReadonlyMap; @@ -370,10 +403,13 @@ function getDeprecatedBlock(apiItem: ApiItem): DocSection | undefined; function getExampleBlocks(apiItem: ApiItem): readonly DocSection[] | undefined; // @public -function getHeadingForApiItem(apiItem: ApiItem, config: Required, headingLevel?: number): Heading; +function getFileSafeNameForApiItem(apiItem: ApiItem): string; // @public -function getLinkForApiItem(apiItem: ApiItem, config: Required, textOverride?: string): Link; +function getHeadingForApiItem(apiItem: ApiItem, config: ApiItemTransformationConfiguration, headingLevel?: number): Heading; + +// @public +function getLinkForApiItem(apiItem: ApiItem, config: ApiItemTransformationConfiguration, textOverride?: string): Link; // @public function getModifiers(apiItem: ApiItem, modifiersToOmit?: ApiModifier[]): ApiModifier[]; @@ -423,7 +459,28 @@ export class HeadingNode extends DocumentationParentNodeBase { + readonly kind: THierarchyKind; +} + +// @public +export enum HierarchyKind { + Document = "document", + Folder = "folder", + Section = "section" +} + +// @public +export type HierarchyOptions = { + [Kind in Exclude]: HierarchyConfig; +} & { + [ApiItemKind.Model]: DocumentHierarchyConfig; + [ApiItemKind.Package]: FolderHierarchyConfig; + [ApiItemKind.EntryPoint]: SectionHierarchyConfig; +}; // @public export class HorizontalRuleNode implements MultiLineDocumentationNode { @@ -594,15 +651,11 @@ export class PlainTextNode extends DocumentationLiteralNodeBase implemen export { ReleaseTag } -// @public -interface RenderApiModelAsHtmlOptions extends ApiItemTransformationConfiguration, RenderDocumentAsHtmlConfig, FileSystemConfiguration { -} - // @public function renderApiModelAsMarkdown(options: RenderApiModelAsMarkdownOptions): Promise; // @public -interface RenderApiModelAsMarkdownOptions extends ApiItemTransformationConfiguration, MarkdownRenderConfiguration, FileSystemConfiguration { +interface RenderApiModelAsMarkdownOptions extends ApiItemTransformationOptions, MarkdownRenderConfiguration, FileSystemConfiguration { } // @public @@ -615,10 +668,6 @@ function renderDocument_2(document: DocumentNode, config: MarkdownRenderConfigur export interface RenderDocumentAsHtmlConfig extends ToHtmlConfig, RenderHtmlConfig { } -// @public -interface RenderDocumentsAsHtmlOptions extends RenderDocumentAsHtmlConfig, FileSystemConfiguration { -} - // @public function renderDocumentsAsMarkdown(documents: DocumentNode[], options: RenderDocumentsAsMarkdownOptions): Promise; @@ -642,6 +691,15 @@ function renderNode(node: DocumentationNode, writer: DocumentWriter, context: Ma // @public function renderNodes(children: DocumentationNode[], writer: DocumentWriter, childContext: MarkdownRenderContext): void; +// @public +export interface SectionHierarchyConfig extends HierarchyConfigBase, SectionHierarchyOptions { +} + +// @public +export interface SectionHierarchyOptions { + readonly headingText: string | ((apiItem: ApiItem) => string); +} + // @public export class SectionNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { constructor(children: DocumentationNode[], heading?: HeadingNode); @@ -774,7 +832,7 @@ export type TransformApiItemWithChildren = (apiItem: T export type TransformApiItemWithoutChildren = (apiItem: TApiItem, config: Required) => SectionNode[]; // @public -export function transformApiModel(transformConfig: ApiItemTransformationConfiguration): DocumentNode[]; +export function transformApiModel(transformConfig: ApiItemTransformationOptions): DocumentNode[]; // @public export function transformTsdocNode(node: DocNode, contextApiItem: ApiItem, config: Required): DocumentationNode | undefined; @@ -791,6 +849,9 @@ export class UnorderedListNode extends DocumentationParentNodeBase; + // @public export const verboseConsoleLogger: Logger; diff --git a/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts b/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts index 3fc7053aea85..c9b06039218d 100644 --- a/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts +++ b/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts @@ -8,7 +8,7 @@ */ export { - doesItemRequireOwnDocument, + doesItemKindRequireOwnDocument, filterItems, getHeadingForApiItem, getLinkForApiItem, diff --git a/tools/api-markdown-documenter/src/ConfigurationBase.ts b/tools/api-markdown-documenter/src/ConfigurationBase.ts index c400af41aa96..5dcb4e459f6b 100644 --- a/tools/api-markdown-documenter/src/ConfigurationBase.ts +++ b/tools/api-markdown-documenter/src/ConfigurationBase.ts @@ -8,6 +8,8 @@ import type { Logger } from "./Logging.js"; /** * Common base interface for configuration interfaces. * + * @privateRemarks TODO: Re-express as "WithLogger" instead of "ConfigurationBase" + * * @public */ export interface ConfigurationBase { diff --git a/tools/api-markdown-documenter/src/FileSystemConfiguration.ts b/tools/api-markdown-documenter/src/FileSystemConfiguration.ts index 2265a661cdfb..2250702730ff 100644 --- a/tools/api-markdown-documenter/src/FileSystemConfiguration.ts +++ b/tools/api-markdown-documenter/src/FileSystemConfiguration.ts @@ -14,7 +14,7 @@ export interface FileSystemConfiguration { /** * The directory under which the document files will be generated. */ - outputDirectoryPath: string; + readonly outputDirectoryPath: string; /** * Specifies what type of newlines API Documenter should use when writing output files. diff --git a/tools/api-markdown-documenter/src/RenderHtml.ts b/tools/api-markdown-documenter/src/RenderHtml.ts index c6e6d51aee49..093093e83658 100644 --- a/tools/api-markdown-documenter/src/RenderHtml.ts +++ b/tools/api-markdown-documenter/src/RenderHtml.ts @@ -9,7 +9,7 @@ import { FileSystem, NewlineKind } from "@rushstack/node-core-library"; import type { FileSystemConfiguration } from "./FileSystemConfiguration.js"; import { - type ApiItemTransformationConfiguration, + type ApiItemTransformationOptions, transformApiModel, } from "./api-item-transforms/index.js"; import type { DocumentNode } from "./documentation-domain/index.js"; @@ -18,32 +18,16 @@ import { type RenderDocumentAsHtmlConfig, renderDocumentAsHtml } from "./rendere /** * API Model HTML rendering options. * - * @public + * @alpha */ export interface RenderApiModelAsHtmlOptions - extends ApiItemTransformationConfiguration, + extends ApiItemTransformationOptions, RenderDocumentAsHtmlConfig, FileSystemConfiguration {} /** * Renders the provided model and its contents, and writes each document to a file on disk. * - * @remarks - * - * Which API members get their own documents and which get written to the contents of their parent is - * determined by {@link DocumentationSuiteOptions.documentBoundaries}. - * - * The file paths under which the files will be generated is determined by the provided output path and the - * following configuration properties: - * - * - {@link DocumentationSuiteOptions.documentBoundaries} - * - {@link DocumentationSuiteOptions.hierarchyBoundaries} - * - * @param transformConfig - Configuration for transforming API items into {@link DocumentationNode}s. - * @param renderConfig - Configuration for rendering {@link DocumentNode}s as HTML. - * @param fileSystemConfig - Configuration for writing document files to disk. - * @param logger - Receiver of system log data. Default: {@link defaultConsoleLogger}. - * * @alpha */ export async function renderApiModelAsHtml(options: RenderApiModelAsHtmlOptions): Promise { @@ -55,7 +39,7 @@ export async function renderApiModelAsHtml(options: RenderApiModelAsHtmlOptions) /** * Options for rendering {@link DocumentNode}s as HTML. * - * @public + * @alpha */ export interface RenderDocumentsAsHtmlOptions extends RenderDocumentAsHtmlConfig, @@ -66,9 +50,6 @@ export interface RenderDocumentsAsHtmlOptions * * @param documents - The documents to render. Each will be rendered to its own file on disk per * {@link DocumentNode.documentPath} (relative to the provided output directory). - * @param renderConfig - Configuration for rendering {@link DocumentNode}s as HTML. - * @param fileSystemConfig - Configuration for writing document files to disk. - * @param logger - Receiver of system log data. Default: {@link defaultConsoleLogger}. * * @alpha */ diff --git a/tools/api-markdown-documenter/src/RenderMarkdown.ts b/tools/api-markdown-documenter/src/RenderMarkdown.ts index 1e0b8dc738a1..b0218b4759a6 100644 --- a/tools/api-markdown-documenter/src/RenderMarkdown.ts +++ b/tools/api-markdown-documenter/src/RenderMarkdown.ts @@ -9,7 +9,7 @@ import { FileSystem, NewlineKind } from "@rushstack/node-core-library"; import type { FileSystemConfiguration } from "./FileSystemConfiguration.js"; import { - type ApiItemTransformationConfiguration, + type ApiItemTransformationOptions, transformApiModel, } from "./api-item-transforms/index.js"; import type { DocumentNode } from "./documentation-domain/index.js"; @@ -21,29 +21,13 @@ import { type MarkdownRenderConfiguration, renderDocumentAsMarkdown } from "./re * @public */ export interface RenderApiModelAsMarkdownOptions - extends ApiItemTransformationConfiguration, + extends ApiItemTransformationOptions, MarkdownRenderConfiguration, FileSystemConfiguration {} /** * Renders the provided model and its contents, and writes each document to a file on disk. * - * @remarks - * - * Which API members get their own documents and which get written to the contents of their parent is - * determined by {@link DocumentationSuiteOptions.documentBoundaries}. - * - * The file paths under which the files will be generated is determined by the provided output path and the - * following configuration properties: - * - * - {@link DocumentationSuiteOptions.documentBoundaries} - * - {@link DocumentationSuiteOptions.hierarchyBoundaries} - * - * @param transformConfig - Configuration for transforming API items into {@link DocumentationNode}s. - * @param renderConfig - Configuration for rendering {@link DocumentNode}s as Markdown. - * @param fileSystemConfig - Configuration for writing document files to disk. - * @param logger - Receiver of system log data. Default: {@link defaultConsoleLogger}. - * * @public */ export async function renderApiModelAsMarkdown( @@ -68,9 +52,6 @@ export interface RenderDocumentsAsMarkdownOptions * * @param documents - The documents to render. Each will be rendered to its own file on disk per * {@link DocumentNode.documentPath} (relative to the provided output directory). - * @param renderConfig - Configuration for rendering {@link DocumentNode}s as Markdown. - * @param fileSystemConfig - Configuration for writing document files to disk. - * @param logger - Receiver of system log data. Default: {@link defaultConsoleLogger}. * * @public */ 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 16b559efb543..9ac72ea6fb29 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts @@ -3,25 +3,42 @@ * Licensed under the MIT License. */ -import * as Path from "node:path"; +import { strict as assert } from "node:assert"; import { type ApiItem, ApiItemKind, ReleaseTag } from "@microsoft/api-extractor-model"; import type { Heading } from "../Heading.js"; import type { Link } from "../Link.js"; -import { getQualifiedApiItemName, getReleaseTag, getValueOrDerived, type DeepRequired } from "../utilities/index.js"; +import { + getApiItemKind, + getQualifiedApiItemName, + getReleaseTag, + getValueOrDerived, + type ValidApiItemKind, +} from "../utilities/index.js"; import { + FolderDocumentPlacement, HierarchyKind, type ApiItemTransformationConfiguration, - type DocumentBoundaries, - type HierarchyBoundaries, + type DocumentHierarchyConfig, + type FolderHierarchyConfig, + type HierarchyConfig, + type HierarchyOptions, } from "./configuration/index.js"; /** * This module contains `ApiItem`-related utilities for use in transformation logic. */ +/** + * API item paired with its hierarchy config. + */ +export interface ApiItemWithHierarchy { + readonly apiItem: ApiItem; + readonly hierarchy: THierarchy; +} + /** * Gets the nearest ancestor of the provided item that will have its own rendered document. * @@ -30,16 +47,16 @@ import { * as well as for generating links. * * @param apiItem - The API item for which we are generating a file path. - * @param documentBoundaries - See {@link DocumentBoundaries} + * @param hierarchyConfig - See {@link HierarchyOptions} */ function getFirstAncestorWithOwnDocument( apiItem: ApiItem, - documentBoundaries: DocumentBoundaries, -): ApiItem { + hierarchyConfig: Required, +): ApiItemWithHierarchy { // Walk parentage until we reach an item kind that gets rendered to its own document. // That is the document we will target with the generated link. let hierarchyItem: ApiItem = apiItem; - while (!doesItemRequireOwnDocument(hierarchyItem, documentBoundaries)) { + while (!doesItemRequireOwnDocument(hierarchyItem, hierarchyConfig)) { const parent = getFilteredParent(hierarchyItem); if (parent === undefined) { throw new Error( @@ -49,7 +66,15 @@ function getFirstAncestorWithOwnDocument( } hierarchyItem = parent; } - return hierarchyItem; + + const hierarchyItemKind = getApiItemKind(hierarchyItem); + const hierarchy = hierarchyConfig[hierarchyItemKind]; + assert(hierarchy.kind !== HierarchyKind.Section); + + return { + apiItem: hierarchyItem, + hierarchy, + }; } /** @@ -67,7 +92,7 @@ function getFirstAncestorWithOwnDocument( */ export function getLinkForApiItem( apiItem: ApiItem, - config: Required, + config: ApiItemTransformationConfiguration, textOverride?: string, ): Link { const text = textOverride ?? config.getLinkTextForItem(apiItem); @@ -90,10 +115,10 @@ export function getLinkForApiItem( */ function getLinkUrlForApiItem( apiItem: ApiItem, - config: Required, + config: ApiItemTransformationConfiguration, ): string { const uriBase = config.getUriBaseOverrideForItem(apiItem) ?? config.uriRoot; - let documentPath = getApiItemPath(apiItem, config).join("/"); + let documentPath = getDocumentPathForApiItem(apiItem, config); // Omit "index" file name from path generated in links. // This can be considered an optimization in most cases, but some documentation systems also special-case @@ -104,7 +129,7 @@ function getLinkUrlForApiItem( // Don't bother with heading ID if we are linking to the root item of a document let headingPostfix = ""; - if (!doesItemRequireOwnDocument(apiItem, config.documentBoundaries)) { + if (!doesItemRequireOwnDocument(apiItem, config.hierarchy)) { const headingId = getHeadingIdForApiItem(apiItem, config); headingPostfix = `#${headingId}`; } @@ -127,99 +152,49 @@ function getLinkUrlForApiItem( */ export function getDocumentPathForApiItem( apiItem: ApiItem, - config: Required, + config: ApiItemTransformationConfiguration, ): string { - const pathSegments = getApiItemPath(apiItem, config); - return Path.join(...pathSegments); -} - -/** - * Gets the path to the specified API item, represented as an ordered list of path segments. - * - * @param apiItem - The API item for which we are generating a file path. - * @param config - See {@link ApiItemTransformationConfiguration}. - */ -function getApiItemPath( - apiItem: ApiItem, - config: Required, -): string[] { - const targetDocumentItem = getFirstAncestorWithOwnDocument(apiItem, config.documentBoundaries); - - const fileName = getDocumentNameForApiItem(apiItem, config); + const { apiItem: targetDocumentItem, hierarchy: targetDocumentHierarchy } = + getFirstAncestorWithOwnDocument(apiItem, config.hierarchy); - // Filtered ancestry in ascending order - const documentAncestry = getAncestralHierarchy(targetDocumentItem, (hierarchyItem) => - doesItemGenerateHierarchy(hierarchyItem, config.hierarchyBoundaries), + const documentName = getValueOrDerived( + targetDocumentHierarchy.documentName, + targetDocumentItem, ); - return [ - fileName, - ...documentAncestry.map((hierarchyItem) => - getDocumentNameForApiItem(hierarchyItem, config), - ), - ].reverse(); -} - -/** - * Gets the document name for the specified API item. - * - * @remarks - * - * In the case of an item that does not get rendered to its own document, this will be the file name for the document - * of the ancestor item under which the provided item will be rendered. - * - * Note: This is strictly the name of the file, not a path to that file. - * To get the path, use {@link getDocumentPathForApiItem}. - * - * @param apiItem - The API item for which we are generating a file path. - * @param config - See {@link ApiItemTransformationConfiguration}. - */ -function getDocumentNameForApiItem( - apiItem: ApiItem, - config: Required, -): string { - const targetDocumentItem = getFirstAncestorWithOwnDocument(apiItem, config.documentBoundaries); - - let unscopedFileName = config.getFileNameForItem(targetDocumentItem); + const pathSegments: string[] = []; - // For items of kinds other than `Model` or `Package` (which are handled specially file-system-wise), - // append the item kind to disambiguate file names resulting from members whose names may conflict in a - // casing-agnostic context (e.g. type "Foo" and function "foo"). + // For the document itself, if its item creates folder-wise hierarchy, we need to refer to the hierarchy config + // to determine whether or not it should be placed inside or outside that folder. if ( - targetDocumentItem.kind !== ApiItemKind.Model && - targetDocumentItem.kind !== ApiItemKind.Package + targetDocumentHierarchy.kind === HierarchyKind.Folder && + targetDocumentHierarchy.documentPlacement === FolderDocumentPlacement.Inside ) { - unscopedFileName = `${unscopedFileName}-${targetDocumentItem.kind.toLocaleLowerCase()}`; - } - - // Walk parentage up until we reach the first ancestor which injects directory hierarchy. - // Qualify generated file name to ensure no conflicts within that directory. - let hierarchyItem = getFilteredParent(targetDocumentItem); - if (hierarchyItem === undefined) { - // If there is no parent item, then we can just return the file name unmodified - return unscopedFileName; + const folderName = getValueOrDerived( + targetDocumentHierarchy.folderName, + targetDocumentItem, + ); + pathSegments.push(`${folderName}/${documentName}`); + } else { + pathSegments.push(documentName); } - let scopedFileName = unscopedFileName; - while ( - hierarchyItem.kind !== ApiItemKind.Model && - !doesItemGenerateHierarchy(hierarchyItem, config.hierarchyBoundaries) - ) { - const segmentName = config.getFileNameForItem(hierarchyItem); - if (segmentName.length === 0) { - throw new Error("Segment name must be non-empty."); - } - - scopedFileName = `${segmentName}-${scopedFileName}`; - - const parent = getFilteredParent(hierarchyItem); - if (parent === undefined) { - break; + let currentItem: ApiItem | undefined = getFilteredParent(targetDocumentItem); + while (currentItem !== undefined) { + const currentItemKind = getApiItemKind(currentItem); + const currentItemHierarchy = config.hierarchy[currentItemKind]; + // Push path segments for all folders in the hierarchy + if (currentItemHierarchy.kind === HierarchyKind.Folder) { + const folderName = getValueOrDerived(currentItemHierarchy.folderName, currentItem); + pathSegments.push(folderName); } - hierarchyItem = parent; + currentItem = getFilteredParent(currentItem); } - return scopedFileName; + // Hierarchy is built from the root down, so reverse the segments to get the correct file path ordering + pathSegments.reverse(); + + return pathSegments.join("/"); } /** @@ -235,21 +210,31 @@ function getDocumentNameForApiItem( */ export function getHeadingForApiItem( apiItem: ApiItem, - config: Required, + config: ApiItemTransformationConfiguration, headingLevel?: number, ): Heading { // Don't generate an ID for the root heading - const id = doesItemRequireOwnDocument(apiItem, config.documentBoundaries) + const id = doesItemRequireOwnDocument(apiItem, config.hierarchy) ? undefined : getHeadingIdForApiItem(apiItem, config); + const title = getHeadingTextForApiItem(apiItem, config); return { - title: config.getHeadingTextForItem(apiItem), + title, id, level: headingLevel, }; } +function getHeadingTextForApiItem( + apiItem: ApiItem, + config: ApiItemTransformationConfiguration, +): string { + const itemKind = getApiItemKind(apiItem); + const hierarchy = config.hierarchy[itemKind]; + return getValueOrDerived(hierarchy.headingText, apiItem); +} + /** * Generates a unique heading ID for the provided API item. * @@ -260,7 +245,7 @@ export function getHeadingForApiItem( * Any links pointing to this item may simply link to the document; no heading ID is needed. * * - The resulting ID is context-dependent. In order to guarantee uniqueness, it will need to express - * hierarchical information up to the ancester item whose document the specified item will ultimately be rendered to. + * hierarchical information up to the ancestor item whose document the specified item will ultimately be rendered to. * * @param apiItem - The API item for which the heading ID is being generated. * @param config - See {@link ApiItemTransformationConfiguration}. @@ -269,7 +254,7 @@ export function getHeadingForApiItem( */ function getHeadingIdForApiItem( apiItem: ApiItem, - config: DeepRequired, + config: ApiItemTransformationConfiguration, ): string { let baseName: string | undefined; const apiItemKind: ApiItemKind = apiItem.kind; @@ -277,7 +262,7 @@ function getHeadingIdForApiItem( // Walk parentage up until we reach the ancestor into whose document we're being rendered. // Generate ID information for everything back to that point let hierarchyItem = apiItem; - while (!doesItemRequireOwnDocument(hierarchyItem, config.documentBoundaries)) { + while (!doesItemRequireOwnDocument(hierarchyItem, config.hierarchy)) { const qualifiedName = getQualifiedApiItemName(hierarchyItem); // Since we're walking up the tree, we'll build the string from the end for simplicity @@ -306,7 +291,7 @@ function getHeadingIdForApiItem( * * @param apiItem - The API item whose filtered parent will be returned. */ -function getFilteredParent(apiItem: ApiItem): ApiItem | undefined { +export function getFilteredParent(apiItem: ApiItem): ApiItem | undefined { const parent = apiItem.parent; if (parent?.kind === ApiItemKind.EntryPoint) { return parent.parent; @@ -314,44 +299,6 @@ function getFilteredParent(apiItem: ApiItem): ApiItem | undefined { return parent; } -/** - * Gets the ancestral hierarchy of the provided API item by walking up the parentage graph and emitting any items - * matching the `includePredicate` until it reaches an item that matches the `breakPredicate`. - * - * @remarks Notes: - * - * - This will not include the provided item itself, even if it matches the `includePredicate`. - * - * - This will not include the item matching the `breakPredicate`, even if they match the `includePredicate`. - * - * @param apiItem - The API item whose ancestral hierarchy is being queried. - * @param includePredicate - Predicate to determine which items in the hierarchy should be preserved in the - * returned list. The provided API item will not be included in the output, even if it would be included by this. - * @param breakPredicate - Predicate to determine when to break from the traversal and return. - * The item matching this predicate will not be included, even if it would be included by `includePredicate`. - * - * @returns The list of matching ancestor items, provided in *ascending* order. - */ -export function getAncestralHierarchy( - apiItem: ApiItem, - includePredicate: (apiItem: ApiItem) => boolean, - breakPredicate?: (apiItem: ApiItem) => boolean, -): ApiItem[] { - const matches: ApiItem[] = []; - - let hierarchyItem: ApiItem | undefined = getFilteredParent(apiItem); - while ( - hierarchyItem !== undefined && - (breakPredicate === undefined || !breakPredicate(hierarchyItem)) - ) { - if (includePredicate(hierarchyItem)) { - matches.push(hierarchyItem); - } - hierarchyItem = getFilteredParent(hierarchyItem); - } - return matches; -} - /** * Determines whether or not the specified API item is one that should be rendered to its own document * (as opposed to being rendered to a section under some ancestor item's document). @@ -361,38 +308,27 @@ export function getAncestralHierarchy( * * @public */ -export function doesItemRequireOwnDocument( - apiItem: ApiItem, - config: DeepRequired, +export function doesItemKindRequireOwnDocument( + apiItemKind: ValidApiItemKind, + hierarchyConfig: Required, ): boolean { - const hierarchy = getValueOrDerived(config.hierarchy, apiItem); + const hierarchy = hierarchyConfig[apiItemKind]; return hierarchy.kind !== HierarchyKind.Section; } /** - * Determines whether or not the specified API item is one that should generate directory-wise hierarchy - * in the resulting documentation suite. - * I.e. whether or not child item documents should be generated under a sub-directory adjacent to the item in question. - * - * @remarks - * `EntryPoint` items are *never* rendered to their own documents (as they are completely ignored by this system), - * regardless of the specified boundaries. + * Determines whether or not the specified API item is one that should be rendered to its own document + * (as opposed to being rendered to a section under some ancestor item's document). * - * @param apiItem - The API item being queried. + * @param apiItem - The API being queried. * @param config - See {@link ApiItemTransformationConfiguration}. */ -function doesItemGenerateHierarchy( +export function doesItemRequireOwnDocument( apiItem: ApiItem, - config: DeepRequired, + hierarchyConfig: Required, ): boolean { - if (apiItem.kind === ApiItemKind.EntryPoint) { - // The same API item within a package can be included in multiple entry-points, so it doesn't make sense to - // include it in generated hierarchy. - return false; - } - - const hierarchy = getValueOrDerived(config.hierarchy, apiItem); - return hierarchy.kind === HierarchyKind.Folder; + const itemKind = getApiItemKind(apiItem); + return doesItemKindRequireOwnDocument(itemKind, hierarchyConfig); } /** diff --git a/tools/api-markdown-documenter/src/api-item-transforms/TransformApiItem.ts b/tools/api-markdown-documenter/src/api-item-transforms/TransformApiItem.ts index 23b83edc960a..b308d60c51ce 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/TransformApiItem.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/TransformApiItem.ts @@ -37,7 +37,7 @@ import { createBreadcrumbParagraph, wrapInSection } from "./helpers/index.js"; * * This should only be called for API item kinds that are intended to be rendered to their own document * (as opposed to being rendered to the same document as their parent) per the provided `config` - * (see {@link DocumentationSuiteOptions.documentBoundaries}). + * (see {@link ApiItemTransformationConfiguration.hierarchy}). * * Also note that this should not be called for the following item kinds, which must be handled specially: * @@ -52,7 +52,7 @@ import { createBreadcrumbParagraph, wrapInSection } from "./helpers/index.js"; */ export function apiItemToDocument( apiItem: ApiItem, - config: Required, + config: ApiItemTransformationConfiguration, ): DocumentNode { if (apiItem.kind === ApiItemKind.None) { throw new Error(`Encountered API item "${apiItem.displayName}" with a kind of "None".`); @@ -72,7 +72,7 @@ export function apiItemToDocument( ); } - if (!doesItemRequireOwnDocument(apiItem, config.documentBoundaries)) { + if (!doesItemRequireOwnDocument(apiItem, config.hierarchy)) { throw new Error( `"renderApiDocument" called for an API item kind that is not intended to be rendered to its own document. Provided item kind: "${apiItem.kind}".`, ); diff --git a/tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts b/tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts index f8820f8a1e8f..22325bd3f84a 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts @@ -12,6 +12,7 @@ import { apiItemToDocument, apiItemToSections } from "./TransformApiItem.js"; import { createDocument } from "./Utilities.js"; import { type ApiItemTransformationConfiguration, + type ApiItemTransformationOptions, getApiItemTransformationConfigurationWithDefaults, } from "./configuration/index.js"; import { createBreadcrumbParagraph, createEntryPointList, wrapInSection } from "./helpers/index.js"; @@ -19,24 +20,11 @@ import { createBreadcrumbParagraph, createEntryPointList, wrapInSection } from " /** * Renders the provided model and its contents to a series of {@link DocumentNode}s. * - * @remarks - * - * Which API members get their own documents and which get written to the contents of their parent is - * determined by {@link DocumentationSuiteOptions.documentBoundaries}. - * - * The generated nodes' {@link DocumentNode.documentPath}s are determined by the provided output path and the - * following configuration properties: - * - * - {@link DocumentationSuiteOptions.documentBoundaries} - * - {@link DocumentationSuiteOptions.hierarchyBoundaries} - * * @param transformConfig - Configuration for transforming API items into {@link DocumentationNode}s. * * @public */ -export function transformApiModel( - transformConfig: ApiItemTransformationConfiguration, -): DocumentNode[] { +export function transformApiModel(transformConfig: ApiItemTransformationOptions): DocumentNode[] { const completeConfig = getApiItemTransformationConfigurationWithDefaults(transformConfig); const { apiModel, logger, skipPackage } = completeConfig; @@ -134,17 +122,14 @@ export function transformApiModel( * @param apiItem - The API item in question. * @param config - See {@link ApiItemTransformationConfiguration} */ -function getDocumentItems( - apiItem: ApiItem, - config: Required, -): ApiItem[] { - const { documentBoundaries } = config; +function getDocumentItems(apiItem: ApiItem, config: ApiItemTransformationConfiguration): ApiItem[] { + const { hierarchy } = config; const result: ApiItem[] = []; for (const childItem of apiItem.members) { if ( shouldItemBeIncluded(childItem, config) && - doesItemRequireOwnDocument(childItem, documentBoundaries) + doesItemRequireOwnDocument(childItem, hierarchy) ) { result.push(childItem); } @@ -163,7 +148,7 @@ function getDocumentItems( */ function createDocumentForApiModel( apiModel: ApiModel, - config: Required, + config: ApiItemTransformationConfiguration, ): DocumentNode { const { logger, transformApiModel: createModelBodySections } = config; @@ -194,7 +179,7 @@ function createDocumentForApiModel( function createDocumentForSingleEntryPointPackage( apiPackage: ApiPackage, apiEntryPoint: ApiEntryPoint, - config: Required, + config: ApiItemTransformationConfiguration, ): DocumentNode { const { includeBreadcrumb, logger, transformApiEntryPoint } = config; diff --git a/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts b/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts index 057c13e95e86..10e90e02a07f 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts @@ -8,7 +8,7 @@ import type { DocDeclarationReference } from "@microsoft/tsdoc"; import type { Link } from "../Link.js"; import { DocumentNode, type SectionNode } from "../documentation-domain/index.js"; -import { resolveSymbolicReference } from "../utilities/index.js"; +import { getApiItemKind, getValueOrDerived, resolveSymbolicReference } from "../utilities/index.js"; import { getDocumentPathForApiItem, @@ -31,11 +31,15 @@ import { wrapInSection } from "./helpers/index.js"; export function createDocument( documentItem: ApiItem, sections: SectionNode[], - config: Required, + config: ApiItemTransformationConfiguration, ): DocumentNode { + const documentItemKind = getApiItemKind(documentItem); + const documentHierarchy = config.hierarchy[documentItemKind]; + const title = getValueOrDerived(documentHierarchy.headingText, documentItem); + // Wrap sections in a root section if top-level heading is requested. const contents = config.includeTopLevelDocumentHeading - ? [wrapInSection(sections, { title: config.getHeadingTextForItem(documentItem) })] + ? [wrapInSection(sections, { title })] : sections; return new DocumentNode({ diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts index cb157378b441..9064753b24b0 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts @@ -9,23 +9,21 @@ import type { ConfigurationBase } from "../../ConfigurationBase.js"; import { defaultConsoleLogger } from "../../Logging.js"; import { + type DocumentationSuiteConfiguration, type DocumentationSuiteOptions, - getDocumentationSuiteOptionsWithDefaults, + getDocumentationSuiteConfigurationWithDefaults, } from "./DocumentationSuiteOptions.js"; import { - type ApiItemTransformationOptions, - getApiItemTransformationOptionsWithDefaults, -} from "./TransformationOptions.js"; + type ApiItemTransformations, + getApiItemTransformationsWithDefaults, +} from "./Transformations.js"; /** - * API Item transformation configuration. + * API Item transformation configuration base. * * @public */ -export interface ApiItemTransformationConfiguration - extends ApiItemTransformationOptions, - DocumentationSuiteOptions, - ConfigurationBase { +export interface ApiItemTransformationConfigurationBase { /** * API Model for which the documentation is being generated. * This is the output of {@link https://api-extractor.com/ | API-Extractor}. @@ -36,7 +34,7 @@ export interface ApiItemTransformationConfiguration * * If you need to generate a model from API reports on disk, see {@link loadModel}. */ - apiModel: ApiModel; + readonly apiModel: ApiModel; /** * Default root URI used when generating content links. @@ -44,6 +42,28 @@ export interface ApiItemTransformationConfiguration readonly uriRoot: string; } +/** + * Partial API Item transformation options. + * + * @public + */ +export interface ApiItemTransformationOptions + extends ApiItemTransformationConfigurationBase, + ApiItemTransformations, + DocumentationSuiteOptions, + ConfigurationBase {} + +/** + * Complete API Item transformation configuration. + * + * @public + */ +export interface ApiItemTransformationConfiguration + extends ApiItemTransformationConfigurationBase, + Required, + DocumentationSuiteConfiguration, + Required {} + /** * Gets a complete {@link ApiItemTransformationConfiguration} using the provided partial configuration, and filling * in the remainder with the documented defaults. @@ -51,11 +71,11 @@ export interface ApiItemTransformationConfiguration * @public */ export function getApiItemTransformationConfigurationWithDefaults( - inputOptions: ApiItemTransformationConfiguration, + inputOptions: ApiItemTransformationOptions, ): Required { const logger = inputOptions.logger ?? defaultConsoleLogger; - const documentationSuiteOptions = getDocumentationSuiteOptionsWithDefaults(inputOptions); - const transformationOptions = getApiItemTransformationOptionsWithDefaults(inputOptions); + const documentationSuiteOptions = getDocumentationSuiteConfigurationWithDefaults(inputOptions); + const transformationOptions = getApiItemTransformationsWithDefaults(inputOptions); return { ...documentationSuiteOptions, ...transformationOptions, diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts index 78a0375eeba4..814a94804536 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts @@ -35,7 +35,7 @@ export interface DocumentationSuiteOptions { * @remarks If you will be rendering the document contents into some other document content that will inject its * own root heading, this can be used to omit that heading from what is rendered by this system. */ - includeTopLevelDocumentHeading?: boolean; + readonly includeTopLevelDocumentHeading?: boolean; /** * Whether or not to include a navigation breadcrumb at the top of rendered documents. @@ -44,7 +44,7 @@ export interface DocumentationSuiteOptions { * * @remarks Note: `Model` items will never have a breadcrumb rendered, even if this is specified. */ - includeBreadcrumb?: boolean; + readonly includeBreadcrumb?: boolean; /** * {@link HierarchyConfig} to use for the provided API item. @@ -65,7 +65,7 @@ export interface DocumentationSuiteOptions { * * @defaultValue Always use the default URI base. */ - getUriBaseOverrideForItem?: (apiItem: ApiItem) => string | undefined; + readonly getUriBaseOverrideForItem?: (apiItem: ApiItem) => string | undefined; /** * Generate link text for the provided `ApiItem`. @@ -76,7 +76,7 @@ export interface DocumentationSuiteOptions { * * @defaultValue {@link DefaultDocumentationSuiteOptions.defaultGetLinkTextForItem} */ - getLinkTextForItem?: (apiItem: ApiItem) => string; + readonly getLinkTextForItem?: (apiItem: ApiItem) => string; /** * Generate a list of "alerts" to display in API items tables for a given API item. @@ -87,7 +87,7 @@ export interface DocumentationSuiteOptions { * * @defaultValue {@link DefaultDocumentationSuiteOptions.defaultGetAlertsForItem} */ - getAlertsForItem?: (apiItem: ApiItem) => string[]; + readonly getAlertsForItem?: (apiItem: ApiItem) => string[]; /** * Whether or not the provided `ApiPackage` should be skipped during documentation generation. @@ -100,7 +100,7 @@ export interface DocumentationSuiteOptions { * * @defaultValue No packages are skipped. */ - skipPackage?: (apiPackage: ApiPackage) => boolean; + readonly skipPackage?: (apiPackage: ApiPackage) => boolean; /** * Minimal release scope to include in generated documentation suite. @@ -123,9 +123,24 @@ export interface DocumentationSuiteOptions { * releaseLevel: ReleaseTag.Beta * ``` */ - minimumReleaseLevel?: Omit; + readonly minimumReleaseLevel?: Exclude; } +/** + * Complete configuration documentation suite generation via the API Item -\> Documentation Domain transformation. + * + * @public + */ +export type DocumentationSuiteConfiguration = Omit< + Required, + "hierarchy" +> & { + /** + * {@inheritDoc DocumentationSuiteOptions.hierarchy} + */ + readonly hierarchy: Required; +}; + /** * Contains a list of default documentation transformations, used by {@link DocumentationSuiteOptions}. * @@ -168,7 +183,7 @@ export namespace DefaultDocumentationSuiteOptions { } /** - * Default {@link DocumentationSuiteOptions.getHeadingTextForItem}. + * Default {@link DocumentationSuiteOptions.getAlertsForItem}. * * Generates alerts for the following tags, if found: * @@ -221,13 +236,13 @@ const defaultDocumentationSuiteOptions: Required = { * Gets a complete {@link DocumentationSuiteOptions} using the provided partial configuration, and filling * in the remainder with the documented defaults. */ -export function getDocumentationSuiteOptionsWithDefaults( +export function getDocumentationSuiteConfigurationWithDefaults( inputOptions: DocumentationSuiteOptions, -): Required { +): DocumentationSuiteConfiguration { const hierarchy: Required = { ...defaultHierarchyOptions, ...inputOptions.hierarchy, - } + }; return { ...defaultDocumentationSuiteOptions, ...inputOptions, diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts index 75075b931cdb..461e09708d13 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts @@ -43,6 +43,8 @@ export enum HierarchyKind { * @remarks * Not intended for external use. * Only exists to share common properties between hierarchy configuration types. + * + * @public */ export interface HierarchyConfigBase { /** @@ -77,7 +79,7 @@ export interface SectionHierarchyConfig * * @public */ -export interface DocumentHierarchyOptions { +export interface DocumentHierarchyOptions extends SectionHierarchyOptions { /** * Document name to use for the API item. */ @@ -91,7 +93,6 @@ export interface DocumentHierarchyOptions { */ export interface DocumentHierarchyConfig extends HierarchyConfigBase, - SectionHierarchyOptions, DocumentHierarchyOptions {} /** @@ -118,7 +119,7 @@ export enum FolderDocumentPlacement { * * @public */ -export interface FolderHierarchyOptions { +export interface FolderHierarchyOptions extends DocumentHierarchyOptions { /** * Placement of the API item's document relative to its generated folder. * `inside`: The document is placed inside its folder. @@ -141,12 +142,12 @@ export interface FolderHierarchyOptions { */ export interface FolderHierarchyConfig extends HierarchyConfigBase, - SectionHierarchyOptions, - DocumentHierarchyOptions, FolderHierarchyOptions {} /** * API item hierarchy configuration. + * + * @public */ export type HierarchyConfig = | SectionHierarchyConfig @@ -202,8 +203,9 @@ function defaultDocumentName(apiItem: ApiItem): string { return getFileSafeNameForApiItem(apiItem); } default: { - // TODO: append item kind postfix - return getQualifiedApiItemName(apiItem); + const base = getQualifiedApiItemName(apiItem); + const postfix = apiItem.kind.toLocaleLowerCase(); + return `${base}-${postfix}`; } } } @@ -214,36 +216,31 @@ const defaultDocumentHierarchyConfig: DocumentHierarchyConfig = { documentName: defaultDocumentName, }; -function defaultFolderName(apiItem: ApiItem): string { - const kind = getApiItemKind(apiItem); - switch (kind) { - case ApiItemKind.Package: { - return getFileSafeNameForApiItem(apiItem); - } - default: { - // TODO: append item kind postfix - return getQualifiedApiItemName(apiItem); - } - } -} +// Default folder name is the same as the default document name. +const defaultFolderName = defaultDocumentName; const defaultFolderHierarchyConfig: FolderHierarchyConfig = { kind: HierarchyKind.Folder, headingText: defaultHeadingText, - documentPlacement: FolderDocumentPlacement.Inside, - documentName: "index", // Documents for items that get their own folder are always named "index" by default. + documentPlacement: FolderDocumentPlacement.Outside, // TODO + documentName: defaultDocumentName, + // documentName: "index", // Documents for items that get their own folder are always named "index" by default. folderName: defaultFolderName, }; - /** * Hierarchy options by API item kind. + * + * @public */ export type HierarchyOptions = { /** * Hierarchy configuration for the API item kind. */ - [Kind in Exclude]: HierarchyConfig; + [Kind in Exclude< + ValidApiItemKind, + ApiItemKind.Model | ApiItemKind.EntryPoint | ApiItemKind.Package + >]: HierarchyConfig; } & { /** * Hierarchy configuration for the `Model` API item kind. @@ -260,8 +257,13 @@ export type HierarchyOptions = { */ [ApiItemKind.Package]: FolderHierarchyConfig; - // TODO: Allow entry-point configuration? -} + /** + * Hierarchy configuration for the `EntryPoint` API item kind. + * + * @remarks Always a section under the parent (package) document. + */ + [ApiItemKind.EntryPoint]: SectionHierarchyConfig; +}; /** * Default {@link HierarchyOptions}. @@ -279,15 +281,16 @@ export const defaultHierarchyOptions: HierarchyOptions = { // Items that get their own document, but do not introduce folder hierarchy: [ApiItemKind.Class]: defaultDocumentHierarchyConfig, - [ApiItemKind.Enum]: defaultDocumentHierarchyConfig, + [ApiItemKind.Enum]: defaultSectionHierarchyConfig, // TODO: DocumentHierarchyConfig [ApiItemKind.Interface]: defaultDocumentHierarchyConfig, - [ApiItemKind.TypeAlias]: defaultDocumentHierarchyConfig, + [ApiItemKind.TypeAlias]: defaultSectionHierarchyConfig, // TODO: DocumentHierarchyConfig // Items that get a section under the document representing an ancestor of the API item: [ApiItemKind.CallSignature]: defaultSectionHierarchyConfig, [ApiItemKind.Constructor]: defaultSectionHierarchyConfig, [ApiItemKind.ConstructSignature]: defaultSectionHierarchyConfig, [ApiItemKind.EnumMember]: defaultSectionHierarchyConfig, + [ApiItemKind.EntryPoint]: defaultSectionHierarchyConfig, [ApiItemKind.Function]: defaultSectionHierarchyConfig, [ApiItemKind.IndexSignature]: defaultSectionHierarchyConfig, [ApiItemKind.Method]: defaultSectionHierarchyConfig, @@ -295,29 +298,4 @@ export const defaultHierarchyOptions: HierarchyOptions = { [ApiItemKind.Property]: defaultSectionHierarchyConfig, [ApiItemKind.PropertySignature]: defaultSectionHierarchyConfig, [ApiItemKind.Variable]: defaultSectionHierarchyConfig, -} - -/** - * Default {@link DocumentationSuiteOptions.hierarchyOptions}. - */ -export const defaultHierarchyConfig = (apiItem: ApiItem): HierarchyConfig => { - const kind = getApiItemKind(apiItem); - - // TODO: audit these - switch (kind) { - case ApiItemKind.Namespace: - case ApiItemKind.Package: { - return defaultFolderHierarchyConfig; - } - case ApiItemKind.Class: - case ApiItemKind.Interface: - case ApiItemKind.EntryPoint: - case ApiItemKind.Model: - case ApiItemKind.TypeAlias: { - return defaultDocumentHierarchyConfig; - } - default: { - return defaultSectionHierarchyConfig; - } - } }; diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/TransformationOptions.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Transformations.ts similarity index 77% rename from tools/api-markdown-documenter/src/api-item-transforms/configuration/TransformationOptions.ts rename to tools/api-markdown-documenter/src/api-item-transforms/configuration/Transformations.ts index b04d2c56e0f0..ed12dd0011c5 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/TransformationOptions.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Transformations.ts @@ -57,9 +57,11 @@ export type TransformApiItemWithoutChildren = ( * * @remarks For any transformation not explicitly configured, a default will be used. * + * @privateRemarks TODO: re-express property names in terms of `ApiItemKind` for consistency. + * * @public */ -export interface ApiItemTransformationOptions { +export interface ApiItemTransformations { /** * Generates the default layout used by all default API item transformations. * @@ -71,7 +73,7 @@ export interface ApiItemTransformationOptions { * * @returns The list of {@link SectionNode}s that comprise the top-level section body for the API item. */ - createDefaultLayout?: ( + readonly createDefaultLayout?: ( apiItem: ApiItem, childSections: SectionNode[] | undefined, config: Required, @@ -80,17 +82,17 @@ export interface ApiItemTransformationOptions { /** * Transformation to generate a {@link SectionNode} for a `Call Signature`. */ - transformApiCallSignature?: TransformApiItemWithoutChildren; + readonly transformApiCallSignature?: TransformApiItemWithoutChildren; /** * Transformation to generate a {@link SectionNode} for a `Class`. */ - transformApiClass?: TransformApiItemWithChildren; + readonly transformApiClass?: TransformApiItemWithChildren; /** * Transformation to generate a {@link SectionNode} for a `Constructor`. */ - transformApiConstructor?: TransformApiItemWithoutChildren< + readonly transformApiConstructor?: TransformApiItemWithoutChildren< ApiConstructSignature | ApiConstructor >; @@ -102,37 +104,37 @@ export interface ApiItemTransformationOptions { * Note: for packages that have a single entry-point, this content will be bubbled up to the generated * package-level document to reduce unecessary indirection in the generated suite. */ - transformApiEntryPoint?: TransformApiItemWithChildren; + readonly transformApiEntryPoint?: TransformApiItemWithChildren; /** * Transformation to generate a {@link SectionNode} for an `Enum`. */ - transformApiEnum?: TransformApiItemWithChildren; + readonly transformApiEnum?: TransformApiItemWithChildren; /** * Transformation to generate a {@link SectionNode} for an `Enum Member` (flag). */ - transformApiEnumMember?: TransformApiItemWithoutChildren; + readonly transformApiEnumMember?: TransformApiItemWithoutChildren; /** * Transformation to generate a {@link SectionNode} for a `Function`. */ - transformApiFunction?: TransformApiItemWithoutChildren; + readonly transformApiFunction?: TransformApiItemWithoutChildren; /** * Transformation to generate a {@link SectionNode} for an `Index Signature`. */ - transformApiIndexSignature?: TransformApiItemWithoutChildren; + readonly transformApiIndexSignature?: TransformApiItemWithoutChildren; /** * Transformation to generate a {@link SectionNode} for an `Interface`. */ - transformApiInterface?: TransformApiItemWithChildren; + readonly transformApiInterface?: TransformApiItemWithChildren; /** * Transformation to generate a {@link SectionNode} for a `Method`. */ - transformApiMethod?: TransformApiItemWithoutChildren; + readonly transformApiMethod?: TransformApiItemWithoutChildren; /** * Transformation to generate a {@link SectionNode} for an `ApiModel`. @@ -143,33 +145,33 @@ export interface ApiItemTransformationOptions { * and `Package` items specially. We never render `Package` child details directly to the `Model` document. * These are always rendered to separate documents from each other. */ - transformApiModel?: TransformApiItemWithoutChildren; + readonly transformApiModel?: TransformApiItemWithoutChildren; /** * Transformation to generate a {@link SectionNode} for a `Namespace`. */ - transformApiNamespace?: TransformApiItemWithChildren; + readonly transformApiNamespace?: TransformApiItemWithChildren; /** * Transformation to generate a {@link SectionNode} for a `Property`. */ - transformApiProperty?: TransformApiItemWithoutChildren; + readonly transformApiProperty?: TransformApiItemWithoutChildren; /** * Transformation to generate a {@link SectionNode} for a `Type Alias`. */ - transformApiTypeAlias?: TransformApiItemWithoutChildren; + readonly transformApiTypeAlias?: TransformApiItemWithoutChildren; /** * Transformation to generate a {@link SectionNode} for an `Variable`. */ - transformApiVariable?: TransformApiItemWithoutChildren; + readonly transformApiVariable?: TransformApiItemWithoutChildren; } /** * The default {@link ApiItemTransformationConfiguration}. */ -const defaultApiItemTransformationOptions: Required = { +const defaultApiItemTransformationOptions: Required = { transformApiCallSignature: DefaultTransformationImplementations.transformApiItemWithoutChildren, transformApiClass: DefaultTransformationImplementations.transformApiClass, transformApiConstructor: DefaultTransformationImplementations.transformApiFunctionLike, @@ -190,12 +192,12 @@ const defaultApiItemTransformationOptions: Required { +export function getApiItemTransformationsWithDefaults( + inputOptions: ApiItemTransformations, +): Required { return { ...defaultApiItemTransformationOptions, ...inputOptions, diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts index 06bd4412ab68..7ded0857a30f 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts @@ -5,12 +5,15 @@ export { type ApiItemTransformationConfiguration, + type ApiItemTransformationConfigurationBase, + type ApiItemTransformationOptions, getApiItemTransformationConfigurationWithDefaults, } from "./Configuration.js"; export { + type DocumentationSuiteConfiguration, type DefaultDocumentationSuiteOptions, type DocumentationSuiteOptions, - getDocumentationSuiteOptionsWithDefaults, + getDocumentationSuiteConfigurationWithDefaults as getDocumentationSuiteOptionsWithDefaults, } from "./DocumentationSuiteOptions.js"; export { HierarchyKind, @@ -23,11 +26,11 @@ export { type FolderHierarchyOptions, type FolderHierarchyConfig, type HierarchyConfig, - defaultHierarchyConfig, + type HierarchyOptions, } from "./HierarchyOptions.js"; export { - type ApiItemTransformationOptions, - getApiItemTransformationOptionsWithDefaults, + type ApiItemTransformations, + getApiItemTransformationsWithDefaults, type TransformApiItemWithChildren, type TransformApiItemWithoutChildren, -} from "./TransformationOptions.js"; +} from "./Transformations.js"; diff --git a/tools/api-markdown-documenter/src/api-item-transforms/default-implementations/CreateDefaultLayout.ts b/tools/api-markdown-documenter/src/api-item-transforms/default-implementations/CreateDefaultLayout.ts index b6b34de3b7f1..0eb9a38d39e9 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/default-implementations/CreateDefaultLayout.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/default-implementations/CreateDefaultLayout.ts @@ -116,7 +116,7 @@ export function createDefaultLayout( // Add heading to top of section only if this is being rendered to a parent item. // Document items have their headings handled specially. - return doesItemRequireOwnDocument(apiItem, config.documentBoundaries) + return doesItemRequireOwnDocument(apiItem, config.hierarchy) ? sections : [wrapInSection(sections, getHeadingForApiItem(apiItem, config))]; } diff --git a/tools/api-markdown-documenter/src/api-item-transforms/default-implementations/TransformApiClass.ts b/tools/api-markdown-documenter/src/api-item-transforms/default-implementations/TransformApiClass.ts index 768e22836749..b66a720fd1d8 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/default-implementations/TransformApiClass.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/default-implementations/TransformApiClass.ts @@ -45,7 +45,7 @@ import { createChildDetailsSection, createMemberTables } from "../helpers/index. * * - index-signatures * - * Details (for any types not rendered to their own documents - see {@link DocumentationSuiteOptions.documentBoundaries}) + * Details (for any types not rendered to their own documents - see {@link ApiItemTransformationOptions.hierarchy}) * * - constructors * diff --git a/tools/api-markdown-documenter/src/api-item-transforms/default-implementations/TransformApiInterface.ts b/tools/api-markdown-documenter/src/api-item-transforms/default-implementations/TransformApiInterface.ts index caded49e4a5a..756ed75a4f74 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/default-implementations/TransformApiInterface.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/default-implementations/TransformApiInterface.ts @@ -39,7 +39,7 @@ import { createChildDetailsSection, createMemberTables } from "../helpers/index. * * - index-signatures * - * Details (for any types not rendered to their own documents - see {@link DocumentationSuiteOptions.documentBoundaries}) + * Details (for any types not rendered to their own documents - see {@link ApiItemTransformationOptions.hierarchy}) * * - constructor-signatures * diff --git a/tools/api-markdown-documenter/src/api-item-transforms/default-implementations/TransformApiModuleLike.ts b/tools/api-markdown-documenter/src/api-item-transforms/default-implementations/TransformApiModuleLike.ts index c74976e54db2..320effbc913c 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/default-implementations/TransformApiModuleLike.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/default-implementations/TransformApiModuleLike.ts @@ -43,7 +43,7 @@ import { createChildDetailsSection, createMemberTables } from "../helpers/index. * * - namespaces * - * Details (for any types not rendered to their own documents - see {@link DocumentationSuiteOptions.documentBoundaries}) + * Details (for any types not rendered to their own documents - see {@link ApiItemTransformationOptions.hierarchy}) * * - interfaces * 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 78573bd70353..6e885cc7f1ab 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 @@ -10,7 +10,6 @@ import { type ApiEntryPoint, ApiInterface, type ApiItem, - type ApiItemKind, ApiReturnTypeMixin, ApiTypeParameterListMixin, type Excerpt, @@ -30,6 +29,7 @@ import { } from "@microsoft/tsdoc"; import type { Heading } from "../../Heading.js"; +import type { Link } from "../../Link.js"; import type { Logger } from "../../Logging.js"; import { type DocumentationNode, @@ -56,16 +56,17 @@ import { getDeprecatedBlock, getExampleBlocks, getReturnsBlock, + getApiItemKind, + type ValidApiItemKind, } from "../../utilities/index.js"; import { doesItemKindRequireOwnDocument, - doesItemRequireOwnDocument, - getAncestralHierarchy, + getFilteredParent, getLinkForApiItem, } from "../ApiItemTransformUtilities.js"; import { transformTsdocSection } from "../TsdocNodeTransforms.js"; import { getTsdocNodeTransformationOptions } from "../Utilities.js"; -import type { ApiItemTransformationConfiguration } from "../configuration/index.js"; +import { HierarchyKind, type ApiItemTransformationConfiguration } from "../configuration/index.js"; import { createParametersSummaryTable, createTypeParametersSummaryTable } from "./TableHelpers.js"; @@ -381,35 +382,44 @@ export function createExcerptSpanWithHyperlinks( * Renders a simple navigation breadcrumb. * * @remarks Displayed as a ` > `-separated list of hierarchical page links. - * 1 for each element in the provided item's ancestory for which a separate document is generated - * (see {@link DocumentBoundaries}). + * 1 for each element in the provided item's ancestry for which a separate document is generated + * (see {@link HierarchyOptions}). * - * @param apiItem - The API item whose ancestory will be used to generate the breadcrumb. + * @param apiItem - The API item whose ancestry will be used to generate the breadcrumb. * @param config - See {@link ApiItemTransformationConfiguration}. * * @public */ export function createBreadcrumbParagraph( apiItem: ApiItem, - config: Required, + config: ApiItemTransformationConfiguration, ): ParagraphNode { - // Get ordered ancestry of document items - const ancestry = getAncestralHierarchy(apiItem, (hierarchyItem) => - doesItemRequireOwnDocument(hierarchyItem, config.documentBoundaries), - ).reverse(); // Reverse from ascending to descending order + // #region Get ordered ancestry of document items - const breadcrumbSeparator = new PlainTextNode(" > "); + const breadcrumbLinks: Link[] = [getLinkForApiItem(apiItem, config)]; - const links = ancestry.map((hierarchyItem) => - LinkNode.createFromPlainTextLink(getLinkForApiItem(hierarchyItem, config)), - ); + let currentItem: ApiItem | undefined = getFilteredParent(apiItem); + while (currentItem !== undefined) { + const currentItemKind = getApiItemKind(currentItem); + const currentItemHierarchy = config.hierarchy[currentItemKind]; + // Push breadcrumb entries for all files in the hierarchy. + if (currentItemHierarchy.kind !== HierarchyKind.Section) { + breadcrumbLinks.push(getLinkForApiItem(currentItem, config)); + } - // Add link for current document item - links.push(LinkNode.createFromPlainTextLink(getLinkForApiItem(apiItem, config))); + currentItem = getFilteredParent(currentItem); + } + breadcrumbLinks.reverse(); // Items are populated in ascending order, but we want them in descending order. + + // #endregion + + const renderedLinks = breadcrumbLinks.map((link) => LinkNode.createFromPlainTextLink(link)); + + const breadcrumbSeparator = new PlainTextNode(" > "); // Inject breadcrumb separator between each link const contents: DocumentationNode[] = injectSeparator( - links, + renderedLinks, breadcrumbSeparator, ); @@ -960,7 +970,7 @@ export interface ChildSectionProperties { /** * The API item kind of all child items. */ - itemKind: ApiItemKind; + itemKind: ValidApiItemKind; /** * The child items to be rendered. @@ -997,7 +1007,7 @@ export function createChildDetailsSection( // (i.e. it does not get rendered to its own document). // Also only render the section if it actually has contents to render (to avoid empty headings). if ( - !doesItemRequireOwnDocument(childItem.itemKind, config) && + !doesItemKindRequireOwnDocument(childItem.itemKind, config.hierarchy) && childItem.items.length > 0 ) { const childContents: DocumentationNode[] = []; diff --git a/tools/api-markdown-documenter/src/api-item-transforms/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/index.ts index 29d11b1ad178..3c7029ef071d 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/index.ts @@ -9,18 +9,22 @@ export { doesItemRequireOwnDocument, + doesItemKindRequireOwnDocument, filterItems, + getFilteredParent, getHeadingForApiItem, getLinkForApiItem, shouldItemBeIncluded, } from "./ApiItemTransformUtilities.js"; export { type ApiItemTransformationConfiguration, + type ApiItemTransformationConfigurationBase, type ApiItemTransformationOptions, + type ApiItemTransformations, type DefaultDocumentationSuiteOptions, - defaultHierarchyConfig, type DocumentHierarchyConfig, type DocumentHierarchyOptions, + type DocumentationSuiteConfiguration, type DocumentationSuiteOptions, FolderDocumentPlacement, type FolderHierarchyConfig, @@ -29,6 +33,7 @@ export { type HierarchyConfig, type HierarchyConfigBase, HierarchyKind, + type HierarchyOptions, type SectionHierarchyConfig, type SectionHierarchyOptions, type TransformApiItemWithChildren, diff --git a/tools/api-markdown-documenter/src/api-item-transforms/test/Transformation.test.ts b/tools/api-markdown-documenter/src/api-item-transforms/test/Transformation.test.ts index 00a8bddeb3f1..268fe10655d4 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/test/Transformation.test.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/test/Transformation.test.ts @@ -41,6 +41,7 @@ import { apiItemToSections } from "../TransformApiItem.js"; import { transformApiModel } from "../TransformApiModel.js"; import { type ApiItemTransformationConfiguration, + type ApiItemTransformationOptions, getApiItemTransformationConfigurationWithDefaults, } from "../configuration/index.js"; import { betaWarningSpan, wrapInSection } from "../helpers/index.js"; @@ -48,7 +49,7 @@ import { betaWarningSpan, wrapInSection } from "../helpers/index.js"; /** * Sample "default" configuration. */ -const defaultPartialConfig: Omit = { +const defaultPartialConfig: Omit = { uriRoot: ".", }; @@ -114,9 +115,9 @@ function findApiMember( * Creates a config for testing. */ function createConfig( - partialConfig: Omit, + partialConfig: Omit, apiModel: ApiModel, -): Required { +): ApiItemTransformationConfiguration { return getApiItemTransformationConfigurationWithDefaults({ ...partialConfig, apiModel, diff --git a/tools/api-markdown-documenter/src/index.ts b/tools/api-markdown-documenter/src/index.ts index 23a32a7aa744..09bb1bec35df 100644 --- a/tools/api-markdown-documenter/src/index.ts +++ b/tools/api-markdown-documenter/src/index.ts @@ -15,14 +15,25 @@ export { type ApiItemTransformationConfiguration, + type ApiItemTransformationConfigurationBase, type ApiItemTransformationOptions, + type ApiItemTransformations, type DefaultDocumentationSuiteOptions, + type DocumentHierarchyConfig, + type DocumentHierarchyOptions, + type DocumentationSuiteConfiguration, type DocumentationSuiteOptions, FolderDocumentPlacement, + type FolderHierarchyConfig, + type FolderHierarchyOptions, // TODO: remove this once utility APIs can be called with partial configs. getApiItemTransformationConfigurationWithDefaults, type HierarchyConfig, + type HierarchyConfigBase, HierarchyKind, + type HierarchyOptions, + type SectionHierarchyConfig, + type SectionHierarchyOptions, type TransformApiItemWithChildren, type TransformApiItemWithoutChildren, transformApiModel, @@ -67,13 +78,13 @@ export { type Logger, verboseConsoleLogger, } from "./Logging.js"; -export { - type ApiFunctionLike, - type ApiMemberKind, - type ApiModifier, - type ApiModuleLike, - type ApiSignatureLike, - type DeepRequired, +export type { + ApiFunctionLike, + ApiMemberKind, + ApiModifier, + ApiModuleLike, + ApiSignatureLike, + ValidApiItemKind, } from "./utilities/index.js"; // #region Scoped exports diff --git a/tools/api-markdown-documenter/src/test/EndToEndTests.ts b/tools/api-markdown-documenter/src/test/EndToEndTests.ts index 4a7069593e40..24612b20057c 100644 --- a/tools/api-markdown-documenter/src/test/EndToEndTests.ts +++ b/tools/api-markdown-documenter/src/test/EndToEndTests.ts @@ -5,12 +5,7 @@ import Path from "node:path"; -import { - ApiItemContainerMixin, - ApiItemKind, - type ApiItem, - type ApiModel, -} from "@microsoft/api-extractor-model"; +import { ApiItemKind, type ApiModel } from "@microsoft/api-extractor-model"; import { FileSystem } from "@rushstack/node-core-library"; import { expect } from "chai"; import { compare } from "dir-compare"; @@ -19,15 +14,18 @@ import type { Suite } from "mocha"; import { ApiItemUtilities, loadModel, + type DocumentHierarchyConfig, type DocumentNode, FolderDocumentPlacement, HierarchyKind, + type HierarchyOptions, transformApiModel, - type HierarchyConfig, - type DeepRequired, type MarkdownRenderer, type HtmlRenderer, type ApiItemTransformationConfiguration, + type ApiItemTransformationOptions, + type FolderHierarchyConfig, + type SectionHierarchyConfig, } from "../index.js"; /** @@ -108,7 +106,7 @@ export interface EndToEndTestConfig { /** * Transformation / render configuration */ - readonly renderConfig: Omit & + readonly renderConfig: Omit & Omit; } @@ -204,82 +202,112 @@ export function endToEndTests( /** * Test hierarchy configs + * + * @privateRemarks TODO: Formalize and export some of these as pre-canned solutions? */ // eslint-disable-next-line @typescript-eslint/no-namespace export namespace HierarchyConfigs { + const defaultSectionConfig: SectionHierarchyConfig = { + kind: HierarchyKind.Section, + headingText: (apiItem) => apiItem.displayName, + }; + + const defaultDocumentConfig: DocumentHierarchyConfig = { + kind: HierarchyKind.Document, + documentName: (apiItem) => ApiItemUtilities.getFileSafeNameForApiItem(apiItem), + headingText: (apiItem) => apiItem.displayName, + }; + + const outsideFolderConfig: FolderHierarchyConfig = { + kind: HierarchyKind.Folder, + documentPlacement: FolderDocumentPlacement.Outside, + documentName: (apiItem) => ApiItemUtilities.getFileSafeNameForApiItem(apiItem), + folderName: (apiItem) => ApiItemUtilities.getFileSafeNameForApiItem(apiItem), + headingText: (apiItem) => apiItem.displayName, + }; + + const insideFolderConfig: FolderHierarchyConfig = { + kind: HierarchyKind.Folder, + documentPlacement: FolderDocumentPlacement.Inside, + documentName: "index", + folderName: (apiItem) => ApiItemUtilities.getFileSafeNameForApiItem(apiItem), + headingText: (apiItem) => apiItem.displayName, + }; + /** * "Flat" hierarchy: Packages get their own documents, and all descendent API items are rendered as sections under that document. * @remarks Results in a small number of documents, but can lead to relatively large documents. */ - export const flat = (apiItem: ApiItem): DeepRequired => { - const kind = ApiItemUtilities.getApiItemKind(apiItem); - - switch (kind) { - case ApiItemKind.Package: { - return { - kind: HierarchyKind.Document, - documentName: ApiItemUtilities.getFileSafeNameForApiItem(apiItem), - headingText: apiItem.displayName, - }; - } - default: { - return { - kind: HierarchyKind.Section, - headingText: apiItem.displayName, - }; - } - } + export const flat: Partial = { + [ApiItemKind.Package]: outsideFolderConfig, + + [ApiItemKind.CallSignature]: defaultSectionConfig, + [ApiItemKind.Class]: defaultSectionConfig, + [ApiItemKind.Constructor]: defaultSectionConfig, + [ApiItemKind.ConstructSignature]: defaultSectionConfig, + [ApiItemKind.Enum]: defaultSectionConfig, + [ApiItemKind.EnumMember]: defaultSectionConfig, + [ApiItemKind.Function]: defaultSectionConfig, + [ApiItemKind.IndexSignature]: defaultSectionConfig, + [ApiItemKind.Interface]: defaultSectionConfig, + [ApiItemKind.Method]: defaultSectionConfig, + [ApiItemKind.MethodSignature]: defaultSectionConfig, + [ApiItemKind.Property]: defaultSectionConfig, + [ApiItemKind.PropertySignature]: defaultSectionConfig, + [ApiItemKind.TypeAlias]: defaultSectionConfig, + [ApiItemKind.Variable]: defaultSectionConfig, }; /** * "Sparse" hierarchy: Packages yield folder hierarchy, and all descendent items get their own document under that folder. * @remarks Leads to many documents, but each document is likely to be relatively small. */ - export const sparse = (apiItem: ApiItem): DeepRequired => { - const kind = ApiItemUtilities.getApiItemKind(apiItem); - - switch (kind) { - case ApiItemKind.Package: { - const name = ApiItemUtilities.getFileSafeNameForApiItem(apiItem); - return { - kind: HierarchyKind.Folder, - documentPlacement: FolderDocumentPlacement.Outside, - documentName: name, - folderName: name, - headingText: apiItem.displayName, - }; - } - default: { - return { - kind: HierarchyKind.Document, - headingText: apiItem.displayName, - documentName: apiItem.displayName, - }; - } - } + export const sparse: Partial = { + [ApiItemKind.Package]: outsideFolderConfig, + + [ApiItemKind.CallSignature]: defaultDocumentConfig, + [ApiItemKind.Class]: defaultDocumentConfig, + [ApiItemKind.Constructor]: defaultDocumentConfig, + [ApiItemKind.ConstructSignature]: defaultDocumentConfig, + [ApiItemKind.Enum]: defaultDocumentConfig, + [ApiItemKind.EnumMember]: defaultDocumentConfig, + [ApiItemKind.Function]: defaultDocumentConfig, + [ApiItemKind.IndexSignature]: defaultDocumentConfig, + [ApiItemKind.Interface]: defaultDocumentConfig, + [ApiItemKind.Method]: defaultDocumentConfig, + [ApiItemKind.MethodSignature]: defaultDocumentConfig, + [ApiItemKind.Namespace]: defaultDocumentConfig, + [ApiItemKind.Property]: defaultDocumentConfig, + [ApiItemKind.PropertySignature]: defaultDocumentConfig, + [ApiItemKind.TypeAlias]: defaultDocumentConfig, + [ApiItemKind.Variable]: defaultDocumentConfig, }; /** * "Deep" hierarchy: All "parent" API items generate hierarchy. All other items are rendered as documents under their parent hierarchy. * @remarks Leads to many documents, but each document is likely to be relatively small. */ - export const deep = (apiItem: ApiItem): DeepRequired => { - if (ApiItemContainerMixin.isBaseClassOf(apiItem)) { - const name = ApiItemUtilities.getFileSafeNameForApiItem(apiItem); - return { - kind: HierarchyKind.Folder, - documentPlacement: FolderDocumentPlacement.Inside, - documentName: name, - folderName: name, - headingText: apiItem.displayName, - }; - } else { - return { - kind: HierarchyKind.Document, - headingText: apiItem.displayName, - documentName: apiItem.displayName, - }; - } + export const deep: Partial = { + // Items that introduce folder hierarchy: + [ApiItemKind.Namespace]: insideFolderConfig, + [ApiItemKind.Package]: insideFolderConfig, + [ApiItemKind.Class]: insideFolderConfig, + [ApiItemKind.Enum]: insideFolderConfig, + [ApiItemKind.Interface]: insideFolderConfig, + [ApiItemKind.TypeAlias]: insideFolderConfig, + + // Items that get their own document, but do not introduce folder hierarchy: + [ApiItemKind.CallSignature]: defaultDocumentConfig, + [ApiItemKind.Constructor]: defaultDocumentConfig, + [ApiItemKind.ConstructSignature]: defaultDocumentConfig, + [ApiItemKind.EnumMember]: defaultDocumentConfig, + [ApiItemKind.Function]: defaultDocumentConfig, + [ApiItemKind.IndexSignature]: defaultDocumentConfig, + [ApiItemKind.Method]: defaultDocumentConfig, + [ApiItemKind.MethodSignature]: defaultDocumentConfig, + [ApiItemKind.Property]: defaultDocumentConfig, + [ApiItemKind.PropertySignature]: defaultDocumentConfig, + [ApiItemKind.Variable]: defaultDocumentConfig, }; } diff --git a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts index 7ab24d10b44a..4c3b18f0fb45 100644 --- a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts @@ -95,7 +95,7 @@ const testConfigs: EndToEndTestConfig[] = [ * A sample "deep" configuration, which generates folder hierarchy for any "container" API items. */ { - testName: "sparse-config", + testName: "deep-config", renderConfig: { uriRoot: "docs", includeBreadcrumb: false, diff --git a/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts b/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts index 04a290757a4c..b48c4fe1d588 100644 --- a/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts +++ b/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts @@ -36,6 +36,7 @@ import { import { PackageName } from "@rushstack/node-core-library"; import type { Logger } from "../Logging.js"; +import { getFilteredParent } from "../api-item-transforms/index.js"; /** * This module contains general `ApiItem`-related types and utilities. @@ -50,6 +51,8 @@ export type ValidApiItemKind = Exclude; /** * Gets the {@link ValidApiItemKind} for the provided API item. Throws if the item's kind is "None". + * + * @public */ export function getApiItemKind(apiItem: ApiItem): ValidApiItemKind { switch (apiItem.kind) { @@ -78,7 +81,7 @@ export function getApiItemKind(apiItem: ApiItem): ValidApiItemKind { * * @public */ -export type ApiMemberKind = Omit< +export type ApiMemberKind = Exclude< ApiItemKind, ApiItemKind.EntryPoint | ApiItemKind.Model | ApiItemKind.None | ApiItemKind.Package >; @@ -263,10 +266,12 @@ export function hasModifierTag(apiItem: ApiItem, tagName: string): boolean { * @public */ export function ancestryHasModifierTag(apiItem: ApiItem, tagName: string): boolean { - return ( - hasModifierTag(apiItem, tagName) || - (apiItem.parent !== undefined && ancestryHasModifierTag(apiItem.parent, tagName)) - ); + if (hasModifierTag(apiItem, tagName)) { + return true; + } + + const parent = getFilteredParent(apiItem); + return parent !== undefined && ancestryHasModifierTag(parent, tagName); } /** @@ -546,6 +551,8 @@ export function getConciseSignature(apiItem: ApiItem): string { /** * Gets a filename-safe representation of the API item's display name. + * + * @public */ export function getFileSafeNameForApiItem(apiItem: ApiItem): string { return apiItem.kind === ApiItemKind.Package From 964e4bfe13ffcda2e3ce5d1ab775960e0b57e807 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 18 Dec 2024 00:43:11 +0000 Subject: [PATCH 08/54] docs: Fix comments --- .../src/api-item-transforms/TransformApiModel.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts b/tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts index 22325bd3f84a..e9b910590442 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts @@ -154,7 +154,7 @@ function createDocumentForApiModel( logger.verbose(`Generating API Model document...`); - // Note: We don't render the breadcrumb for Model document, as it is always the root of the file hierarchical + // Note: We don't render the breadcrumb for Model document, as it is always the root of the file hierarchy. // Render body contents const sections = createModelBodySections(apiModel, config); @@ -232,7 +232,7 @@ function createDocumentForMultiEntryPointPackage( sections.push(wrapInSection([createBreadcrumbParagraph(apiPackage, config)])); } - // Render list of entry-points + // Render list of links to entry-points, each of which will get its own document. const renderedEntryPointList = createEntryPointList(apiEntryPoints, config); if (renderedEntryPointList !== undefined) { sections.push( From 600591ab18a75aaaddd453c4a254c6591caf5224 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 18 Dec 2024 00:50:18 +0000 Subject: [PATCH 09/54] fix: Correct handling of entry-points --- .../api-report/api-markdown-documenter.alpha.api.md | 2 +- .../api-report/api-markdown-documenter.beta.api.md | 2 +- .../api-report/api-markdown-documenter.public.api.md | 2 +- .../api-item-transforms/configuration/HierarchyOptions.ts | 7 ++++--- 4 files changed, 7 insertions(+), 6 deletions(-) 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 7cd5ff932b72..1278af522cb0 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 @@ -479,7 +479,7 @@ export type HierarchyOptions = { } & { [ApiItemKind.Model]: DocumentHierarchyConfig; [ApiItemKind.Package]: FolderHierarchyConfig; - [ApiItemKind.EntryPoint]: SectionHierarchyConfig; + [ApiItemKind.EntryPoint]: DocumentHierarchyConfig; }; // @public 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 f6bc06b9094a..d236e0a2e6a2 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 @@ -479,7 +479,7 @@ export type HierarchyOptions = { } & { [ApiItemKind.Model]: DocumentHierarchyConfig; [ApiItemKind.Package]: FolderHierarchyConfig; - [ApiItemKind.EntryPoint]: SectionHierarchyConfig; + [ApiItemKind.EntryPoint]: DocumentHierarchyConfig; }; // @public 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 180a0bf37422..b1cda53a9012 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 @@ -479,7 +479,7 @@ export type HierarchyOptions = { } & { [ApiItemKind.Model]: DocumentHierarchyConfig; [ApiItemKind.Package]: FolderHierarchyConfig; - [ApiItemKind.EntryPoint]: SectionHierarchyConfig; + [ApiItemKind.EntryPoint]: DocumentHierarchyConfig; }; // @public diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts index 461e09708d13..72566a5d4ffe 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts @@ -260,9 +260,10 @@ export type HierarchyOptions = { /** * Hierarchy configuration for the `EntryPoint` API item kind. * - * @remarks Always a section under the parent (package) document. + * @remarks Always its own document, adjacent to the package document. + * @privateRemarks TODO: Make this fully configurable - there is no real reason for this policy to be baked in. */ - [ApiItemKind.EntryPoint]: SectionHierarchyConfig; + [ApiItemKind.EntryPoint]: DocumentHierarchyConfig; }; /** @@ -282,6 +283,7 @@ export const defaultHierarchyOptions: HierarchyOptions = { // Items that get their own document, but do not introduce folder hierarchy: [ApiItemKind.Class]: defaultDocumentHierarchyConfig, [ApiItemKind.Enum]: defaultSectionHierarchyConfig, // TODO: DocumentHierarchyConfig + [ApiItemKind.EntryPoint]: defaultDocumentHierarchyConfig, [ApiItemKind.Interface]: defaultDocumentHierarchyConfig, [ApiItemKind.TypeAlias]: defaultSectionHierarchyConfig, // TODO: DocumentHierarchyConfig @@ -290,7 +292,6 @@ export const defaultHierarchyOptions: HierarchyOptions = { [ApiItemKind.Constructor]: defaultSectionHierarchyConfig, [ApiItemKind.ConstructSignature]: defaultSectionHierarchyConfig, [ApiItemKind.EnumMember]: defaultSectionHierarchyConfig, - [ApiItemKind.EntryPoint]: defaultSectionHierarchyConfig, [ApiItemKind.Function]: defaultSectionHierarchyConfig, [ApiItemKind.IndexSignature]: defaultSectionHierarchyConfig, [ApiItemKind.Method]: defaultSectionHierarchyConfig, From 571c1703351c3e9f35365ac5f19a9fd14fb6cb15 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 18 Dec 2024 00:52:29 +0000 Subject: [PATCH 10/54] fix: Types --- tools/api-markdown-documenter/src/test/EndToEndTests.ts | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/tools/api-markdown-documenter/src/test/EndToEndTests.ts b/tools/api-markdown-documenter/src/test/EndToEndTests.ts index 24612b20057c..3ea8ff4531b4 100644 --- a/tools/api-markdown-documenter/src/test/EndToEndTests.ts +++ b/tools/api-markdown-documenter/src/test/EndToEndTests.ts @@ -22,7 +22,6 @@ import { transformApiModel, type MarkdownRenderer, type HtmlRenderer, - type ApiItemTransformationConfiguration, type ApiItemTransformationOptions, type FolderHierarchyConfig, type SectionHierarchyConfig, @@ -145,13 +144,13 @@ export function endToEndTests( ); describe(testConfig.testName, () => { - let config: ApiItemTransformationConfiguration & TRenderConfig; + let config: ApiItemTransformationOptions & TRenderConfig; before(async () => { config = { ...testConfig.renderConfig, apiModel, outputDirectoryPath: temporaryDirectoryPath, - } as unknown as ApiItemTransformationConfiguration & TRenderConfig; + } as unknown as ApiItemTransformationOptions & TRenderConfig; }); // Run a sanity check to ensure that the suite did not generate multiple documents with the same From 63f253d63de041ddc5d78b768b47aed1e5f9149d Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 18 Dec 2024 00:55:02 +0000 Subject: [PATCH 11/54] refactor: Rename interface --- .../api-markdown-documenter.alpha.api.md | 22 +++++++++---------- .../api-markdown-documenter.beta.api.md | 22 +++++++++---------- .../api-markdown-documenter.public.api.md | 20 ++++++++--------- .../src/LintApiModel.ts | 4 ++-- .../api-markdown-documenter/src/LoadModel.ts | 4 ++-- ...ConfigurationBase.ts => LoggingOptions.ts} | 6 ++--- .../TsdocNodeTransforms.ts | 4 ++-- .../configuration/Configuration.ts | 6 ++--- .../configuration/Configuration.ts | 4 ++-- tools/api-markdown-documenter/src/index.ts | 2 +- .../configuration/Configuration.ts | 4 ++-- 11 files changed, 48 insertions(+), 50 deletions(-) rename tools/api-markdown-documenter/src/{ConfigurationBase.ts => LoggingOptions.ts} (75%) 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 1278af522cb0..f1dbfae11755 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 @@ -48,7 +48,7 @@ export { ApiItem } export { ApiItemKind } // @public -export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, Required, DocumentationSuiteConfiguration, Required { +export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, Required, DocumentationSuiteConfiguration, Required { } // @public @@ -58,7 +58,7 @@ export interface ApiItemTransformationConfigurationBase { } // @public -export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, ApiItemTransformations, DocumentationSuiteOptions, ConfigurationBase { +export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, ApiItemTransformations, DocumentationSuiteOptions, LoggingOptions { } // @public @@ -153,11 +153,6 @@ export class CodeSpanNode extends DocumentationParentNodeBase; // @beta -export interface LintApiModelConfiguration extends ConfigurationBase { +export interface LintApiModelConfiguration extends LoggingOptions { apiModel: ApiModel; } @@ -587,7 +582,7 @@ export interface LinterReferenceError { export function loadModel(options: LoadModelOptions): Promise; // @public -export interface LoadModelOptions extends ConfigurationBase { +export interface LoadModelOptions extends LoggingOptions { readonly modelDirectoryPath: string; } @@ -604,7 +599,12 @@ export interface Logger { export type LoggingFunction = (message: string | Error, ...parameters: unknown[]) => void; // @public -export interface MarkdownRenderConfiguration extends ConfigurationBase { +export interface LoggingOptions { + readonly logger?: Logger; +} + +// @public +export interface MarkdownRenderConfiguration extends LoggingOptions { readonly customRenderers?: MarkdownRenderers; readonly startingHeadingLevel?: number; } @@ -839,7 +839,7 @@ export interface TextFormatting { } // @public -export interface ToHtmlConfig extends ConfigurationBase { +export interface ToHtmlConfig extends LoggingOptions { readonly customTransformations?: ToHtmlTransformations; readonly language?: string; readonly rootFormatting?: TextFormatting; 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 d236e0a2e6a2..8482155faba2 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 @@ -48,7 +48,7 @@ export { ApiItem } export { ApiItemKind } // @public -export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, Required, DocumentationSuiteConfiguration, Required { +export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, Required, DocumentationSuiteConfiguration, Required { } // @public @@ -58,7 +58,7 @@ export interface ApiItemTransformationConfigurationBase { } // @public -export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, ApiItemTransformations, DocumentationSuiteOptions, ConfigurationBase { +export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, ApiItemTransformations, DocumentationSuiteOptions, LoggingOptions { } // @public @@ -153,11 +153,6 @@ export class CodeSpanNode extends DocumentationParentNodeBase; // @beta -export interface LintApiModelConfiguration extends ConfigurationBase { +export interface LintApiModelConfiguration extends LoggingOptions { apiModel: ApiModel; } @@ -587,7 +582,7 @@ export interface LinterReferenceError { export function loadModel(options: LoadModelOptions): Promise; // @public -export interface LoadModelOptions extends ConfigurationBase { +export interface LoadModelOptions extends LoggingOptions { readonly modelDirectoryPath: string; } @@ -604,7 +599,12 @@ export interface Logger { export type LoggingFunction = (message: string | Error, ...parameters: unknown[]) => void; // @public -export interface MarkdownRenderConfiguration extends ConfigurationBase { +export interface LoggingOptions { + readonly logger?: Logger; +} + +// @public +export interface MarkdownRenderConfiguration extends LoggingOptions { readonly customRenderers?: MarkdownRenderers; readonly startingHeadingLevel?: number; } @@ -825,7 +825,7 @@ export interface TextFormatting { } // @public -export interface ToHtmlConfig extends ConfigurationBase { +export interface ToHtmlConfig extends LoggingOptions { readonly customTransformations?: ToHtmlTransformations; readonly language?: string; readonly rootFormatting?: TextFormatting; 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 b1cda53a9012..c2fa790f9de8 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 @@ -48,7 +48,7 @@ export { ApiItem } export { ApiItemKind } // @public -export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, Required, DocumentationSuiteConfiguration, Required { +export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, Required, DocumentationSuiteConfiguration, Required { } // @public @@ -58,7 +58,7 @@ export interface ApiItemTransformationConfigurationBase { } // @public -export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, ApiItemTransformations, DocumentationSuiteOptions, ConfigurationBase { +export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, ApiItemTransformations, DocumentationSuiteOptions, LoggingOptions { } // @public @@ -153,11 +153,6 @@ export class CodeSpanNode extends DocumentationParentNodeBase; // @public -export interface LoadModelOptions extends ConfigurationBase { +export interface LoadModelOptions extends LoggingOptions { readonly modelDirectoryPath: string; } @@ -582,7 +577,12 @@ export interface Logger { export type LoggingFunction = (message: string | Error, ...parameters: unknown[]) => void; // @public -export interface MarkdownRenderConfiguration extends ConfigurationBase { +export interface LoggingOptions { + readonly logger?: Logger; +} + +// @public +export interface MarkdownRenderConfiguration extends LoggingOptions { readonly customRenderers?: MarkdownRenderers; readonly startingHeadingLevel?: number; } @@ -803,7 +803,7 @@ export interface TextFormatting { } // @public -export interface ToHtmlConfig extends ConfigurationBase { +export interface ToHtmlConfig extends LoggingOptions { readonly customTransformations?: ToHtmlTransformations; readonly language?: string; readonly rootFormatting?: TextFormatting; diff --git a/tools/api-markdown-documenter/src/LintApiModel.ts b/tools/api-markdown-documenter/src/LintApiModel.ts index bce345e7b5c4..2620e68d9c84 100644 --- a/tools/api-markdown-documenter/src/LintApiModel.ts +++ b/tools/api-markdown-documenter/src/LintApiModel.ts @@ -22,8 +22,8 @@ import { DocNodeKind, } from "@microsoft/tsdoc"; -import type { ConfigurationBase } from "./ConfigurationBase.js"; import { defaultConsoleLogger } from "./Logging.js"; +import type { LoggingOptions } from "./LoggingOptions.js"; import { resolveSymbolicReference } from "./utilities/index.js"; /** @@ -31,7 +31,7 @@ import { resolveSymbolicReference } from "./utilities/index.js"; * * @beta */ -export interface LintApiModelConfiguration extends ConfigurationBase { +export interface LintApiModelConfiguration extends LoggingOptions { /** * The API model to lint. */ diff --git a/tools/api-markdown-documenter/src/LoadModel.ts b/tools/api-markdown-documenter/src/LoadModel.ts index 2e0fad5a877c..72793dde8e18 100644 --- a/tools/api-markdown-documenter/src/LoadModel.ts +++ b/tools/api-markdown-documenter/src/LoadModel.ts @@ -15,15 +15,15 @@ import { import type { DocComment, DocInheritDocTag } from "@microsoft/tsdoc"; import { FileSystem } from "@rushstack/node-core-library"; -import type { ConfigurationBase } from "./ConfigurationBase.js"; import { defaultConsoleLogger, type Logger } from "./Logging.js"; +import type { LoggingOptions } from "./LoggingOptions.js"; /** * {@link loadModel} options. * * @public */ -export interface LoadModelOptions extends ConfigurationBase { +export interface LoadModelOptions extends LoggingOptions { /** * Path to the API model directory. * I.e., the directory containing the set of `.api.json` files that comprise the API model. diff --git a/tools/api-markdown-documenter/src/ConfigurationBase.ts b/tools/api-markdown-documenter/src/LoggingOptions.ts similarity index 75% rename from tools/api-markdown-documenter/src/ConfigurationBase.ts rename to tools/api-markdown-documenter/src/LoggingOptions.ts index 5dcb4e459f6b..4aeb5ef1b154 100644 --- a/tools/api-markdown-documenter/src/ConfigurationBase.ts +++ b/tools/api-markdown-documenter/src/LoggingOptions.ts @@ -6,13 +6,11 @@ import type { Logger } from "./Logging.js"; /** - * Common base interface for configuration interfaces. - * - * @privateRemarks TODO: Re-express as "WithLogger" instead of "ConfigurationBase" + * Common base interface for configurations that take a logger. * * @public */ -export interface ConfigurationBase { +export interface LoggingOptions { /** * Optional receiver of system log data. * diff --git a/tools/api-markdown-documenter/src/api-item-transforms/TsdocNodeTransforms.ts b/tools/api-markdown-documenter/src/api-item-transforms/TsdocNodeTransforms.ts index e757f3cc9374..5a4df098a3de 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/TsdocNodeTransforms.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/TsdocNodeTransforms.ts @@ -20,8 +20,8 @@ import { type DocHtmlStartTag, } from "@microsoft/tsdoc"; -import type { ConfigurationBase } from "../ConfigurationBase.js"; import type { Link } from "../Link.js"; +import type { LoggingOptions } from "../LoggingOptions.js"; import { CodeSpanNode, type DocumentationNode, @@ -70,7 +70,7 @@ export function transformTsdocNode( /** * Options for {@link @microsoft/tsdoc#DocNode} transformations. */ -export interface TsdocNodeTransformOptions extends ConfigurationBase { +export interface TsdocNodeTransformOptions extends LoggingOptions { /** * The API item with which the documentation node(s) are associated. */ diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts index 9064753b24b0..d2fdc779610e 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts @@ -5,8 +5,8 @@ import type { ApiModel } from "@microsoft/api-extractor-model"; -import type { ConfigurationBase } from "../../ConfigurationBase.js"; import { defaultConsoleLogger } from "../../Logging.js"; +import type { LoggingOptions } from "../../LoggingOptions.js"; import { type DocumentationSuiteConfiguration, @@ -51,7 +51,7 @@ export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, ApiItemTransformations, DocumentationSuiteOptions, - ConfigurationBase {} + LoggingOptions {} /** * Complete API Item transformation configuration. @@ -62,7 +62,7 @@ export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, Required, DocumentationSuiteConfiguration, - Required {} + Required {} /** * Gets a complete {@link ApiItemTransformationConfiguration} using the provided partial configuration, and filling diff --git a/tools/api-markdown-documenter/src/documentation-domain-to-html/configuration/Configuration.ts b/tools/api-markdown-documenter/src/documentation-domain-to-html/configuration/Configuration.ts index 37c5d6052753..918f4729b0ec 100644 --- a/tools/api-markdown-documenter/src/documentation-domain-to-html/configuration/Configuration.ts +++ b/tools/api-markdown-documenter/src/documentation-domain-to-html/configuration/Configuration.ts @@ -3,8 +3,8 @@ * Licensed under the MIT License. */ -import type { ConfigurationBase } from "../../ConfigurationBase.js"; import { defaultConsoleLogger } from "../../Logging.js"; +import type { LoggingOptions } from "../../LoggingOptions.js"; import type { TextFormatting } from "../../documentation-domain/index.js"; import type { Transformations } from "./Transformation.js"; @@ -14,7 +14,7 @@ import type { Transformations } from "./Transformation.js"; * * @public */ -export interface TransformationConfig extends ConfigurationBase { +export interface TransformationConfig extends LoggingOptions { /** * User-specified transformations. * diff --git a/tools/api-markdown-documenter/src/index.ts b/tools/api-markdown-documenter/src/index.ts index 09bb1bec35df..ecd735a33ccb 100644 --- a/tools/api-markdown-documenter/src/index.ts +++ b/tools/api-markdown-documenter/src/index.ts @@ -61,7 +61,7 @@ export { type MarkdownRenderers, type MarkdownRenderConfiguration, } from "./renderers/index.js"; -export type { ConfigurationBase } from "./ConfigurationBase.js"; +export type { LoggingOptions } from "./LoggingOptions.js"; export type { FileSystemConfiguration } from "./FileSystemConfiguration.js"; export type { Heading } from "./Heading.js"; export type { Link, UrlTarget } from "./Link.js"; diff --git a/tools/api-markdown-documenter/src/renderers/markdown-renderer/configuration/Configuration.ts b/tools/api-markdown-documenter/src/renderers/markdown-renderer/configuration/Configuration.ts index d97838080b55..2d9f37722fb7 100644 --- a/tools/api-markdown-documenter/src/renderers/markdown-renderer/configuration/Configuration.ts +++ b/tools/api-markdown-documenter/src/renderers/markdown-renderer/configuration/Configuration.ts @@ -3,8 +3,8 @@ * Licensed under the MIT License. */ -import type { ConfigurationBase } from "../../../ConfigurationBase.js"; import { defaultConsoleLogger } from "../../../Logging.js"; +import type { LoggingOptions } from "../../../LoggingOptions.js"; import type { Renderers } from "./RenderOptions.js"; @@ -13,7 +13,7 @@ import type { Renderers } from "./RenderOptions.js"; * * @public */ -export interface RenderConfiguration extends ConfigurationBase { +export interface RenderConfiguration extends LoggingOptions { /** * User-specified renderers. * From 824c7f0cf5801bf49dab4f6b581090ca9ab7a7a5 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 18 Dec 2024 02:16:45 +0000 Subject: [PATCH 12/54] fix: End-to-end tests --- .../api-markdown-documenter.alpha.api.md | 6 +- .../api-markdown-documenter.beta.api.md | 4 +- .../api-markdown-documenter.public.api.md | 4 +- .../api-markdown-documenter/src/RenderHtml.ts | 2 +- .../src/RenderMarkdown.ts | 2 +- .../api-item-transforms/TransformApiModel.ts | 31 +-- .../src/api-item-transforms/Utilities.ts | 41 ++++ .../configuration/Configuration.ts | 2 +- .../src/api-item-transforms/index.ts | 1 + ...ToEndTests.ts => EndToEndTestUtilities.ts} | 183 ++---------------- .../src/test/HtmlEndToEnd.test.ts | 164 +++++++--------- .../src/test/MarkdownEndToEnd.test.ts | 144 +++++++------- .../test/TransformApiModelEndToEnd.test.ts | 75 +++++++ 13 files changed, 296 insertions(+), 363 deletions(-) rename tools/api-markdown-documenter/src/test/{EndToEndTests.ts => EndToEndTestUtilities.ts} (52%) create mode 100644 tools/api-markdown-documenter/src/test/TransformApiModelEndToEnd.test.ts 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 f1dbfae11755..45a5602b9be3 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 @@ -383,7 +383,7 @@ export interface FolderHierarchyOptions extends DocumentHierarchyOptions { function getApiItemKind(apiItem: ApiItem): ValidApiItemKind; // @public -export function getApiItemTransformationConfigurationWithDefaults(inputOptions: ApiItemTransformationOptions): Required; +export function getApiItemTransformationConfigurationWithDefaults(inputOptions: ApiItemTransformationOptions): ApiItemTransformationConfiguration; // @public function getCustomBlockComments(apiItem: ApiItem): ReadonlyMap; @@ -698,14 +698,14 @@ export interface RenderDocumentAsHtmlConfig extends ToHtmlConfig, RenderHtmlConf } // @alpha -function renderDocumentsAsHtml(documents: DocumentNode[], options: RenderDocumentsAsHtmlOptions): Promise; +function renderDocumentsAsHtml(documents: readonly DocumentNode[], options: RenderDocumentsAsHtmlOptions): Promise; // @alpha interface RenderDocumentsAsHtmlOptions extends RenderDocumentAsHtmlConfig, FileSystemConfiguration { } // @public -function renderDocumentsAsMarkdown(documents: DocumentNode[], options: RenderDocumentsAsMarkdownOptions): Promise; +function renderDocumentsAsMarkdown(documents: readonly DocumentNode[], options: RenderDocumentsAsMarkdownOptions): Promise; // @public interface RenderDocumentsAsMarkdownOptions extends MarkdownRenderConfiguration, FileSystemConfiguration { 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 8482155faba2..a85e97fe53ff 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 @@ -383,7 +383,7 @@ export interface FolderHierarchyOptions extends DocumentHierarchyOptions { function getApiItemKind(apiItem: ApiItem): ValidApiItemKind; // @public -export function getApiItemTransformationConfigurationWithDefaults(inputOptions: ApiItemTransformationOptions): Required; +export function getApiItemTransformationConfigurationWithDefaults(inputOptions: ApiItemTransformationOptions): ApiItemTransformationConfiguration; // @public function getCustomBlockComments(apiItem: ApiItem): ReadonlyMap; @@ -691,7 +691,7 @@ export interface RenderDocumentAsHtmlConfig extends ToHtmlConfig, RenderHtmlConf } // @public -function renderDocumentsAsMarkdown(documents: DocumentNode[], options: RenderDocumentsAsMarkdownOptions): Promise; +function renderDocumentsAsMarkdown(documents: readonly DocumentNode[], options: RenderDocumentsAsMarkdownOptions): Promise; // @public interface RenderDocumentsAsMarkdownOptions extends MarkdownRenderConfiguration, FileSystemConfiguration { 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 c2fa790f9de8..adff06ec8a19 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 @@ -383,7 +383,7 @@ export interface FolderHierarchyOptions extends DocumentHierarchyOptions { function getApiItemKind(apiItem: ApiItem): ValidApiItemKind; // @public -export function getApiItemTransformationConfigurationWithDefaults(inputOptions: ApiItemTransformationOptions): Required; +export function getApiItemTransformationConfigurationWithDefaults(inputOptions: ApiItemTransformationOptions): ApiItemTransformationConfiguration; // @public function getCustomBlockComments(apiItem: ApiItem): ReadonlyMap; @@ -669,7 +669,7 @@ export interface RenderDocumentAsHtmlConfig extends ToHtmlConfig, RenderHtmlConf } // @public -function renderDocumentsAsMarkdown(documents: DocumentNode[], options: RenderDocumentsAsMarkdownOptions): Promise; +function renderDocumentsAsMarkdown(documents: readonly DocumentNode[], options: RenderDocumentsAsMarkdownOptions): Promise; // @public interface RenderDocumentsAsMarkdownOptions extends MarkdownRenderConfiguration, FileSystemConfiguration { diff --git a/tools/api-markdown-documenter/src/RenderHtml.ts b/tools/api-markdown-documenter/src/RenderHtml.ts index 093093e83658..5980faa4f4fa 100644 --- a/tools/api-markdown-documenter/src/RenderHtml.ts +++ b/tools/api-markdown-documenter/src/RenderHtml.ts @@ -54,7 +54,7 @@ export interface RenderDocumentsAsHtmlOptions * @alpha */ export async function renderDocumentsAsHtml( - documents: DocumentNode[], + documents: readonly DocumentNode[], options: RenderDocumentsAsHtmlOptions, ): Promise { const { logger, newlineKind, outputDirectoryPath } = options; diff --git a/tools/api-markdown-documenter/src/RenderMarkdown.ts b/tools/api-markdown-documenter/src/RenderMarkdown.ts index b0218b4759a6..555b73e6eb8e 100644 --- a/tools/api-markdown-documenter/src/RenderMarkdown.ts +++ b/tools/api-markdown-documenter/src/RenderMarkdown.ts @@ -56,7 +56,7 @@ export interface RenderDocumentsAsMarkdownOptions * @public */ export async function renderDocumentsAsMarkdown( - documents: DocumentNode[], + documents: readonly DocumentNode[], options: RenderDocumentsAsMarkdownOptions, ): Promise { const { logger, newlineKind, outputDirectoryPath } = options; diff --git a/tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts b/tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts index e9b910590442..5d41ffaff17e 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts @@ -9,7 +9,7 @@ import type { DocumentNode, SectionNode } from "../documentation-domain/index.js import { doesItemRequireOwnDocument, shouldItemBeIncluded } from "./ApiItemTransformUtilities.js"; import { apiItemToDocument, apiItemToSections } from "./TransformApiItem.js"; -import { createDocument } from "./Utilities.js"; +import { checkForDuplicateDocumentPaths, createDocument } from "./Utilities.js"; import { type ApiItemTransformationConfiguration, type ApiItemTransformationOptions, @@ -33,10 +33,10 @@ export function transformApiModel(transformConfig: ApiItemTransformationOptions) // If a package has multiple entry-points, it's possible for the same API item to appear under more than one // entry-point (i.e., we are traversing a graph, rather than a tree). // To avoid redundant computation, we will keep a ledger of which API items we have transformed. - const documents: Map = new Map(); + const documentsMap: Map = new Map(); // Always render Model document (this is the "root" of the generated documentation suite). - documents.set(apiModel, createDocumentForApiModel(apiModel, completeConfig)); + documentsMap.set(apiModel, createDocumentForApiModel(apiModel, completeConfig)); const packages = apiModel.packages; @@ -71,22 +71,22 @@ export function transformApiModel(transformConfig: ApiItemTransformationOptions) const entryPoint = packageEntryPoints[0]; - documents.set( + documentsMap.set( packageItem, createDocumentForSingleEntryPointPackage(packageItem, entryPoint, completeConfig), ); const packageDocumentItems = getDocumentItems(entryPoint, completeConfig); for (const apiItem of packageDocumentItems) { - if (!documents.has(apiItem)) { - documents.set(apiItem, apiItemToDocument(apiItem, completeConfig)); + if (!documentsMap.has(apiItem)) { + documentsMap.set(apiItem, apiItemToDocument(apiItem, completeConfig)); } } } else { // If a package contains multiple entry-points, we will generate a separate document for each. // The package-level document will enumerate the entry-points. - documents.set( + documentsMap.set( packageItem, createDocumentForMultiEntryPointPackage( packageItem, @@ -96,24 +96,31 @@ export function transformApiModel(transformConfig: ApiItemTransformationOptions) ); for (const entryPoint of packageEntryPoints) { - documents.set( + documentsMap.set( entryPoint, createDocumentForApiEntryPoint(entryPoint, completeConfig), ); const packageDocumentItems = getDocumentItems(entryPoint, completeConfig); for (const apiItem of packageDocumentItems) { - if (!documents.has(apiItem)) { - documents.set(apiItem, apiItemToDocument(apiItem, completeConfig)); + if (!documentsMap.has(apiItem)) { + documentsMap.set(apiItem, apiItemToDocument(apiItem, completeConfig)); } } } } } - logger.success("API Model documents generated!"); + const documents = [...documentsMap.values()]; + + try { + checkForDuplicateDocumentPaths(documents); + } catch (error: unknown) { + logger.warning((error as Error).message); + } - return [...documents.values()]; + logger.success("API Model documents generated!"); + return documents; } /** diff --git a/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts b/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts index 10e90e02a07f..78045146c2e4 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts @@ -99,3 +99,44 @@ function resolveSymbolicLink( return getLinkForApiItem(resolvedReference, config); } + +/** + * Checks for duplicate {@link DocumentNode.documentPath}s among the provided set of documents. + * @throws If any duplicates are found. + */ +export function checkForDuplicateDocumentPaths(documents: readonly DocumentNode[]): void { + const documentPathMap = new Map(); + for (const document of documents) { + let entries = documentPathMap.get(document.documentPath); + if (entries === undefined) { + entries = []; + documentPathMap.set(document.documentPath, entries); + } + entries.push(document); + } + + const duplicates = [...documentPathMap.entries()].filter( + ([, documentsUnderPath]) => documentsUnderPath.length > 1, + ); + + if (duplicates.length === 0) { + return; + } + + const errorMessageLines = ["Duplicate output paths found among the generated documents:"]; + + for (const [documentPath, documentsUnderPath] of duplicates) { + errorMessageLines.push(`- ${documentPath}`); + for (const document of documentsUnderPath) { + const errorEntry = document.apiItem + ? `${document.apiItem.displayName} (${document.apiItem.kind})` + : "(No corresponding API item)"; + errorMessageLines.push(` - ${errorEntry}`); + } + } + errorMessageLines.push( + "Check your configuration to ensure different API items do not result in the same output path.", + ); + + throw new Error(errorMessageLines.join("\n")); +} diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts index d2fdc779610e..6a87d5da9039 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts @@ -72,7 +72,7 @@ export interface ApiItemTransformationConfiguration */ export function getApiItemTransformationConfigurationWithDefaults( inputOptions: ApiItemTransformationOptions, -): Required { +): ApiItemTransformationConfiguration { const logger = inputOptions.logger ?? defaultConsoleLogger; const documentationSuiteOptions = getDocumentationSuiteConfigurationWithDefaults(inputOptions); const transformationOptions = getApiItemTransformationsWithDefaults(inputOptions); diff --git a/tools/api-markdown-documenter/src/api-item-transforms/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/index.ts index 3c7029ef071d..88bddb07c825 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/index.ts @@ -55,3 +55,4 @@ export { export { transformTsdocNode } from "./TsdocNodeTransforms.js"; export { apiItemToDocument, apiItemToSections } from "./TransformApiItem.js"; export { transformApiModel } from "./TransformApiModel.js"; +export { checkForDuplicateDocumentPaths } from "./Utilities.js"; diff --git a/tools/api-markdown-documenter/src/test/EndToEndTests.ts b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts similarity index 52% rename from tools/api-markdown-documenter/src/test/EndToEndTests.ts rename to tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts index 3ea8ff4531b4..59e1fbe6a746 100644 --- a/tools/api-markdown-documenter/src/test/EndToEndTests.ts +++ b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts @@ -4,200 +4,41 @@ */ import Path from "node:path"; +import { fileURLToPath } from "node:url"; -import { ApiItemKind, type ApiModel } from "@microsoft/api-extractor-model"; +import { ApiItemKind } from "@microsoft/api-extractor-model"; import { FileSystem } from "@rushstack/node-core-library"; import { expect } from "chai"; import { compare } from "dir-compare"; -import type { Suite } from "mocha"; import { ApiItemUtilities, - loadModel, type DocumentHierarchyConfig, - type DocumentNode, FolderDocumentPlacement, HierarchyKind, type HierarchyOptions, - transformApiModel, - type MarkdownRenderer, - type HtmlRenderer, - type ApiItemTransformationOptions, type FolderHierarchyConfig, type SectionHierarchyConfig, } from "../index.js"; -/** - * Supported render configuration types. - */ -export type RenderConfig = - | MarkdownRenderer.RenderDocumentsOptions - | HtmlRenderer.RenderDocumentsOptions; +const dirname = Path.dirname(fileURLToPath(import.meta.url)); /** - * End-to-end snapshot test configuration. - * - * @remarks Generates a test suite with a test for each combination of API Model and test configuration. + * Temp directory under which all tests that generate files will output their contents. */ -export interface EndToEndSuiteConfig { - /** - * Name of the outer test suite. - */ - readonly suiteName: string; - - /** - * Path to the directory where all suite test output will be written for comparison against checked-in snapshots. - * - * @remarks - * Individual tests' output will be written to `/<{@link ApiModelTestOptions.modelName}>/<{@link ApiItemTransformationTestOptions.configName}>/<{@link RenderTestOptions.configName}>`. - */ - readonly temporaryOutputDirectoryPath: string; - - /** - * Path to the directory containing the checked-in snapshots for comparison in this suite. - * - * @remarks - * Individual tests' output will be written to `/<{@link ApiModelTestOptions.modelName}>/<{@link ApiItemTransformationTestOptions.configName}>/<{@link RenderTestOptions.configName}>`. - */ - readonly snapshotsDirectoryPath: string; - - /** - * The end-to-end test scenario to run against the API model. - * Writes the output to the specified directory for snapshot comparison. - */ - render(document: DocumentNode, config: TRenderConfig): Promise; - - /** - * The models to test. - */ - readonly apiModels: readonly ApiModelTestOptions[]; - - /** - * Test configurations to run against each API Model. - */ - readonly testConfigs: readonly EndToEndTestConfig[]; -} - -/** - * API Model test options for a test. - */ -export interface ApiModelTestOptions { - /** - * Name of the API Model being tested. - */ - readonly modelName: string; - - /** - * Path to the directory containing the API Model. - */ - readonly directoryPath: string; -} +export const testTemporaryDirectoryPath = Path.resolve(dirname, "test_temp"); /** - * API Item transformation options for a test. + * Snapshot directory to which generated test data will be copied. + * @remarks Relative to lib/test */ -export interface EndToEndTestConfig { - /** - * Test name - */ - readonly testName: string; - - /** - * Transformation / render configuration - */ - readonly renderConfig: Omit & - Omit; -} +export const snapshotsDirectoryPath = Path.resolve(dirname, "..", "..", "src", "test", "snapshots"); /** - * Generates a test suite that performs end-to-end tests for each test - * configuration x API Model combination. - * - * @remarks - * The generated test suite will include the following checks: - * - * - Basic smoke-test validation of the API Item transformation step, ensuring unique document paths. - * - * - Snapshot test comparing the final rendered output against checked-in snapshots. + * Directory containing the end-to-end test models. + * @remarks Relative to lib/test */ -export function endToEndTests( - suiteConfig: EndToEndSuiteConfig, -): Suite { - return describe(suiteConfig.suiteName, () => { - for (const apiModelTestConfig of suiteConfig.apiModels) { - const { modelName, directoryPath: modelDirectoryPath } = apiModelTestConfig; - describe(modelName, () => { - let apiModel: ApiModel; - before(async () => { - apiModel = await loadModel({ modelDirectoryPath }); - }); - - for (const testConfig of suiteConfig.testConfigs) { - const testOutputPath = Path.join(modelName, testConfig.testName); - const temporaryDirectoryPath = Path.resolve( - suiteConfig.temporaryOutputDirectoryPath, - testOutputPath, - ); - const snapshotDirectoryPath = Path.resolve( - suiteConfig.snapshotsDirectoryPath, - testOutputPath, - ); - - describe(testConfig.testName, () => { - let config: ApiItemTransformationOptions & TRenderConfig; - before(async () => { - config = { - ...testConfig.renderConfig, - apiModel, - outputDirectoryPath: temporaryDirectoryPath, - } as unknown as ApiItemTransformationOptions & TRenderConfig; - }); - - // Run a sanity check to ensure that the suite did not generate multiple documents with the same - // output file path. This either indicates a bug in the system, or an bad configuration. - it("Ensure no duplicate file paths", () => { - const documents = transformApiModel(config); - - const pathMap = new Map(); - for (const document of documents) { - if (pathMap.has(document.documentPath)) { - expect.fail( - `Rendering generated multiple documents to be rendered to the same file path.`, - ); - } else { - pathMap.set(document.documentPath, document); - } - } - }); - - // Perform actual output snapshot comparison test against checked-in test collateral. - it("Snapshot test", async () => { - // Ensure the output temp and snapshots directories exists (will create an empty ones if they don't). - await FileSystem.ensureFolderAsync(temporaryDirectoryPath); - await FileSystem.ensureFolderAsync(snapshotDirectoryPath); - - // Clear any existing test_temp data - await FileSystem.ensureEmptyFolderAsync(temporaryDirectoryPath); - - const documents = transformApiModel(config); - - await Promise.all( - documents.map(async (document) => - suiteConfig.render(document, config), - ), - ); - - await compareDocumentationSuiteSnapshot( - snapshotDirectoryPath, - temporaryDirectoryPath, - ); - }); - }); - } - }); - } - }); -} +export const testDataDirectoryPath = Path.resolve(dirname, "..", "..", "src", "test", "test-data"); /** * Test hierarchy configs @@ -322,7 +163,7 @@ export namespace HierarchyConfigs { * @param temporaryDirectoryPath - Resolved path to the directory containing the freshly generated test output. * Represents the "actual" test output. */ -async function compareDocumentationSuiteSnapshot( +export async function compareDocumentationSuiteSnapshot( snapshotDirectoryPath: string, temporaryDirectoryPath: string, ): Promise { diff --git a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts index 4c3b18f0fb45..55e6db45e280 100644 --- a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts @@ -3,100 +3,63 @@ * Licensed under the MIT License. */ -import * as Path from "node:path"; -import { fileURLToPath } from "node:url"; +import Path from "node:path"; -import { ReleaseTag } from "@microsoft/api-extractor-model"; -import { FileSystem, NewlineKind } from "@rushstack/node-core-library"; +import { ReleaseTag, type ApiModel } from "@microsoft/api-extractor-model"; -import { type DocumentNode, HtmlRenderer } from "../index.js"; +import { HtmlRenderer, loadModel } from "../index.js"; import { - endToEndTests, + compareDocumentationSuiteSnapshot, HierarchyConfigs, - type ApiModelTestOptions, - type EndToEndTestConfig, -} from "./EndToEndTests.js"; - -const dirname = Path.dirname(fileURLToPath(import.meta.url)); + snapshotsDirectoryPath as snapshotsDirectoryPathBase, + testDataDirectoryPath, + testTemporaryDirectoryPath as testTemporaryDirectoryPathBase, +} from "./EndToEndTestUtilities.js"; /** * Temp directory under which all tests that generate files will output their contents. */ -const testTemporaryDirectoryPath = Path.resolve(dirname, "test_temp", "html"); +const testTemporaryDirectoryPath = Path.resolve(testTemporaryDirectoryPathBase, "html"); /** * Snapshot directory to which generated test data will be copied. * Relative to lib/test */ -const snapshotsDirectoryPath = Path.resolve( - dirname, - "..", - "..", - "src", - "test", - "snapshots", - "html", -); - -// Relative to lib/test -const testDataDirectoryPath = Path.resolve(dirname, "..", "..", "src", "test", "test-data"); - -const apiModels: ApiModelTestOptions[] = [ - { - modelName: "simple-suite-test", - directoryPath: Path.resolve(testDataDirectoryPath, "simple-suite-test"), - }, - // TODO: add other models +const snapshotsDirectoryPath = Path.resolve(snapshotsDirectoryPathBase, "html"); + +const apiModels: string[] = [ + // TODO: empty model + "simple-suite-test", ]; -const testConfigs: EndToEndTestConfig[] = [ - /** - * A sample "default" configuration, which renders every item kind under a package to the package parent document. - */ - { - testName: "default-config", - renderConfig: { +const testConfigs = new Map< + string, + Omit +>([ + [ + "default-config", + { uriRoot: ".", }, - }, - - /** - * A sample "flat" configuration, which renders every item kind under a package to the package parent document. - */ - { - testName: "flat-config", - renderConfig: { + ], + + // A sample "flat" configuration, which renders every item kind under a package to the package parent document. + [ + "flat-config", + { uriRoot: "docs", includeBreadcrumb: true, includeTopLevelDocumentHeading: false, - hierarchy: HierarchyConfigs.flat, - minimumReleaseLevel: ReleaseTag.Beta, // Only include `@public` and `beta` items in the docs suite - }, - }, - - /** - * A sample "sparse" configuration, which renders every item kind to its own document. - */ - { - testName: "sparse-config", - renderConfig: { - uriRoot: "docs", - includeBreadcrumb: false, - includeTopLevelDocumentHeading: true, hierarchy: HierarchyConfigs.sparse, - minimumReleaseLevel: ReleaseTag.Public, // Only include `@public` items in the docs suite - skipPackage: (apiPackage) => apiPackage.name === "test-suite-b", // Skip test-suite-b package - startingHeadingLevel: 2, + minimumReleaseLevel: ReleaseTag.Beta, // Only include `@public` and `beta` items in the docs suite }, - }, - - /** - * A sample "deep" configuration, which generates folder hierarchy for any "container" API items. - */ - { - testName: "deep-config", - renderConfig: { + ], + + // A sample "sparse" configuration, which renders every item kind to its own document. + [ + "sparse-config", + { uriRoot: "docs", includeBreadcrumb: false, includeTopLevelDocumentHeading: true, @@ -105,27 +68,40 @@ const testConfigs: EndToEndTestConfig[] = [ skipPackage: (apiPackage) => apiPackage.name === "test-suite-b", // Skip test-suite-b package startingHeadingLevel: 2, }, - }, -]; - -async function renderDocumentToFile( - document: DocumentNode, - renderConfig: HtmlRenderer.RenderDocumentsOptions, -): Promise { - const renderedDocument = HtmlRenderer.renderDocument(document, renderConfig); - - const filePath = Path.join(renderConfig.outputDirectoryPath, `${document.documentPath}.html`); - await FileSystem.writeFileAsync(filePath, renderedDocument, { - convertLineEndings: NewlineKind.Lf, - ensureFolderExists: true, - }); -} - -endToEndTests({ - suiteName: "Markdown End-to-End Tests", - temporaryOutputDirectoryPath: testTemporaryDirectoryPath, - snapshotsDirectoryPath, - render: renderDocumentToFile, - apiModels, - testConfigs, + ], +]); + +describe("HTML end-to-end tests", () => { + for (const modelName of apiModels) { + // Input directory for the model + const modelDirectoryPath = Path.join(testDataDirectoryPath, modelName); + + describe(`API model: ${modelName}`, () => { + let apiModel: ApiModel; + before(async () => { + apiModel = await loadModel({ modelDirectoryPath }); + }); + + for (const [configName, inputConfig] of testConfigs) { + const temporaryOutputPath = Path.join( + testTemporaryDirectoryPath, + modelName, + configName, + ); + const snapshotPath = Path.join(snapshotsDirectoryPath, modelName, configName); + + it(configName, async () => { + const options: HtmlRenderer.RenderApiModelOptions = { + ...inputConfig, + apiModel, + outputDirectoryPath: temporaryOutputPath, + }; + + await HtmlRenderer.renderApiModel(options); + + await compareDocumentationSuiteSnapshot(snapshotPath, temporaryOutputPath); + }); + } + }); + } }); diff --git a/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts index eef5be885190..30cb3487aed3 100644 --- a/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts @@ -3,84 +3,63 @@ * Licensed under the MIT License. */ -import * as Path from "node:path"; -import { fileURLToPath } from "node:url"; +import Path from "node:path"; -import { ReleaseTag } from "@microsoft/api-extractor-model"; -import { FileSystem, NewlineKind } from "@rushstack/node-core-library"; +import { ReleaseTag, type ApiModel } from "@microsoft/api-extractor-model"; -import { type DocumentNode, MarkdownRenderer } from "../index.js"; +import { loadModel, MarkdownRenderer } from "../index.js"; import { - endToEndTests, + compareDocumentationSuiteSnapshot, HierarchyConfigs, - type ApiModelTestOptions, - type EndToEndTestConfig, -} from "./EndToEndTests.js"; - -const dirname = Path.dirname(fileURLToPath(import.meta.url)); + snapshotsDirectoryPath as snapshotsDirectoryPathBase, + testDataDirectoryPath, + testTemporaryDirectoryPath as testTemporaryDirectoryPathBase, +} from "./EndToEndTestUtilities.js"; /** * Temp directory under which all tests that generate files will output their contents. */ -const testTemporaryDirectoryPath = Path.resolve(dirname, "test_temp", "markdown"); +const testTemporaryDirectoryPath = Path.resolve(testTemporaryDirectoryPathBase, "markdown"); /** * Snapshot directory to which generated test data will be copied. * Relative to lib/test */ -const snapshotsDirectoryPath = Path.resolve( - dirname, - "..", - "..", - "src", - "test", - "snapshots", - "markdown", -); - -// Relative to lib/test -const testDataDirectoryPath = Path.resolve(dirname, "..", "..", "src", "test", "test-data"); - -const apiModels: ApiModelTestOptions[] = [ - { - modelName: "simple-suite-test", - directoryPath: Path.resolve(testDataDirectoryPath, "simple-suite-test"), - }, - // TODO: add other models +const snapshotsDirectoryPath = Path.resolve(snapshotsDirectoryPathBase, "markdown"); + +const apiModels: string[] = [ + // TODO: empty model + "simple-suite-test", ]; -const testConfigs: EndToEndTestConfig[] = [ - /** - * A sample "flat" configuration, which renders every item kind under a package to the package parent document. - */ - { - testName: "default-config", - renderConfig: { +const testConfigs = new Map< + string, + Omit +>([ + [ + "default-config", + { uriRoot: ".", }, - }, - - /** - * A sample "flat" configuration, which renders every item kind under a package to the package parent document. - */ - { - testName: "flat-config", - renderConfig: { + ], + + // A sample "flat" configuration, which renders every item kind under a package to the package parent document. + [ + "flat-config", + { uriRoot: "docs", includeBreadcrumb: true, includeTopLevelDocumentHeading: false, hierarchy: HierarchyConfigs.sparse, minimumReleaseLevel: ReleaseTag.Beta, // Only include `@public` and `beta` items in the docs suite }, - }, - - /** - * A sample "sparse" configuration, which renders every item kind to its own document. - */ - { - testName: "sparse-config", - renderConfig: { + ], + + // A sample "sparse" configuration, which renders every item kind to its own document. + [ + "sparse-config", + { uriRoot: "docs", includeBreadcrumb: false, includeTopLevelDocumentHeading: true, @@ -89,27 +68,40 @@ const testConfigs: EndToEndTestConfig[] skipPackage: (apiPackage) => apiPackage.name === "test-suite-b", // Skip test-suite-b package startingHeadingLevel: 2, }, - }, -]; + ], +]); + +describe("Markdown end-to-end tests", () => { + for (const modelName of apiModels) { + // Input directory for the model + const modelDirectoryPath = Path.join(testDataDirectoryPath, modelName); + + describe(`API model: ${modelName}`, () => { + let apiModel: ApiModel; + before(async () => { + apiModel = await loadModel({ modelDirectoryPath }); + }); + + for (const [configName, inputConfig] of testConfigs) { + const temporaryOutputPath = Path.join( + testTemporaryDirectoryPath, + modelName, + configName, + ); + const snapshotPath = Path.join(snapshotsDirectoryPath, modelName, configName); + + it(configName, async () => { + const options: MarkdownRenderer.RenderApiModelOptions = { + ...inputConfig, + apiModel, + outputDirectoryPath: temporaryOutputPath, + }; + + await MarkdownRenderer.renderApiModel(options); -async function renderDocumentToFile( - document: DocumentNode, - renderConfig: MarkdownRenderer.RenderDocumentsOptions, -): Promise { - const renderedDocument = MarkdownRenderer.renderDocument(document, renderConfig); - - const filePath = Path.join(renderConfig.outputDirectoryPath, `${document.documentPath}.md`); - await FileSystem.writeFileAsync(filePath, renderedDocument, { - convertLineEndings: NewlineKind.Lf, - ensureFolderExists: true, - }); -} - -endToEndTests({ - suiteName: "Markdown End-to-End Tests", - temporaryOutputDirectoryPath: testTemporaryDirectoryPath, - snapshotsDirectoryPath, - render: renderDocumentToFile, - apiModels, - testConfigs, + await compareDocumentationSuiteSnapshot(snapshotPath, temporaryOutputPath); + }); + } + }); + } }); diff --git a/tools/api-markdown-documenter/src/test/TransformApiModelEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/TransformApiModelEndToEnd.test.ts new file mode 100644 index 000000000000..1a57c8d6e46e --- /dev/null +++ b/tools/api-markdown-documenter/src/test/TransformApiModelEndToEnd.test.ts @@ -0,0 +1,75 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +import Path from "node:path"; + +import { ReleaseTag, type ApiModel } from "@microsoft/api-extractor-model"; + +import { checkForDuplicateDocumentPaths } from "../api-item-transforms/index.js"; +import { loadModel, transformApiModel, type ApiItemTransformationOptions } from "../index.js"; + +import { HierarchyConfigs, testDataDirectoryPath } from "./EndToEndTestUtilities.js"; + +const apiModels: string[] = ["empty-model", "simple-suite-test"]; + +const testConfigs = new Map>([ + [ + "default-config", + { + uriRoot: ".", + }, + ], + + // A sample "flat" configuration, which renders every item kind under a package to the package parent document. + [ + "flat-config", + { + uriRoot: "docs", + includeBreadcrumb: true, + includeTopLevelDocumentHeading: false, + hierarchy: HierarchyConfigs.sparse, + minimumReleaseLevel: ReleaseTag.Beta, // Only include `@public` and `beta` items in the docs suite + }, + ], + + // A sample "sparse" configuration, which renders every item kind to its own document. + [ + "sparse-config", + { + uriRoot: "docs", + includeBreadcrumb: false, + includeTopLevelDocumentHeading: true, + hierarchy: HierarchyConfigs.sparse, + minimumReleaseLevel: ReleaseTag.Public, // Only include `@public` items in the docs suite + skipPackage: (apiPackage) => apiPackage.name === "test-suite-b", // Skip test-suite-b package + }, + ], +]); + +describe("API item transformation end-to-end tests", () => { + for (const modelName of apiModels) { + // Input directory for the model + const modelDirectoryPath = Path.join(testDataDirectoryPath, modelName); + + describe(`API model: ${modelName}`, () => { + let apiModel: ApiModel; + before(async () => { + apiModel = await loadModel({ modelDirectoryPath }); + }); + + for (const [configName, inputConfig] of testConfigs) { + it(configName, async () => { + const options: ApiItemTransformationOptions = { + ...inputConfig, + apiModel, + }; + + const documents = transformApiModel(options); + checkForDuplicateDocumentPaths(documents); + }); + } + }); + } +}); From cf91dc5deb6538e396fda695548e6a684c2a85e5 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 18 Dec 2024 02:22:56 +0000 Subject: [PATCH 13/54] fix: Config generation --- .../api-item-transforms/configuration/Configuration.ts | 3 +++ .../configuration/HierarchyOptions.ts | 10 ++++++++++ 2 files changed, 13 insertions(+) diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts index 6a87d5da9039..b88cfcd662a1 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts @@ -13,6 +13,7 @@ import { type DocumentationSuiteOptions, getDocumentationSuiteConfigurationWithDefaults, } from "./DocumentationSuiteOptions.js"; +import { getHierarchyOptionsWithDefaults } from "./HierarchyOptions.js"; import { type ApiItemTransformations, getApiItemTransformationsWithDefaults, @@ -74,6 +75,7 @@ export function getApiItemTransformationConfigurationWithDefaults( inputOptions: ApiItemTransformationOptions, ): ApiItemTransformationConfiguration { const logger = inputOptions.logger ?? defaultConsoleLogger; + const hierarchy = getHierarchyOptionsWithDefaults(inputOptions?.hierarchy); const documentationSuiteOptions = getDocumentationSuiteConfigurationWithDefaults(inputOptions); const transformationOptions = getApiItemTransformationsWithDefaults(inputOptions); return { @@ -81,6 +83,7 @@ export function getApiItemTransformationConfigurationWithDefaults( ...transformationOptions, apiModel: inputOptions.apiModel, uriRoot: inputOptions.uriRoot, + hierarchy, logger, }; } diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts index 72566a5d4ffe..cece040a48dd 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts @@ -300,3 +300,13 @@ export const defaultHierarchyOptions: HierarchyOptions = { [ApiItemKind.PropertySignature]: defaultSectionHierarchyConfig, [ApiItemKind.Variable]: defaultSectionHierarchyConfig, }; + +/** + * Gets a complete {@link HierarchyOptions} using the provided partial configuration, and filling + * in the remainder with defaults. + */ +export function getHierarchyOptionsWithDefaults( + inputOptions: Partial | undefined, +): HierarchyOptions { + return { ...defaultHierarchyOptions, ...inputOptions }; +} From 301902896cdb42d1633e96535ed62df44311e762 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 18 Dec 2024 21:24:16 +0000 Subject: [PATCH 14/54] refactor: Rename types --- .../api-markdown-documenter.alpha.api.md | 48 +++++------ .../api-markdown-documenter.beta.api.md | 48 +++++------ .../api-markdown-documenter.public.api.md | 48 +++++------ .../ApiItemTransformUtilities.ts | 22 ++--- .../DocumentationSuiteOptions.ts | 14 ++-- .../configuration/HierarchyOptions.ts | 81 ++++++++++--------- .../configuration/index.ts | 18 ++--- .../api-item-transforms/helpers/Helpers.ts | 2 +- .../src/api-item-transforms/index.ts | 18 ++--- tools/api-markdown-documenter/src/index.ts | 18 ++--- .../src/test/EndToEndTestUtilities.ts | 22 ++--- 11 files changed, 173 insertions(+), 166 deletions(-) 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 45a5602b9be3..f49db0c486d5 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 @@ -197,6 +197,14 @@ export namespace DefaultDocumentationSuiteOptions { export function defaultSkipPackage(): boolean; } +// @public +export type DocumentationHierarchyConfiguration = SectionHierarchyConfiguration | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; + +// @public +export interface DocumentationHierarchyConfigurationBase { + readonly kind: THierarchyKind; +} + // @public export interface DocumentationLiteralNode extends Literal, DocumentationNode { readonly isLiteral: true; @@ -281,7 +289,7 @@ export abstract class DocumentationParentNodeBase, "hierarchy"> & { - readonly hierarchy: Required; + readonly hierarchy: Required; }; // @public @@ -289,7 +297,7 @@ export interface DocumentationSuiteOptions { readonly getAlertsForItem?: (apiItem: ApiItem) => string[]; readonly getLinkTextForItem?: (apiItem: ApiItem) => string; readonly getUriBaseOverrideForItem?: (apiItem: ApiItem) => string | undefined; - readonly hierarchy?: Partial; + readonly hierarchy?: Partial; readonly includeBreadcrumb?: boolean; readonly includeTopLevelDocumentHeading?: boolean; readonly minimumReleaseLevel?: Exclude; @@ -297,11 +305,11 @@ export interface DocumentationSuiteOptions { } // @public -export interface DocumentHierarchyConfig extends HierarchyConfigBase, DocumentHierarchyOptions { +export interface DocumentHierarchyConfiguration extends DocumentationHierarchyConfigurationBase, DocumentHierarchyProperties { } // @public -export interface DocumentHierarchyOptions extends SectionHierarchyOptions { +export interface DocumentHierarchyProperties extends SectionHierarchyProperties { readonly documentName: string | ((apiItem: ApiItem) => string); } @@ -343,7 +351,7 @@ export namespace DocumentWriter { } // @public -function doesItemKindRequireOwnDocument(apiItemKind: ValidApiItemKind, hierarchyConfig: Required): boolean; +function doesItemKindRequireOwnDocument(apiItemKind: ValidApiItemKind, hierarchyConfig: Required): boolean; // @public export class FencedCodeBlockNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { @@ -370,11 +378,11 @@ export enum FolderDocumentPlacement { } // @public -export interface FolderHierarchyConfig extends HierarchyConfigBase, FolderHierarchyOptions { +export interface FolderHierarchyConfiguration extends DocumentationHierarchyConfigurationBase, FolderHierarchyProperties { } // @public -export interface FolderHierarchyOptions extends DocumentHierarchyOptions { +export interface FolderHierarchyProperties extends DocumentHierarchyProperties { readonly documentPlacement: FolderDocumentPlacement | ((apiItem: ApiItem) => FolderDocumentPlacement); readonly folderName: string | ((apiItem: ApiItem) => string); } @@ -454,12 +462,13 @@ export class HeadingNode extends DocumentationParentNodeBase { - readonly kind: THierarchyKind; -} +export type HierarchyConfiguration = { + [Kind in Exclude]: DocumentationHierarchyConfiguration; +} & { + [ApiItemKind.Model]: DocumentHierarchyConfiguration; + [ApiItemKind.Package]: FolderHierarchyConfiguration; + [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; +}; // @public export enum HierarchyKind { @@ -468,15 +477,6 @@ export enum HierarchyKind { Section = "section" } -// @public -export type HierarchyOptions = { - [Kind in Exclude]: HierarchyConfig; -} & { - [ApiItemKind.Model]: DocumentHierarchyConfig; - [ApiItemKind.Package]: FolderHierarchyConfig; - [ApiItemKind.EntryPoint]: DocumentHierarchyConfig; -}; - // @public export class HorizontalRuleNode implements MultiLineDocumentationNode { constructor(); @@ -728,11 +728,11 @@ function renderNode(node: DocumentationNode, writer: DocumentWriter, context: Ma function renderNodes(children: DocumentationNode[], writer: DocumentWriter, childContext: MarkdownRenderContext): void; // @public -export interface SectionHierarchyConfig extends HierarchyConfigBase, SectionHierarchyOptions { +export interface SectionHierarchyConfiguration extends DocumentationHierarchyConfigurationBase, SectionHierarchyProperties { } // @public -export interface SectionHierarchyOptions { +export interface SectionHierarchyProperties { readonly headingText: string | ((apiItem: ApiItem) => string); } 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 a85e97fe53ff..c1e27ca4b38e 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 @@ -197,6 +197,14 @@ export namespace DefaultDocumentationSuiteOptions { export function defaultSkipPackage(): boolean; } +// @public +export type DocumentationHierarchyConfiguration = SectionHierarchyConfiguration | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; + +// @public +export interface DocumentationHierarchyConfigurationBase { + readonly kind: THierarchyKind; +} + // @public export interface DocumentationLiteralNode extends Literal, DocumentationNode { readonly isLiteral: true; @@ -281,7 +289,7 @@ export abstract class DocumentationParentNodeBase, "hierarchy"> & { - readonly hierarchy: Required; + readonly hierarchy: Required; }; // @public @@ -289,7 +297,7 @@ export interface DocumentationSuiteOptions { readonly getAlertsForItem?: (apiItem: ApiItem) => string[]; readonly getLinkTextForItem?: (apiItem: ApiItem) => string; readonly getUriBaseOverrideForItem?: (apiItem: ApiItem) => string | undefined; - readonly hierarchy?: Partial; + readonly hierarchy?: Partial; readonly includeBreadcrumb?: boolean; readonly includeTopLevelDocumentHeading?: boolean; readonly minimumReleaseLevel?: Exclude; @@ -297,11 +305,11 @@ export interface DocumentationSuiteOptions { } // @public -export interface DocumentHierarchyConfig extends HierarchyConfigBase, DocumentHierarchyOptions { +export interface DocumentHierarchyConfiguration extends DocumentationHierarchyConfigurationBase, DocumentHierarchyProperties { } // @public -export interface DocumentHierarchyOptions extends SectionHierarchyOptions { +export interface DocumentHierarchyProperties extends SectionHierarchyProperties { readonly documentName: string | ((apiItem: ApiItem) => string); } @@ -343,7 +351,7 @@ export namespace DocumentWriter { } // @public -function doesItemKindRequireOwnDocument(apiItemKind: ValidApiItemKind, hierarchyConfig: Required): boolean; +function doesItemKindRequireOwnDocument(apiItemKind: ValidApiItemKind, hierarchyConfig: Required): boolean; // @public export class FencedCodeBlockNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { @@ -370,11 +378,11 @@ export enum FolderDocumentPlacement { } // @public -export interface FolderHierarchyConfig extends HierarchyConfigBase, FolderHierarchyOptions { +export interface FolderHierarchyConfiguration extends DocumentationHierarchyConfigurationBase, FolderHierarchyProperties { } // @public -export interface FolderHierarchyOptions extends DocumentHierarchyOptions { +export interface FolderHierarchyProperties extends DocumentHierarchyProperties { readonly documentPlacement: FolderDocumentPlacement | ((apiItem: ApiItem) => FolderDocumentPlacement); readonly folderName: string | ((apiItem: ApiItem) => string); } @@ -454,12 +462,13 @@ export class HeadingNode extends DocumentationParentNodeBase { - readonly kind: THierarchyKind; -} +export type HierarchyConfiguration = { + [Kind in Exclude]: DocumentationHierarchyConfiguration; +} & { + [ApiItemKind.Model]: DocumentHierarchyConfiguration; + [ApiItemKind.Package]: FolderHierarchyConfiguration; + [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; +}; // @public export enum HierarchyKind { @@ -468,15 +477,6 @@ export enum HierarchyKind { Section = "section" } -// @public -export type HierarchyOptions = { - [Kind in Exclude]: HierarchyConfig; -} & { - [ApiItemKind.Model]: DocumentHierarchyConfig; - [ApiItemKind.Package]: FolderHierarchyConfig; - [ApiItemKind.EntryPoint]: DocumentHierarchyConfig; -}; - // @public export class HorizontalRuleNode implements MultiLineDocumentationNode { constructor(); @@ -714,11 +714,11 @@ function renderNode(node: DocumentationNode, writer: DocumentWriter, context: Ma function renderNodes(children: DocumentationNode[], writer: DocumentWriter, childContext: MarkdownRenderContext): void; // @public -export interface SectionHierarchyConfig extends HierarchyConfigBase, SectionHierarchyOptions { +export interface SectionHierarchyConfiguration extends DocumentationHierarchyConfigurationBase, SectionHierarchyProperties { } // @public -export interface SectionHierarchyOptions { +export interface SectionHierarchyProperties { readonly headingText: string | ((apiItem: ApiItem) => string); } 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 adff06ec8a19..fe2a01af8de0 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 @@ -197,6 +197,14 @@ export namespace DefaultDocumentationSuiteOptions { export function defaultSkipPackage(): boolean; } +// @public +export type DocumentationHierarchyConfiguration = SectionHierarchyConfiguration | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; + +// @public +export interface DocumentationHierarchyConfigurationBase { + readonly kind: THierarchyKind; +} + // @public export interface DocumentationLiteralNode extends Literal, DocumentationNode { readonly isLiteral: true; @@ -281,7 +289,7 @@ export abstract class DocumentationParentNodeBase, "hierarchy"> & { - readonly hierarchy: Required; + readonly hierarchy: Required; }; // @public @@ -289,7 +297,7 @@ export interface DocumentationSuiteOptions { readonly getAlertsForItem?: (apiItem: ApiItem) => string[]; readonly getLinkTextForItem?: (apiItem: ApiItem) => string; readonly getUriBaseOverrideForItem?: (apiItem: ApiItem) => string | undefined; - readonly hierarchy?: Partial; + readonly hierarchy?: Partial; readonly includeBreadcrumb?: boolean; readonly includeTopLevelDocumentHeading?: boolean; readonly minimumReleaseLevel?: Exclude; @@ -297,11 +305,11 @@ export interface DocumentationSuiteOptions { } // @public -export interface DocumentHierarchyConfig extends HierarchyConfigBase, DocumentHierarchyOptions { +export interface DocumentHierarchyConfiguration extends DocumentationHierarchyConfigurationBase, DocumentHierarchyProperties { } // @public -export interface DocumentHierarchyOptions extends SectionHierarchyOptions { +export interface DocumentHierarchyProperties extends SectionHierarchyProperties { readonly documentName: string | ((apiItem: ApiItem) => string); } @@ -343,7 +351,7 @@ export namespace DocumentWriter { } // @public -function doesItemKindRequireOwnDocument(apiItemKind: ValidApiItemKind, hierarchyConfig: Required): boolean; +function doesItemKindRequireOwnDocument(apiItemKind: ValidApiItemKind, hierarchyConfig: Required): boolean; // @public export class FencedCodeBlockNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { @@ -370,11 +378,11 @@ export enum FolderDocumentPlacement { } // @public -export interface FolderHierarchyConfig extends HierarchyConfigBase, FolderHierarchyOptions { +export interface FolderHierarchyConfiguration extends DocumentationHierarchyConfigurationBase, FolderHierarchyProperties { } // @public -export interface FolderHierarchyOptions extends DocumentHierarchyOptions { +export interface FolderHierarchyProperties extends DocumentHierarchyProperties { readonly documentPlacement: FolderDocumentPlacement | ((apiItem: ApiItem) => FolderDocumentPlacement); readonly folderName: string | ((apiItem: ApiItem) => string); } @@ -454,12 +462,13 @@ export class HeadingNode extends DocumentationParentNodeBase { - readonly kind: THierarchyKind; -} +export type HierarchyConfiguration = { + [Kind in Exclude]: DocumentationHierarchyConfiguration; +} & { + [ApiItemKind.Model]: DocumentHierarchyConfiguration; + [ApiItemKind.Package]: FolderHierarchyConfiguration; + [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; +}; // @public export enum HierarchyKind { @@ -468,15 +477,6 @@ export enum HierarchyKind { Section = "section" } -// @public -export type HierarchyOptions = { - [Kind in Exclude]: HierarchyConfig; -} & { - [ApiItemKind.Model]: DocumentHierarchyConfig; - [ApiItemKind.Package]: FolderHierarchyConfig; - [ApiItemKind.EntryPoint]: DocumentHierarchyConfig; -}; - // @public export class HorizontalRuleNode implements MultiLineDocumentationNode { constructor(); @@ -692,11 +692,11 @@ function renderNode(node: DocumentationNode, writer: DocumentWriter, context: Ma function renderNodes(children: DocumentationNode[], writer: DocumentWriter, childContext: MarkdownRenderContext): void; // @public -export interface SectionHierarchyConfig extends HierarchyConfigBase, SectionHierarchyOptions { +export interface SectionHierarchyConfiguration extends DocumentationHierarchyConfigurationBase, SectionHierarchyProperties { } // @public -export interface SectionHierarchyOptions { +export interface SectionHierarchyProperties { readonly headingText: string | ((apiItem: ApiItem) => string); } 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 9ac72ea6fb29..d696d8450a86 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts @@ -21,10 +21,10 @@ import { FolderDocumentPlacement, HierarchyKind, type ApiItemTransformationConfiguration, - type DocumentHierarchyConfig, - type FolderHierarchyConfig, - type HierarchyConfig, - type HierarchyOptions, + type DocumentHierarchyConfiguration, + type FolderHierarchyConfiguration, + type DocumentationHierarchyConfiguration, + type HierarchyConfiguration, } from "./configuration/index.js"; /** @@ -34,7 +34,9 @@ import { /** * API item paired with its hierarchy config. */ -export interface ApiItemWithHierarchy { +export interface ApiItemWithHierarchy< + THierarchy extends DocumentationHierarchyConfiguration = DocumentationHierarchyConfiguration, +> { readonly apiItem: ApiItem; readonly hierarchy: THierarchy; } @@ -47,12 +49,12 @@ export interface ApiItemWithHierarchy, -): ApiItemWithHierarchy { + hierarchyConfig: Required, +): ApiItemWithHierarchy { // Walk parentage until we reach an item kind that gets rendered to its own document. // That is the document we will target with the generated link. let hierarchyItem: ApiItem = apiItem; @@ -310,7 +312,7 @@ export function getFilteredParent(apiItem: ApiItem): ApiItem | undefined { */ export function doesItemKindRequireOwnDocument( apiItemKind: ValidApiItemKind, - hierarchyConfig: Required, + hierarchyConfig: Required, ): boolean { const hierarchy = hierarchyConfig[apiItemKind]; return hierarchy.kind !== HierarchyKind.Section; @@ -325,7 +327,7 @@ export function doesItemKindRequireOwnDocument( */ export function doesItemRequireOwnDocument( apiItem: ApiItem, - hierarchyConfig: Required, + hierarchyConfig: Required, ): boolean { const itemKind = getApiItemKind(apiItem); return doesItemKindRequireOwnDocument(itemKind, hierarchyConfig); diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts index 814a94804536..4d1dcd2eb0a3 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts @@ -18,7 +18,7 @@ import { getReleaseTag, } from "../../utilities/index.js"; -import { defaultHierarchyOptions, type HierarchyOptions } from "./HierarchyOptions.js"; +import { defaultHierarchyConfiguration, type HierarchyConfiguration } from "./HierarchyOptions.js"; import { trimTrailingSemicolon } from "./Utilities.js"; /** @@ -47,9 +47,9 @@ export interface DocumentationSuiteOptions { readonly includeBreadcrumb?: boolean; /** - * {@link HierarchyConfig} to use for the provided API item. + * {@link HierarchyConfiguration} to use for the provided API item. */ - readonly hierarchy?: Partial; + readonly hierarchy?: Partial; /** * Optionally provide an override for the URI base used in links generated for the provided `ApiItem`. @@ -138,7 +138,7 @@ export type DocumentationSuiteConfiguration = Omit< /** * {@inheritDoc DocumentationSuiteOptions.hierarchy} */ - readonly hierarchy: Required; + readonly hierarchy: Required; }; /** @@ -222,7 +222,7 @@ export namespace DefaultDocumentationSuiteOptions { * Default {@link DocumentationSuiteOptions} value. */ const defaultDocumentationSuiteOptions: Required = { - hierarchy: defaultHierarchyOptions, + hierarchy: defaultHierarchyConfiguration, includeTopLevelDocumentHeading: true, includeBreadcrumb: true, getUriBaseOverrideForItem: DefaultDocumentationSuiteOptions.defaultGetUriBaseOverrideForItem, @@ -239,8 +239,8 @@ const defaultDocumentationSuiteOptions: Required = { export function getDocumentationSuiteConfigurationWithDefaults( inputOptions: DocumentationSuiteOptions, ): DocumentationSuiteConfiguration { - const hierarchy: Required = { - ...defaultHierarchyOptions, + const hierarchy: Required = { + ...defaultHierarchyConfiguration, ...inputOptions.hierarchy, }; return { diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts index cece040a48dd..582912ccc454 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts @@ -38,7 +38,7 @@ export enum HierarchyKind { } /** - * {@link HierarchyConfig} base interface. + * {@link DocumentationHierarchyConfiguration} base interface. * * @remarks * Not intended for external use. @@ -46,7 +46,7 @@ export enum HierarchyKind { * * @public */ -export interface HierarchyConfigBase { +export interface DocumentationHierarchyConfigurationBase { /** * {@inheritDoc HierarchyKind} */ @@ -54,11 +54,11 @@ export interface HierarchyConfigBase { } /** - * {@link HierarchyKind.Section} hierarchy configuration options. + * {@link HierarchyKind.Section} hierarchy configuration properties. * * @public */ -export interface SectionHierarchyOptions { +export interface SectionHierarchyProperties { /** * Heading text to use for the API item. */ @@ -70,16 +70,16 @@ export interface SectionHierarchyOptions { * * @public */ -export interface SectionHierarchyConfig - extends HierarchyConfigBase, - SectionHierarchyOptions {} +export interface SectionHierarchyConfiguration + extends DocumentationHierarchyConfigurationBase, + SectionHierarchyProperties {} /** - * {@link HierarchyKind.Document} hierarchy configuration options. + * {@link HierarchyKind.Document} hierarchy configuration properties. * * @public */ -export interface DocumentHierarchyOptions extends SectionHierarchyOptions { +export interface DocumentHierarchyProperties extends SectionHierarchyProperties { /** * Document name to use for the API item. */ @@ -91,14 +91,14 @@ export interface DocumentHierarchyOptions extends SectionHierarchyOptions { * * @public */ -export interface DocumentHierarchyConfig - extends HierarchyConfigBase, - DocumentHierarchyOptions {} +export interface DocumentHierarchyConfiguration + extends DocumentationHierarchyConfigurationBase, + DocumentHierarchyProperties {} /** * Placement of the API item's document relative to its generated folder. * - * @remarks Used by {@link FolderHierarchyOptions}. + * @remarks Used by {@link FolderHierarchyProperties}. * * @public */ @@ -115,11 +115,11 @@ export enum FolderDocumentPlacement { } /** - * {@link HierarchyKind.Document} hierarchy configuration options. + * {@link HierarchyKind.Document} hierarchy configuration properties. * * @public */ -export interface FolderHierarchyOptions extends DocumentHierarchyOptions { +export interface FolderHierarchyProperties extends DocumentHierarchyProperties { /** * Placement of the API item's document relative to its generated folder. * `inside`: The document is placed inside its folder. @@ -140,22 +140,22 @@ export interface FolderHierarchyOptions extends DocumentHierarchyOptions { * * @public */ -export interface FolderHierarchyConfig - extends HierarchyConfigBase, - FolderHierarchyOptions {} +export interface FolderHierarchyConfiguration + extends DocumentationHierarchyConfigurationBase, + FolderHierarchyProperties {} /** * API item hierarchy configuration. * * @public */ -export type HierarchyConfig = - | SectionHierarchyConfig - | DocumentHierarchyConfig - | FolderHierarchyConfig; +export type DocumentationHierarchyConfiguration = + | SectionHierarchyConfiguration + | DocumentHierarchyConfiguration + | FolderHierarchyConfiguration; /** - * Default {@link SectionHierarchyOptions.headingText}. + * Default {@link SectionHierarchyProperties.headingText}. * * Uses the item's qualified API name, but is handled differently for the following items: * @@ -184,13 +184,13 @@ function defaultHeadingText(apiItem: ApiItem): string { } } -const defaultSectionHierarchyConfig: SectionHierarchyConfig = { +const defaultSectionHierarchyConfig: SectionHierarchyConfiguration = { kind: HierarchyKind.Section, headingText: defaultHeadingText, }; /** - * Default {@link DocumentHierarchyOptions.documentName} for non-folder hierarchy documents. + * Default {@link DocumentHierarchyProperties.documentName} for non-folder hierarchy documents. * * Uses the item's qualified API name, but is handled differently for the following items: * @@ -210,7 +210,7 @@ function defaultDocumentName(apiItem: ApiItem): string { } } -const defaultDocumentHierarchyConfig: DocumentHierarchyConfig = { +const defaultDocumentHierarchyConfig: DocumentHierarchyConfiguration = { kind: HierarchyKind.Document, headingText: defaultHeadingText, documentName: defaultDocumentName, @@ -219,7 +219,7 @@ const defaultDocumentHierarchyConfig: DocumentHierarchyConfig = { // Default folder name is the same as the default document name. const defaultFolderName = defaultDocumentName; -const defaultFolderHierarchyConfig: FolderHierarchyConfig = { +const defaultFolderHierarchyConfig: FolderHierarchyConfiguration = { kind: HierarchyKind.Folder, headingText: defaultHeadingText, documentPlacement: FolderDocumentPlacement.Outside, // TODO @@ -233,21 +233,21 @@ const defaultFolderHierarchyConfig: FolderHierarchyConfig = { * * @public */ -export type HierarchyOptions = { +export type HierarchyConfiguration = { /** * Hierarchy configuration for the API item kind. */ [Kind in Exclude< ValidApiItemKind, ApiItemKind.Model | ApiItemKind.EntryPoint | ApiItemKind.Package - >]: HierarchyConfig; + >]: DocumentationHierarchyConfiguration; } & { /** * Hierarchy configuration for the `Model` API item kind. * * @remarks Always its own document. Never introduces folder hierarchy. */ - [ApiItemKind.Model]: DocumentHierarchyConfig; + [ApiItemKind.Model]: DocumentHierarchyConfiguration; /** * Hierarchy configuration for the `Package` API item kind. @@ -255,7 +255,7 @@ export type HierarchyOptions = { * @remarks Always introduces folder hierarchy. * @privateRemarks TODO: Make this fully configurable - there is no real reason for this policy to be baked in. */ - [ApiItemKind.Package]: FolderHierarchyConfig; + [ApiItemKind.Package]: FolderHierarchyConfiguration; /** * Hierarchy configuration for the `EntryPoint` API item kind. @@ -263,13 +263,18 @@ export type HierarchyOptions = { * @remarks Always its own document, adjacent to the package document. * @privateRemarks TODO: Make this fully configurable - there is no real reason for this policy to be baked in. */ - [ApiItemKind.EntryPoint]: DocumentHierarchyConfig; + [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; }; /** - * Default {@link HierarchyOptions}. + * Partial {@link HierarchyConfiguration} provided as user input. */ -export const defaultHierarchyOptions: HierarchyOptions = { +export type HierarchyOptions = Partial; + +/** + * Default {@link HierarchyConfiguration}. + */ +export const defaultHierarchyConfiguration: HierarchyConfiguration = { [ApiItemKind.Model]: { kind: HierarchyKind.Document, headingText: "API Overview", @@ -302,11 +307,11 @@ export const defaultHierarchyOptions: HierarchyOptions = { }; /** - * Gets a complete {@link HierarchyOptions} using the provided partial configuration, and filling + * Gets a complete {@link HierarchyConfiguration} using the provided partial configuration, and filling * in the remainder with defaults. */ export function getHierarchyOptionsWithDefaults( - inputOptions: Partial | undefined, -): HierarchyOptions { - return { ...defaultHierarchyOptions, ...inputOptions }; + inputOptions: HierarchyOptions | undefined, +): HierarchyConfiguration { + return { ...defaultHierarchyConfiguration, ...inputOptions }; } diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts index 7ded0857a30f..ded1c08f204e 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts @@ -17,16 +17,16 @@ export { } from "./DocumentationSuiteOptions.js"; export { HierarchyKind, - type HierarchyConfigBase, - type SectionHierarchyOptions, - type SectionHierarchyConfig, - type DocumentHierarchyOptions, - type DocumentHierarchyConfig, + type DocumentationHierarchyConfigurationBase, + type SectionHierarchyProperties, + type SectionHierarchyConfiguration, + type DocumentHierarchyProperties, + type DocumentHierarchyConfiguration, FolderDocumentPlacement, - type FolderHierarchyOptions, - type FolderHierarchyConfig, - type HierarchyConfig, - type HierarchyOptions, + type FolderHierarchyProperties, + type FolderHierarchyConfiguration, + type DocumentationHierarchyConfiguration, + type HierarchyConfiguration, } from "./HierarchyOptions.js"; export { type ApiItemTransformations, 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 6e885cc7f1ab..46a7e85b4fcf 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 @@ -383,7 +383,7 @@ export function createExcerptSpanWithHyperlinks( * * @remarks Displayed as a ` > `-separated list of hierarchical page links. * 1 for each element in the provided item's ancestry for which a separate document is generated - * (see {@link HierarchyOptions}). + * (see {@link HierarchyConfiguration}). * * @param apiItem - The API item whose ancestry will be used to generate the breadcrumb. * @param config - See {@link ApiItemTransformationConfiguration}. diff --git a/tools/api-markdown-documenter/src/api-item-transforms/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/index.ts index 88bddb07c825..83db0edc1bb6 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/index.ts @@ -22,20 +22,20 @@ export { type ApiItemTransformationOptions, type ApiItemTransformations, type DefaultDocumentationSuiteOptions, - type DocumentHierarchyConfig, - type DocumentHierarchyOptions, + type DocumentHierarchyConfiguration, + type DocumentHierarchyProperties, type DocumentationSuiteConfiguration, type DocumentationSuiteOptions, FolderDocumentPlacement, - type FolderHierarchyConfig, - type FolderHierarchyOptions, + type FolderHierarchyConfiguration, + type FolderHierarchyProperties, getApiItemTransformationConfigurationWithDefaults, - type HierarchyConfig, - type HierarchyConfigBase, + type DocumentationHierarchyConfiguration, + type DocumentationHierarchyConfigurationBase, HierarchyKind, - type HierarchyOptions, - type SectionHierarchyConfig, - type SectionHierarchyOptions, + type HierarchyConfiguration, + type SectionHierarchyConfiguration, + type SectionHierarchyProperties, type TransformApiItemWithChildren, type TransformApiItemWithoutChildren, } from "./configuration/index.js"; diff --git a/tools/api-markdown-documenter/src/index.ts b/tools/api-markdown-documenter/src/index.ts index ecd735a33ccb..7e232bb3c443 100644 --- a/tools/api-markdown-documenter/src/index.ts +++ b/tools/api-markdown-documenter/src/index.ts @@ -19,21 +19,21 @@ export { type ApiItemTransformationOptions, type ApiItemTransformations, type DefaultDocumentationSuiteOptions, - type DocumentHierarchyConfig, - type DocumentHierarchyOptions, + type DocumentHierarchyConfiguration, + type DocumentHierarchyProperties, type DocumentationSuiteConfiguration, type DocumentationSuiteOptions, FolderDocumentPlacement, - type FolderHierarchyConfig, - type FolderHierarchyOptions, + type FolderHierarchyConfiguration, + type FolderHierarchyProperties, // TODO: remove this once utility APIs can be called with partial configs. getApiItemTransformationConfigurationWithDefaults, - type HierarchyConfig, - type HierarchyConfigBase, + type DocumentationHierarchyConfiguration, + type DocumentationHierarchyConfigurationBase, HierarchyKind, - type HierarchyOptions, - type SectionHierarchyConfig, - type SectionHierarchyOptions, + type HierarchyConfiguration, + type SectionHierarchyConfiguration, + type SectionHierarchyProperties, type TransformApiItemWithChildren, type TransformApiItemWithoutChildren, transformApiModel, diff --git a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts index 59e1fbe6a746..29fa0026ea34 100644 --- a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts +++ b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts @@ -13,12 +13,12 @@ import { compare } from "dir-compare"; import { ApiItemUtilities, - type DocumentHierarchyConfig, + type DocumentHierarchyConfiguration, FolderDocumentPlacement, HierarchyKind, - type HierarchyOptions, - type FolderHierarchyConfig, - type SectionHierarchyConfig, + type HierarchyConfiguration, + type FolderHierarchyConfiguration, + type SectionHierarchyConfiguration, } from "../index.js"; const dirname = Path.dirname(fileURLToPath(import.meta.url)); @@ -47,18 +47,18 @@ export const testDataDirectoryPath = Path.resolve(dirname, "..", "..", "src", "t */ // eslint-disable-next-line @typescript-eslint/no-namespace export namespace HierarchyConfigs { - const defaultSectionConfig: SectionHierarchyConfig = { + const defaultSectionConfig: SectionHierarchyConfiguration = { kind: HierarchyKind.Section, headingText: (apiItem) => apiItem.displayName, }; - const defaultDocumentConfig: DocumentHierarchyConfig = { + const defaultDocumentConfig: DocumentHierarchyConfiguration = { kind: HierarchyKind.Document, documentName: (apiItem) => ApiItemUtilities.getFileSafeNameForApiItem(apiItem), headingText: (apiItem) => apiItem.displayName, }; - const outsideFolderConfig: FolderHierarchyConfig = { + const outsideFolderConfig: FolderHierarchyConfiguration = { kind: HierarchyKind.Folder, documentPlacement: FolderDocumentPlacement.Outside, documentName: (apiItem) => ApiItemUtilities.getFileSafeNameForApiItem(apiItem), @@ -66,7 +66,7 @@ export namespace HierarchyConfigs { headingText: (apiItem) => apiItem.displayName, }; - const insideFolderConfig: FolderHierarchyConfig = { + const insideFolderConfig: FolderHierarchyConfiguration = { kind: HierarchyKind.Folder, documentPlacement: FolderDocumentPlacement.Inside, documentName: "index", @@ -78,7 +78,7 @@ export namespace HierarchyConfigs { * "Flat" hierarchy: Packages get their own documents, and all descendent API items are rendered as sections under that document. * @remarks Results in a small number of documents, but can lead to relatively large documents. */ - export const flat: Partial = { + export const flat: Partial = { [ApiItemKind.Package]: outsideFolderConfig, [ApiItemKind.CallSignature]: defaultSectionConfig, @@ -102,7 +102,7 @@ export namespace HierarchyConfigs { * "Sparse" hierarchy: Packages yield folder hierarchy, and all descendent items get their own document under that folder. * @remarks Leads to many documents, but each document is likely to be relatively small. */ - export const sparse: Partial = { + export const sparse: Partial = { [ApiItemKind.Package]: outsideFolderConfig, [ApiItemKind.CallSignature]: defaultDocumentConfig, @@ -127,7 +127,7 @@ export namespace HierarchyConfigs { * "Deep" hierarchy: All "parent" API items generate hierarchy. All other items are rendered as documents under their parent hierarchy. * @remarks Leads to many documents, but each document is likely to be relatively small. */ - export const deep: Partial = { + export const deep: Partial = { // Items that introduce folder hierarchy: [ApiItemKind.Namespace]: insideFolderConfig, [ApiItemKind.Package]: insideFolderConfig, From dad58144795058407f62aae7a6d0a15bf8b314c8 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 18 Dec 2024 21:25:35 +0000 Subject: [PATCH 15/54] refactor: Rename file --- .../src/api-item-transforms/configuration/Configuration.ts | 2 +- .../configuration/DocumentationSuiteOptions.ts | 2 +- .../configuration/{HierarchyOptions.ts => Hierarchy.ts} | 0 .../src/api-item-transforms/configuration/index.ts | 2 +- 4 files changed, 3 insertions(+), 3 deletions(-) rename tools/api-markdown-documenter/src/api-item-transforms/configuration/{HierarchyOptions.ts => Hierarchy.ts} (100%) diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts index b88cfcd662a1..1384275bfd5d 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts @@ -13,7 +13,7 @@ import { type DocumentationSuiteOptions, getDocumentationSuiteConfigurationWithDefaults, } from "./DocumentationSuiteOptions.js"; -import { getHierarchyOptionsWithDefaults } from "./HierarchyOptions.js"; +import { getHierarchyOptionsWithDefaults } from "./Hierarchy.js"; import { type ApiItemTransformations, getApiItemTransformationsWithDefaults, diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts index 4d1dcd2eb0a3..3a67a305c121 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts @@ -18,7 +18,7 @@ import { getReleaseTag, } from "../../utilities/index.js"; -import { defaultHierarchyConfiguration, type HierarchyConfiguration } from "./HierarchyOptions.js"; +import { defaultHierarchyConfiguration, type HierarchyConfiguration } from "./Hierarchy.js"; import { trimTrailingSemicolon } from "./Utilities.js"; /** diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts similarity index 100% rename from tools/api-markdown-documenter/src/api-item-transforms/configuration/HierarchyOptions.ts rename to tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts index ded1c08f204e..8ea88881fbe7 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts @@ -27,7 +27,7 @@ export { type FolderHierarchyConfiguration, type DocumentationHierarchyConfiguration, type HierarchyConfiguration, -} from "./HierarchyOptions.js"; +} from "./Hierarchy.js"; export { type ApiItemTransformations, getApiItemTransformationsWithDefaults, From 81994f4ee14a1afc88be8cd7d0ab074a28d726ff Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 18 Dec 2024 21:44:00 +0000 Subject: [PATCH 16/54] fix: Restore support for document hierarchy for packages --- .../api-markdown-documenter.alpha.api.md | 2 +- .../api-markdown-documenter.beta.api.md | 2 +- .../api-markdown-documenter.public.api.md | 2 +- .../configuration/Hierarchy.ts | 18 +++++++++++++----- 4 files changed, 16 insertions(+), 8 deletions(-) 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 f49db0c486d5..c2b155411f11 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 @@ -466,7 +466,7 @@ export type HierarchyConfiguration = { [Kind in Exclude]: DocumentationHierarchyConfiguration; } & { [ApiItemKind.Model]: DocumentHierarchyConfiguration; - [ApiItemKind.Package]: FolderHierarchyConfiguration; + [ApiItemKind.Package]: DocumentHierarchyConfiguration | FolderHierarchyConfiguration; [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; }; 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 c1e27ca4b38e..addab2101705 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 @@ -466,7 +466,7 @@ export type HierarchyConfiguration = { [Kind in Exclude]: DocumentationHierarchyConfiguration; } & { [ApiItemKind.Model]: DocumentHierarchyConfiguration; - [ApiItemKind.Package]: FolderHierarchyConfiguration; + [ApiItemKind.Package]: DocumentHierarchyConfiguration | FolderHierarchyConfiguration; [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; }; 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 fe2a01af8de0..86df9fa68a0e 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 @@ -466,7 +466,7 @@ export type HierarchyConfiguration = { [Kind in Exclude]: DocumentationHierarchyConfiguration; } & { [ApiItemKind.Model]: DocumentHierarchyConfiguration; - [ApiItemKind.Package]: FolderHierarchyConfiguration; + [ApiItemKind.Package]: DocumentHierarchyConfiguration | FolderHierarchyConfiguration; [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; }; diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts index 582912ccc454..440272c17216 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts @@ -252,16 +252,24 @@ export type HierarchyConfiguration = { /** * Hierarchy configuration for the `Package` API item kind. * - * @remarks Always introduces folder hierarchy. - * @privateRemarks TODO: Make this fully configurable - there is no real reason for this policy to be baked in. + * @remarks Must be either a folder or document hierarchy configuration. + * + * @privateRemarks + * TODO: Allow all hierarchy configurations for packages. + * There isn't a real reason to restrict this, except the way the code is currently structured. */ - [ApiItemKind.Package]: FolderHierarchyConfiguration; + [ApiItemKind.Package]: DocumentHierarchyConfiguration | FolderHierarchyConfiguration; /** * Hierarchy configuration for the `EntryPoint` API item kind. * - * @remarks Always its own document, adjacent to the package document. - * @privateRemarks TODO: Make this fully configurable - there is no real reason for this policy to be baked in. + * @remarks + * Always its own document, adjacent to the package document. + * When a package only has a single entrypoint, this is skipped entirely and entrypoint children are rendered directly to the package document. + * + * @privateRemarks + * TODO: Allow all hierarchy configurations for packages. + * There isn't a real reason to restrict this, except the way the code is currently structured. */ [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; }; From 214ae3bff1958ac11fdf0f467968c155e3022bad Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 18 Dec 2024 21:44:10 +0000 Subject: [PATCH 17/54] fix: Test configs --- .../api-markdown-documenter/src/test/EndToEndTestUtilities.ts | 3 ++- tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts | 4 +++- .../api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts | 4 +++- 3 files changed, 8 insertions(+), 3 deletions(-) diff --git a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts index 29fa0026ea34..394743e53980 100644 --- a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts +++ b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts @@ -79,7 +79,7 @@ export namespace HierarchyConfigs { * @remarks Results in a small number of documents, but can lead to relatively large documents. */ export const flat: Partial = { - [ApiItemKind.Package]: outsideFolderConfig, + [ApiItemKind.Package]: defaultDocumentConfig, [ApiItemKind.CallSignature]: defaultSectionConfig, [ApiItemKind.Class]: defaultSectionConfig, @@ -92,6 +92,7 @@ export namespace HierarchyConfigs { [ApiItemKind.Interface]: defaultSectionConfig, [ApiItemKind.Method]: defaultSectionConfig, [ApiItemKind.MethodSignature]: defaultSectionConfig, + [ApiItemKind.Namespace]: defaultSectionConfig, [ApiItemKind.Property]: defaultSectionConfig, [ApiItemKind.PropertySignature]: defaultSectionConfig, [ApiItemKind.TypeAlias]: defaultSectionConfig, diff --git a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts index 55e6db45e280..c5c22c95d33e 100644 --- a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts @@ -51,7 +51,7 @@ const testConfigs = new Map< uriRoot: "docs", includeBreadcrumb: true, includeTopLevelDocumentHeading: false, - hierarchy: HierarchyConfigs.sparse, + hierarchy: HierarchyConfigs.flat, minimumReleaseLevel: ReleaseTag.Beta, // Only include `@public` and `beta` items in the docs suite }, ], @@ -69,6 +69,8 @@ const testConfigs = new Map< startingHeadingLevel: 2, }, ], + + // TODO: deep config ]); describe("HTML end-to-end tests", () => { diff --git a/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts index 30cb3487aed3..796f18819819 100644 --- a/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts @@ -51,7 +51,7 @@ const testConfigs = new Map< uriRoot: "docs", includeBreadcrumb: true, includeTopLevelDocumentHeading: false, - hierarchy: HierarchyConfigs.sparse, + hierarchy: HierarchyConfigs.flat, minimumReleaseLevel: ReleaseTag.Beta, // Only include `@public` and `beta` items in the docs suite }, ], @@ -69,6 +69,8 @@ const testConfigs = new Map< startingHeadingLevel: 2, }, ], + + // TODO: deep config ]); describe("Markdown end-to-end tests", () => { From 9786a34f50ea9ddde48378413b8806900de1c7ba Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 18 Dec 2024 21:54:22 +0000 Subject: [PATCH 18/54] fix(test): Fix configurations --- .../configuration/Hierarchy.ts | 39 ++++-- .../configuration/index.ts | 19 ++- .../src/api-item-transforms/index.ts | 7 ++ .../src/test/EndToEndTestUtilities.ts | 119 +++++++++--------- 4 files changed, 106 insertions(+), 78 deletions(-) diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts index 440272c17216..366291927f37 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts @@ -159,11 +159,13 @@ export type DocumentationHierarchyConfiguration = * * Uses the item's qualified API name, but is handled differently for the following items: * - * - Model: Uses "index". + * - CallSignature, ConstructSignature, IndexSignature: Uses a cleaned up variation on the type signature. * - * - Package: Uses the unscoped package name. + * - Model: Uses "API Overview". + * + * @privateRemarks Exported for testing purposes. */ -function defaultHeadingText(apiItem: ApiItem): string { +export function defaultHeadingText(apiItem: ApiItem): string { const kind = getApiItemKind(apiItem); switch (kind) { case ApiItemKind.Model: { @@ -184,7 +186,11 @@ function defaultHeadingText(apiItem: ApiItem): string { } } -const defaultSectionHierarchyConfig: SectionHierarchyConfiguration = { +/** + * Default {@link SectionHierarchyConfiguration} used by the system. + * @privateRemarks Exported for testing purposes. + */ +export const defaultSectionHierarchyConfig: SectionHierarchyConfiguration = { kind: HierarchyKind.Section, headingText: defaultHeadingText, }; @@ -195,8 +201,10 @@ const defaultSectionHierarchyConfig: SectionHierarchyConfiguration = { * Uses the item's qualified API name, but is handled differently for the following items: * * - Package: Uses the unscoped package name. + * + * @privateRemarks Exported for testing purposes. */ -function defaultDocumentName(apiItem: ApiItem): string { +export function defaultDocumentName(apiItem: ApiItem): string { const kind = getApiItemKind(apiItem); switch (kind) { case ApiItemKind.Package: { @@ -210,16 +218,29 @@ function defaultDocumentName(apiItem: ApiItem): string { } } -const defaultDocumentHierarchyConfig: DocumentHierarchyConfiguration = { +/** + * Default {@link DocumentHierarchyConfiguration} used by the system. + * @privateRemarks Exported for testing purposes. + */ +export const defaultDocumentHierarchyConfig: DocumentHierarchyConfiguration = { kind: HierarchyKind.Document, headingText: defaultHeadingText, documentName: defaultDocumentName, }; -// Default folder name is the same as the default document name. -const defaultFolderName = defaultDocumentName; +/** + * Default {@link SectionHierarchyConfiguration} used by the system. + * + * @remarks Default folder name is the same as the default document name. + * @privateRemarks Exported for testing purposes. + */ +export const defaultFolderName = defaultDocumentName; -const defaultFolderHierarchyConfig: FolderHierarchyConfiguration = { +/** + * Default {@link FolderHierarchyConfiguration} used by the system. + * @privateRemarks Exported for testing purposes. + */ +export const defaultFolderHierarchyConfig: FolderHierarchyConfiguration = { kind: HierarchyKind.Folder, headingText: defaultHeadingText, documentPlacement: FolderDocumentPlacement.Outside, // TODO diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts index 8ea88881fbe7..71be73272ca4 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts @@ -16,17 +16,24 @@ export { getDocumentationSuiteConfigurationWithDefaults as getDocumentationSuiteOptionsWithDefaults, } from "./DocumentationSuiteOptions.js"; export { - HierarchyKind, + defaultDocumentHierarchyConfig, + defaultDocumentName, + defaultFolderName, + defaultHeadingText, + defaultFolderHierarchyConfig, + defaultHierarchyConfiguration, + defaultSectionHierarchyConfig, + type DocumentationHierarchyConfiguration, type DocumentationHierarchyConfigurationBase, - type SectionHierarchyProperties, - type SectionHierarchyConfiguration, - type DocumentHierarchyProperties, type DocumentHierarchyConfiguration, + type DocumentHierarchyProperties, FolderDocumentPlacement, - type FolderHierarchyProperties, type FolderHierarchyConfiguration, - type DocumentationHierarchyConfiguration, + type FolderHierarchyProperties, type HierarchyConfiguration, + HierarchyKind, + type SectionHierarchyConfiguration, + type SectionHierarchyProperties, } from "./Hierarchy.js"; export { type ApiItemTransformations, diff --git a/tools/api-markdown-documenter/src/api-item-transforms/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/index.ts index 83db0edc1bb6..ae868f6301ab 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/index.ts @@ -22,6 +22,13 @@ export { type ApiItemTransformationOptions, type ApiItemTransformations, type DefaultDocumentationSuiteOptions, + defaultDocumentHierarchyConfig, + defaultDocumentName, + defaultFolderName, + defaultHeadingText, + defaultFolderHierarchyConfig, + defaultHierarchyConfiguration, + defaultSectionHierarchyConfig, type DocumentHierarchyConfiguration, type DocumentHierarchyProperties, type DocumentationSuiteConfiguration, diff --git a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts index 394743e53980..22edf8250ee2 100644 --- a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts +++ b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts @@ -12,13 +12,17 @@ import { expect } from "chai"; import { compare } from "dir-compare"; import { - ApiItemUtilities, - type DocumentHierarchyConfiguration, + defaultSectionHierarchyConfig, + defaultHeadingText, + defaultDocumentHierarchyConfig, + defaultFolderName, + defaultDocumentName, +} from "../api-item-transforms/index.js"; +import { FolderDocumentPlacement, HierarchyKind, type HierarchyConfiguration, type FolderHierarchyConfiguration, - type SectionHierarchyConfiguration, } from "../index.js"; const dirname = Path.dirname(fileURLToPath(import.meta.url)); @@ -47,22 +51,11 @@ export const testDataDirectoryPath = Path.resolve(dirname, "..", "..", "src", "t */ // eslint-disable-next-line @typescript-eslint/no-namespace export namespace HierarchyConfigs { - const defaultSectionConfig: SectionHierarchyConfiguration = { - kind: HierarchyKind.Section, - headingText: (apiItem) => apiItem.displayName, - }; - - const defaultDocumentConfig: DocumentHierarchyConfiguration = { - kind: HierarchyKind.Document, - documentName: (apiItem) => ApiItemUtilities.getFileSafeNameForApiItem(apiItem), - headingText: (apiItem) => apiItem.displayName, - }; - const outsideFolderConfig: FolderHierarchyConfiguration = { kind: HierarchyKind.Folder, documentPlacement: FolderDocumentPlacement.Outside, - documentName: (apiItem) => ApiItemUtilities.getFileSafeNameForApiItem(apiItem), - folderName: (apiItem) => ApiItemUtilities.getFileSafeNameForApiItem(apiItem), + documentName: defaultDocumentName, + folderName: defaultFolderName, headingText: (apiItem) => apiItem.displayName, }; @@ -70,8 +63,8 @@ export namespace HierarchyConfigs { kind: HierarchyKind.Folder, documentPlacement: FolderDocumentPlacement.Inside, documentName: "index", - folderName: (apiItem) => ApiItemUtilities.getFileSafeNameForApiItem(apiItem), - headingText: (apiItem) => apiItem.displayName, + folderName: defaultFolderName, + headingText: defaultHeadingText, }; /** @@ -79,24 +72,24 @@ export namespace HierarchyConfigs { * @remarks Results in a small number of documents, but can lead to relatively large documents. */ export const flat: Partial = { - [ApiItemKind.Package]: defaultDocumentConfig, - - [ApiItemKind.CallSignature]: defaultSectionConfig, - [ApiItemKind.Class]: defaultSectionConfig, - [ApiItemKind.Constructor]: defaultSectionConfig, - [ApiItemKind.ConstructSignature]: defaultSectionConfig, - [ApiItemKind.Enum]: defaultSectionConfig, - [ApiItemKind.EnumMember]: defaultSectionConfig, - [ApiItemKind.Function]: defaultSectionConfig, - [ApiItemKind.IndexSignature]: defaultSectionConfig, - [ApiItemKind.Interface]: defaultSectionConfig, - [ApiItemKind.Method]: defaultSectionConfig, - [ApiItemKind.MethodSignature]: defaultSectionConfig, - [ApiItemKind.Namespace]: defaultSectionConfig, - [ApiItemKind.Property]: defaultSectionConfig, - [ApiItemKind.PropertySignature]: defaultSectionConfig, - [ApiItemKind.TypeAlias]: defaultSectionConfig, - [ApiItemKind.Variable]: defaultSectionConfig, + [ApiItemKind.Package]: defaultDocumentHierarchyConfig, + + [ApiItemKind.CallSignature]: defaultSectionHierarchyConfig, + [ApiItemKind.Class]: defaultSectionHierarchyConfig, + [ApiItemKind.Constructor]: defaultSectionHierarchyConfig, + [ApiItemKind.ConstructSignature]: defaultSectionHierarchyConfig, + [ApiItemKind.Enum]: defaultSectionHierarchyConfig, + [ApiItemKind.EnumMember]: defaultSectionHierarchyConfig, + [ApiItemKind.Function]: defaultSectionHierarchyConfig, + [ApiItemKind.IndexSignature]: defaultSectionHierarchyConfig, + [ApiItemKind.Interface]: defaultSectionHierarchyConfig, + [ApiItemKind.Method]: defaultSectionHierarchyConfig, + [ApiItemKind.MethodSignature]: defaultSectionHierarchyConfig, + [ApiItemKind.Namespace]: defaultSectionHierarchyConfig, + [ApiItemKind.Property]: defaultSectionHierarchyConfig, + [ApiItemKind.PropertySignature]: defaultSectionHierarchyConfig, + [ApiItemKind.TypeAlias]: defaultSectionHierarchyConfig, + [ApiItemKind.Variable]: defaultSectionHierarchyConfig, }; /** @@ -106,22 +99,22 @@ export namespace HierarchyConfigs { export const sparse: Partial = { [ApiItemKind.Package]: outsideFolderConfig, - [ApiItemKind.CallSignature]: defaultDocumentConfig, - [ApiItemKind.Class]: defaultDocumentConfig, - [ApiItemKind.Constructor]: defaultDocumentConfig, - [ApiItemKind.ConstructSignature]: defaultDocumentConfig, - [ApiItemKind.Enum]: defaultDocumentConfig, - [ApiItemKind.EnumMember]: defaultDocumentConfig, - [ApiItemKind.Function]: defaultDocumentConfig, - [ApiItemKind.IndexSignature]: defaultDocumentConfig, - [ApiItemKind.Interface]: defaultDocumentConfig, - [ApiItemKind.Method]: defaultDocumentConfig, - [ApiItemKind.MethodSignature]: defaultDocumentConfig, - [ApiItemKind.Namespace]: defaultDocumentConfig, - [ApiItemKind.Property]: defaultDocumentConfig, - [ApiItemKind.PropertySignature]: defaultDocumentConfig, - [ApiItemKind.TypeAlias]: defaultDocumentConfig, - [ApiItemKind.Variable]: defaultDocumentConfig, + [ApiItemKind.CallSignature]: defaultDocumentHierarchyConfig, + [ApiItemKind.Class]: defaultDocumentHierarchyConfig, + [ApiItemKind.Constructor]: defaultDocumentHierarchyConfig, + [ApiItemKind.ConstructSignature]: defaultDocumentHierarchyConfig, + [ApiItemKind.Enum]: defaultDocumentHierarchyConfig, + [ApiItemKind.EnumMember]: defaultDocumentHierarchyConfig, + [ApiItemKind.Function]: defaultDocumentHierarchyConfig, + [ApiItemKind.IndexSignature]: defaultDocumentHierarchyConfig, + [ApiItemKind.Interface]: defaultDocumentHierarchyConfig, + [ApiItemKind.Method]: defaultDocumentHierarchyConfig, + [ApiItemKind.MethodSignature]: defaultDocumentHierarchyConfig, + [ApiItemKind.Namespace]: defaultDocumentHierarchyConfig, + [ApiItemKind.Property]: defaultDocumentHierarchyConfig, + [ApiItemKind.PropertySignature]: defaultDocumentHierarchyConfig, + [ApiItemKind.TypeAlias]: defaultDocumentHierarchyConfig, + [ApiItemKind.Variable]: defaultDocumentHierarchyConfig, }; /** @@ -138,17 +131,17 @@ export namespace HierarchyConfigs { [ApiItemKind.TypeAlias]: insideFolderConfig, // Items that get their own document, but do not introduce folder hierarchy: - [ApiItemKind.CallSignature]: defaultDocumentConfig, - [ApiItemKind.Constructor]: defaultDocumentConfig, - [ApiItemKind.ConstructSignature]: defaultDocumentConfig, - [ApiItemKind.EnumMember]: defaultDocumentConfig, - [ApiItemKind.Function]: defaultDocumentConfig, - [ApiItemKind.IndexSignature]: defaultDocumentConfig, - [ApiItemKind.Method]: defaultDocumentConfig, - [ApiItemKind.MethodSignature]: defaultDocumentConfig, - [ApiItemKind.Property]: defaultDocumentConfig, - [ApiItemKind.PropertySignature]: defaultDocumentConfig, - [ApiItemKind.Variable]: defaultDocumentConfig, + [ApiItemKind.CallSignature]: defaultDocumentHierarchyConfig, + [ApiItemKind.Constructor]: defaultDocumentHierarchyConfig, + [ApiItemKind.ConstructSignature]: defaultDocumentHierarchyConfig, + [ApiItemKind.EnumMember]: defaultDocumentHierarchyConfig, + [ApiItemKind.Function]: defaultDocumentHierarchyConfig, + [ApiItemKind.IndexSignature]: defaultDocumentHierarchyConfig, + [ApiItemKind.Method]: defaultDocumentHierarchyConfig, + [ApiItemKind.MethodSignature]: defaultDocumentHierarchyConfig, + [ApiItemKind.Property]: defaultDocumentHierarchyConfig, + [ApiItemKind.PropertySignature]: defaultDocumentHierarchyConfig, + [ApiItemKind.Variable]: defaultDocumentHierarchyConfig, }; } From 8bce322873f1516b062da6413c2bfaa3ef48b25a Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 18 Dec 2024 21:56:38 +0000 Subject: [PATCH 19/54] refactor: Move function --- .../ApiItemTransformUtilities.ts | 22 ++----------------- .../src/utilities/ApiItemUtilities.ts | 21 +++++++++++++++++- 2 files changed, 22 insertions(+), 21 deletions(-) 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 d696d8450a86..94a0736574ae 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts @@ -5,12 +5,13 @@ import { strict as assert } from "node:assert"; -import { type ApiItem, ApiItemKind, ReleaseTag } from "@microsoft/api-extractor-model"; +import { type ApiItem, type ApiItemKind, ReleaseTag } from "@microsoft/api-extractor-model"; import type { Heading } from "../Heading.js"; import type { Link } from "../Link.js"; import { getApiItemKind, + getFilteredParent, getQualifiedApiItemName, getReleaseTag, getValueOrDerived, @@ -282,25 +283,6 @@ function getHeadingIdForApiItem( return `${baseName}-${apiItemKind.toLowerCase()}`; } -/** - * Gets the "filtered" parent of the provided API item. - * - * @remarks This logic specifically skips items of the following kinds: - * - * - EntryPoint: skipped because any given Package item will have exactly 1 EntryPoint child with current version of - * API-Extractor, making this redundant in the hierarchy. We may need to revisit this in the future if/when - * API-Extractor adds support for multiple entrypoints. - * - * @param apiItem - The API item whose filtered parent will be returned. - */ -export function getFilteredParent(apiItem: ApiItem): ApiItem | undefined { - const parent = apiItem.parent; - if (parent?.kind === ApiItemKind.EntryPoint) { - return parent.parent; - } - return parent; -} - /** * Determines whether or not the specified API item is one that should be rendered to its own document * (as opposed to being rendered to a section under some ancestor item's document). diff --git a/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts b/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts index b48c4fe1d588..ffebc3e71ec2 100644 --- a/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts +++ b/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts @@ -36,10 +36,10 @@ import { import { PackageName } from "@rushstack/node-core-library"; import type { Logger } from "../Logging.js"; -import { getFilteredParent } from "../api-item-transforms/index.js"; /** * This module contains general `ApiItem`-related types and utilities. + * @remarks Note: the utilities here should not require any specific context or configuration. */ /** @@ -164,6 +164,25 @@ export enum ApiModifier { Sealed = "sealed", } +/** + * Gets the "filtered" parent of the provided API item. + * + * @remarks This logic specifically skips items of the following kinds: + * + * - EntryPoint: skipped because any given Package item will have exactly 1 EntryPoint child with current version of + * API-Extractor, making this redundant in the hierarchy. We may need to revisit this in the future if/when + * API-Extractor adds support for multiple entrypoints. + * + * @param apiItem - The API item whose filtered parent will be returned. + */ +export function getFilteredParent(apiItem: ApiItem): ApiItem | undefined { + const parent = apiItem.parent; + if (parent?.kind === ApiItemKind.EntryPoint) { + return parent.parent; + } + return parent; +} + /** * Adjusts the name of the item as needed. * Accounts for method overloads by adding a suffix such as "myMethod_2". From fda21fadc4bcddf1f877dfe1dde3770e4ed0239d Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 18 Dec 2024 22:57:26 +0000 Subject: [PATCH 20/54] test: Remove invalid test case --- .../src/test/TransformApiModelEndToEnd.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/api-markdown-documenter/src/test/TransformApiModelEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/TransformApiModelEndToEnd.test.ts index 1a57c8d6e46e..15540f0497ab 100644 --- a/tools/api-markdown-documenter/src/test/TransformApiModelEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/TransformApiModelEndToEnd.test.ts @@ -12,7 +12,7 @@ import { loadModel, transformApiModel, type ApiItemTransformationOptions } from import { HierarchyConfigs, testDataDirectoryPath } from "./EndToEndTestUtilities.js"; -const apiModels: string[] = ["empty-model", "simple-suite-test"]; +const apiModels: string[] = ["simple-suite-test"]; const testConfigs = new Map>([ [ From 3071431f57752e194ad813b79ad4ba03ec3d65cc Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 18 Dec 2024 23:31:04 +0000 Subject: [PATCH 21/54] fix: Document and folder naming --- .../api-markdown-documenter.alpha.api.md | 8 +- .../api-markdown-documenter.beta.api.md | 8 +- .../api-markdown-documenter.public.api.md | 8 +- .../src/ApiItemUtilitiesModule.ts | 1 - .../ApiItemTransformUtilities.ts | 188 ++++++++++++------ .../src/api-item-transforms/Utilities.ts | 2 +- .../configuration/Hierarchy.ts | 32 +-- .../api-item-transforms/helpers/Helpers.ts | 7 +- .../src/api-item-transforms/index.ts | 1 - .../src/test/EndToEndTestUtilities.ts | 2 - .../src/utilities/ApiItemUtilities.ts | 49 +++-- 11 files changed, 180 insertions(+), 126 deletions(-) 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 c2b155411f11..fc7eadb2b6d0 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 @@ -94,7 +94,6 @@ declare namespace ApiItemUtilities { getDefaultValueBlock, getDeprecatedBlock, getExampleBlocks, - getFileSafeNameForApiItem, getModifiers, getModifierTags, getQualifiedApiItemName, @@ -310,7 +309,7 @@ export interface DocumentHierarchyConfiguration extends DocumentationHierarchyCo // @public export interface DocumentHierarchyProperties extends SectionHierarchyProperties { - readonly documentName: string | ((apiItem: ApiItem) => string); + readonly documentName?: string | undefined | ((apiItem: ApiItem) => string | undefined); } // @public @@ -384,7 +383,7 @@ export interface FolderHierarchyConfiguration extends DocumentationHierarchyConf // @public export interface FolderHierarchyProperties extends DocumentHierarchyProperties { readonly documentPlacement: FolderDocumentPlacement | ((apiItem: ApiItem) => FolderDocumentPlacement); - readonly folderName: string | ((apiItem: ApiItem) => string); + readonly folderName: string | undefined | ((apiItem: ApiItem) => string | undefined); } // @public @@ -405,9 +404,6 @@ 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; 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 addab2101705..d864b131603e 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 @@ -94,7 +94,6 @@ declare namespace ApiItemUtilities { getDefaultValueBlock, getDeprecatedBlock, getExampleBlocks, - getFileSafeNameForApiItem, getModifiers, getModifierTags, getQualifiedApiItemName, @@ -310,7 +309,7 @@ export interface DocumentHierarchyConfiguration extends DocumentationHierarchyCo // @public export interface DocumentHierarchyProperties extends SectionHierarchyProperties { - readonly documentName: string | ((apiItem: ApiItem) => string); + readonly documentName?: string | undefined | ((apiItem: ApiItem) => string | undefined); } // @public @@ -384,7 +383,7 @@ export interface FolderHierarchyConfiguration extends DocumentationHierarchyConf // @public export interface FolderHierarchyProperties extends DocumentHierarchyProperties { readonly documentPlacement: FolderDocumentPlacement | ((apiItem: ApiItem) => FolderDocumentPlacement); - readonly folderName: string | ((apiItem: ApiItem) => string); + readonly folderName: string | undefined | ((apiItem: ApiItem) => string | undefined); } // @public @@ -405,9 +404,6 @@ 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; 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 86df9fa68a0e..2cf9115fd3f3 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 @@ -94,7 +94,6 @@ declare namespace ApiItemUtilities { getDefaultValueBlock, getDeprecatedBlock, getExampleBlocks, - getFileSafeNameForApiItem, getModifiers, getModifierTags, getQualifiedApiItemName, @@ -310,7 +309,7 @@ export interface DocumentHierarchyConfiguration extends DocumentationHierarchyCo // @public export interface DocumentHierarchyProperties extends SectionHierarchyProperties { - readonly documentName: string | ((apiItem: ApiItem) => string); + readonly documentName?: string | undefined | ((apiItem: ApiItem) => string | undefined); } // @public @@ -384,7 +383,7 @@ export interface FolderHierarchyConfiguration extends DocumentationHierarchyConf // @public export interface FolderHierarchyProperties extends DocumentHierarchyProperties { readonly documentPlacement: FolderDocumentPlacement | ((apiItem: ApiItem) => FolderDocumentPlacement); - readonly folderName: string | ((apiItem: ApiItem) => string); + readonly folderName: string | undefined | ((apiItem: ApiItem) => string | undefined); } // @public @@ -405,9 +404,6 @@ 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; diff --git a/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts b/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts index c9b06039218d..5caf1f665866 100644 --- a/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts +++ b/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts @@ -21,7 +21,6 @@ export { getDefaultValueBlock, getDeprecatedBlock, getExampleBlocks, - getFileSafeNameForApiItem, getModifiers, getModifierTags, getQualifiedApiItemName, 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 94a0736574ae..4fc5827ada51 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts @@ -5,7 +5,7 @@ import { strict as assert } from "node:assert"; -import { type ApiItem, type ApiItemKind, ReleaseTag } from "@microsoft/api-extractor-model"; +import { type ApiItem, ApiItemKind, ReleaseTag } from "@microsoft/api-extractor-model"; import type { Heading } from "../Heading.js"; import type { Link } from "../Link.js"; @@ -42,44 +42,6 @@ export interface ApiItemWithHierarchy< readonly hierarchy: THierarchy; } -/** - * Gets the nearest ancestor of the provided item that will have its own rendered document. - * - * @remarks - * This can be useful for determining the file path the item will ultimately be rendered under, - * as well as for generating links. - * - * @param apiItem - The API item for which we are generating a file path. - * @param hierarchyConfig - See {@link HierarchyConfiguration} - */ -function getFirstAncestorWithOwnDocument( - apiItem: ApiItem, - hierarchyConfig: Required, -): ApiItemWithHierarchy { - // Walk parentage until we reach an item kind that gets rendered to its own document. - // That is the document we will target with the generated link. - let hierarchyItem: ApiItem = apiItem; - while (!doesItemRequireOwnDocument(hierarchyItem, hierarchyConfig)) { - const parent = getFilteredParent(hierarchyItem); - if (parent === undefined) { - throw new Error( - `Walking hierarchy from "${apiItem.displayName}" does not converge on an item that is rendered ` + - `to its own document.`, - ); - } - hierarchyItem = parent; - } - - const hierarchyItemKind = getApiItemKind(hierarchyItem); - const hierarchy = hierarchyConfig[hierarchyItemKind]; - assert(hierarchy.kind !== HierarchyKind.Section); - - return { - apiItem: hierarchyItem, - hierarchy, - }; -} - /** * Creates a {@link Link} for the provided API item. * @@ -121,7 +83,7 @@ function getLinkUrlForApiItem( config: ApiItemTransformationConfiguration, ): string { const uriBase = config.getUriBaseOverrideForItem(apiItem) ?? config.uriRoot; - let documentPath = getDocumentPathForApiItem(apiItem, config); + let documentPath = getDocumentPathForApiItem(apiItem, config.hierarchy); // Omit "index" file name from path generated in links. // This can be considered an optimization in most cases, but some documentation systems also special-case @@ -140,6 +102,65 @@ function getLinkUrlForApiItem( return `${uriBase}/${documentPath}${headingPostfix}`; } +/** + * Walks up the provided API item's hierarchy until and API item is found that matches the provided predicate. + * + * @returns The matching item, if one was found. Otherwise, `undefined`. + * + * @param apiItem - The API item for which we are generating a file path. + * @param predicate - A function that returns `true` when the desired item is found. + */ +function findInHierarchy( + apiItem: ApiItem, + predicate: (item: ApiItem) => boolean, +): ApiItem | undefined { + let current: ApiItem | undefined = apiItem; + do { + if (predicate(current)) { + return current; + } + current = getFilteredParent(current); + } while (current !== undefined); + + return undefined; +} + +/** + * Gets the nearest ancestor of the provided item that will have its own rendered document. + * + * @remarks + * This can be useful for determining the file path the item will ultimately be rendered under, + * as well as for generating links. + * + * @param apiItem - The API item for which we are generating a file path. + * @param hierarchyConfig - See {@link HierarchyConfiguration} + */ +function getFirstAncestorWithOwnDocument( + apiItem: ApiItem, + hierarchyConfig: Required, +): ApiItemWithHierarchy { + // Walk parentage until we reach an item kind that gets rendered to its own document. + // That is the document we will target with the generated link. + const documentItem = findInHierarchy(apiItem, (item) => + doesItemRequireOwnDocument(item, hierarchyConfig), + ); + + if (documentItem === undefined) { + throw new Error( + `No ancestor of API item "${apiItem.displayName}" found that requires its own document.`, + ); + } + + const documentItemKind = getApiItemKind(documentItem); + const documentHierarchyConfig = hierarchyConfig[documentItemKind]; + assert(documentHierarchyConfig.kind !== HierarchyKind.Section); + + return { + apiItem: documentItem, + hierarchy: documentHierarchyConfig, + }; +} + /** * Gets the path to the document for the specified API item. * @@ -151,44 +172,43 @@ function getLinkUrlForApiItem( * The generated path is relative to {@link ApiItemTransformationConfiguration.uriRoot}. * * @param apiItem - The API item for which we are generating a file path. - * @param config - See {@link ApiItemTransformationConfiguration}. + * @param hierarchyConfig - See {@link HierarchyConfiguration}. */ export function getDocumentPathForApiItem( apiItem: ApiItem, - config: ApiItemTransformationConfiguration, + hierarchyConfig: HierarchyConfiguration, ): string { - const { apiItem: targetDocumentItem, hierarchy: targetDocumentHierarchy } = - getFirstAncestorWithOwnDocument(apiItem, config.hierarchy); + const targetDocument = getFirstAncestorWithOwnDocument(apiItem, hierarchyConfig); - const documentName = getValueOrDerived( - targetDocumentHierarchy.documentName, - targetDocumentItem, - ); + const documentName = getDocumentNameForItem(targetDocument, hierarchyConfig); const pathSegments: string[] = []; // For the document itself, if its item creates folder-wise hierarchy, we need to refer to the hierarchy config // to determine whether or not it should be placed inside or outside that folder. if ( - targetDocumentHierarchy.kind === HierarchyKind.Folder && - targetDocumentHierarchy.documentPlacement === FolderDocumentPlacement.Inside + targetDocument.hierarchy.kind === HierarchyKind.Folder && + targetDocument.hierarchy.documentPlacement === FolderDocumentPlacement.Inside ) { - const folderName = getValueOrDerived( - targetDocumentHierarchy.folderName, - targetDocumentItem, + const folderName = getFolderNameForItem( + targetDocument as ApiItemWithHierarchy, + hierarchyConfig, ); pathSegments.push(`${folderName}/${documentName}`); } else { pathSegments.push(documentName); } - let currentItem: ApiItem | undefined = getFilteredParent(targetDocumentItem); + let currentItem: ApiItem | undefined = getFilteredParent(targetDocument.apiItem); while (currentItem !== undefined) { const currentItemKind = getApiItemKind(currentItem); - const currentItemHierarchy = config.hierarchy[currentItemKind]; + const currentItemHierarchy = hierarchyConfig[currentItemKind]; // Push path segments for all folders in the hierarchy if (currentItemHierarchy.kind === HierarchyKind.Folder) { - const folderName = getValueOrDerived(currentItemHierarchy.folderName, currentItem); + const folderName = getFolderNameForItem( + { apiItem: currentItem, hierarchy: currentItemHierarchy }, + hierarchyConfig, + ); pathSegments.push(folderName); } currentItem = getFilteredParent(currentItem); @@ -200,6 +220,58 @@ export function getDocumentPathForApiItem( return pathSegments.join("/"); } +function getDocumentNameForItem( + item: ApiItemWithHierarchy, + hierarchyConfig: HierarchyConfiguration, +): string { + return ( + getValueOrDerived(item.hierarchy.documentName, item.apiItem) ?? + createQualifiedDocumentNameForApiItem(item.apiItem, hierarchyConfig) + ); +} + +function getFolderNameForItem( + item: ApiItemWithHierarchy, + hierarchyConfig: HierarchyConfiguration, +): string { + return ( + getValueOrDerived(item.hierarchy.folderName, item.apiItem) ?? + // If no folder name is configured, use the system-default document name + createQualifiedDocumentNameForApiItem(item.apiItem, hierarchyConfig) + ); +} + +function createQualifiedDocumentNameForApiItem( + apiItem: ApiItem, + hierarchyConfig: HierarchyConfiguration, +): string { + const apiItemKind = getApiItemKind(apiItem); + let documentName = getQualifiedApiItemName(apiItem); + if (apiItemKind !== ApiItemKind.Package) { + // If the item is not a package, append its "kind" to the document name to ensure uniqueness. + // Packages strictly live at the root of the document hierarchy (beneath the model), and only + // packages may appear there, so this information is redundant. + const postfix = apiItemKind.toLocaleLowerCase(); + documentName = `${documentName}-${postfix}`; + } + + // Walk up hierarchy until we find the nearest ancestor that yields folder hierarchy (or until we hit the model root). + // Qualify the document name with all ancestral items up to that point to ensure document name uniqueness. + + let currentItem: ApiItem | undefined = getFilteredParent(apiItem); + + while ( + currentItem !== undefined && + currentItem.kind !== "Model" && + hierarchyConfig[getApiItemKind(currentItem)].kind !== HierarchyKind.Folder + ) { + documentName = `${getQualifiedApiItemName(currentItem)}-${documentName}`; + currentItem = getFilteredParent(currentItem); + } + + return documentName; +} + /** * Generates a {@link Heading} for the specified API item. * @@ -238,8 +310,10 @@ function getHeadingTextForApiItem( return getValueOrDerived(hierarchy.headingText, apiItem); } +// TODO: this doesn't actually return `undefined` for own document. Verify and fix. /** - * Generates a unique heading ID for the provided API item. + * Generates a heading ID for the provided API item. + * Guaranteed to be unique within the document to which the API item is being rendered. * * @remarks * Notes: diff --git a/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts b/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts index 78045146c2e4..9299429bc163 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts @@ -45,7 +45,7 @@ export function createDocument( return new DocumentNode({ apiItem: documentItem, children: contents, - documentPath: getDocumentPathForApiItem(documentItem, config), + documentPath: getDocumentPathForApiItem(documentItem, config.hierarchy), }); } diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts index 366291927f37..7b49883dcba7 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts @@ -6,8 +6,6 @@ import { type ApiDeclaredItem, type ApiItem, ApiItemKind } from "@microsoft/api-extractor-model"; import { - getQualifiedApiItemName, - getFileSafeNameForApiItem, getSingleLineExcerptText, getApiItemKind, type ValidApiItemKind, @@ -82,8 +80,9 @@ export interface SectionHierarchyConfiguration export interface DocumentHierarchyProperties extends SectionHierarchyProperties { /** * Document name to use for the API item. + * @remarks `undefined` indicates that the system default should be used. */ - readonly documentName: string | ((apiItem: ApiItem) => string); + readonly documentName?: string | undefined | ((apiItem: ApiItem) => string | undefined); } /** @@ -131,8 +130,9 @@ export interface FolderHierarchyProperties extends DocumentHierarchyProperties { /** * Folder name to use for the API item. + * @remarks `undefined` indicates that the system default should be used. */ - readonly folderName: string | ((apiItem: ApiItem) => string); + readonly folderName: string | undefined | ((apiItem: ApiItem) => string | undefined); } /** @@ -198,22 +198,21 @@ export const defaultSectionHierarchyConfig: SectionHierarchyConfiguration = { /** * Default {@link DocumentHierarchyProperties.documentName} for non-folder hierarchy documents. * - * Uses the item's qualified API name, but is handled differently for the following items: + * Uses the item's scoped and qualified API name, but is handled differently for the following items: * - * - Package: Uses the unscoped package name. + * - Model: "index" * * @privateRemarks Exported for testing purposes. */ -export function defaultDocumentName(apiItem: ApiItem): string { +export function defaultDocumentName(apiItem: ApiItem): string | undefined { const kind = getApiItemKind(apiItem); switch (kind) { - case ApiItemKind.Package: { - return getFileSafeNameForApiItem(apiItem); + case ApiItemKind.Model: { + return "index"; } default: { - const base = getQualifiedApiItemName(apiItem); - const postfix = apiItem.kind.toLocaleLowerCase(); - return `${base}-${postfix}`; + // Let the system generate a unique name that accounts for folder hierarchy. + return undefined; } } } @@ -231,10 +230,9 @@ export const defaultDocumentHierarchyConfig: DocumentHierarchyConfiguration = { /** * Default {@link SectionHierarchyConfiguration} used by the system. * - * @remarks Default folder name is the same as the default document name. * @privateRemarks Exported for testing purposes. */ -export const defaultFolderName = defaultDocumentName; +export const defaultFolderName = undefined; /** * Default {@link FolderHierarchyConfiguration} used by the system. @@ -243,8 +241,8 @@ export const defaultFolderName = defaultDocumentName; export const defaultFolderHierarchyConfig: FolderHierarchyConfiguration = { kind: HierarchyKind.Folder, headingText: defaultHeadingText, - documentPlacement: FolderDocumentPlacement.Outside, // TODO documentName: defaultDocumentName, + documentPlacement: FolderDocumentPlacement.Outside, // TODO // documentName: "index", // Documents for items that get their own folder are always named "index" by default. folderName: defaultFolderName, }; @@ -266,7 +264,9 @@ export type HierarchyConfiguration = { /** * Hierarchy configuration for the `Model` API item kind. * - * @remarks Always its own document. Never introduces folder hierarchy. + * @remarks + * Always its own document. Never introduces folder hierarchy. + * This is an important invariant, as it ensures that there is always at least one document in the output. */ [ApiItemKind.Model]: DocumentHierarchyConfiguration; 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 46a7e85b4fcf..000532f78172 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 @@ -58,12 +58,9 @@ import { getReturnsBlock, getApiItemKind, type ValidApiItemKind, -} from "../../utilities/index.js"; -import { - doesItemKindRequireOwnDocument, getFilteredParent, - getLinkForApiItem, -} from "../ApiItemTransformUtilities.js"; +} from "../../utilities/index.js"; +import { doesItemKindRequireOwnDocument, getLinkForApiItem } from "../ApiItemTransformUtilities.js"; import { transformTsdocSection } from "../TsdocNodeTransforms.js"; import { getTsdocNodeTransformationOptions } from "../Utilities.js"; import { HierarchyKind, type ApiItemTransformationConfiguration } from "../configuration/index.js"; diff --git a/tools/api-markdown-documenter/src/api-item-transforms/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/index.ts index ae868f6301ab..1dd855960c5f 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/index.ts @@ -11,7 +11,6 @@ export { doesItemRequireOwnDocument, doesItemKindRequireOwnDocument, filterItems, - getFilteredParent, getHeadingForApiItem, getLinkForApiItem, shouldItemBeIncluded, diff --git a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts index 22edf8250ee2..899424d1435d 100644 --- a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts +++ b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts @@ -16,7 +16,6 @@ import { defaultHeadingText, defaultDocumentHierarchyConfig, defaultFolderName, - defaultDocumentName, } from "../api-item-transforms/index.js"; import { FolderDocumentPlacement, @@ -54,7 +53,6 @@ export namespace HierarchyConfigs { const outsideFolderConfig: FolderHierarchyConfiguration = { kind: HierarchyKind.Folder, documentPlacement: FolderDocumentPlacement.Outside, - documentName: defaultDocumentName, folderName: defaultFolderName, headingText: (apiItem) => apiItem.displayName, }; diff --git a/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts b/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts index ffebc3e71ec2..87dc37419728 100644 --- a/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts +++ b/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts @@ -183,6 +183,29 @@ export function getFilteredParent(apiItem: ApiItem): ApiItem | undefined { return parent; } +/** + * Converts bad filename characters to underscores. + */ +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(); +} + +/** + * Gets a filename-safe representation of the API item's display name. + */ +function getFileSafeNameForApiItem(apiItem: ApiItem): string { + return apiItem.kind === ApiItemKind.Package + ? getSafeFilenameForName(getUnscopedPackageName(apiItem as ApiPackage)) + : getSafeFilenameForName(apiItem.displayName); +} + +// TODO: rename to be a bit more specific /** * Adjusts the name of the item as needed. * Accounts for method overloads by adding a suffix such as "myMethod_2". @@ -192,7 +215,7 @@ export function getFilteredParent(apiItem: ApiItem): ApiItem | undefined { * @public */ export function getQualifiedApiItemName(apiItem: ApiItem): string { - let qualifiedName: string = getSafeFilenameForName(apiItem.displayName); + let qualifiedName: string = getFileSafeNameForApiItem(apiItem); 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) @@ -568,30 +591,6 @@ export function getConciseSignature(apiItem: ApiItem): string { return apiItem.displayName; } -/** - * Gets a filename-safe representation of the API item's display name. - * - * @public - */ -export function getFileSafeNameForApiItem(apiItem: ApiItem): string { - return apiItem.kind === ApiItemKind.Package - ? getSafeFilenameForName(getUnscopedPackageName(apiItem as ApiPackage)) - : getSafeFilenameForName(apiItem.displayName); -} - -/** - * Converts bad filename characters to underscores. - */ -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. * From e4f184c070e33ebc44b6e9f2781ad6e96ce8c605 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Fri, 20 Dec 2024 22:11:12 +0000 Subject: [PATCH 22/54] docs: Fix comment --- .../src/api-item-transforms/configuration/DocumentationSuite.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 b2179f1d0343..345580ed72fb 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 @@ -147,7 +147,7 @@ export type DocumentationSuiteOptions = Omit< }; /** - * Contains a list of default documentation transformations, used by {@link DocumentationSuiteOptions}. + * Contains a list of default {@link DocumentationSuiteConfiguration} functions. * * @public */ From 25162b57982ea5e86989ead2293674e372263710 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Fri, 20 Dec 2024 22:16:09 +0000 Subject: [PATCH 23/54] refactor: Remove unneeded type alias --- .../src/api-item-transforms/configuration/Hierarchy.ts | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts index 7b49883dcba7..806cc46667d9 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts @@ -295,11 +295,6 @@ export type HierarchyConfiguration = { [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; }; -/** - * Partial {@link HierarchyConfiguration} provided as user input. - */ -export type HierarchyOptions = Partial; - /** * Default {@link HierarchyConfiguration}. */ @@ -340,7 +335,7 @@ export const defaultHierarchyConfiguration: HierarchyConfiguration = { * in the remainder with defaults. */ export function getHierarchyOptionsWithDefaults( - inputOptions: HierarchyOptions | undefined, + inputOptions?: Partial, ): HierarchyConfiguration { return { ...defaultHierarchyConfiguration, ...inputOptions }; } From 92ecd59f5a5f61c7a69bae1f8dec2760c9bd1bd5 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Fri, 20 Dec 2024 22:16:56 +0000 Subject: [PATCH 24/54] docs: Remove obsolete TODO --- .../src/api-item-transforms/configuration/Transformations.ts | 2 -- 1 file changed, 2 deletions(-) diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Transformations.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Transformations.ts index 926ae54e698f..77fcbaeb1e08 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Transformations.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Transformations.ts @@ -59,8 +59,6 @@ export type TransformApiItemWithoutChildren = ( * * @privateRemarks TODO: Make transformation for package items configurable * - * @privateRemarks TODO: re-express property names in terms of `ApiItemKind` for consistency. - * * @public */ export interface ApiItemTransformations { From 7e2dbd58d8a6af2cf15720e11aefc0e47ed646a4 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Fri, 20 Dec 2024 22:20:13 +0000 Subject: [PATCH 25/54] docs: Remove TODOs --- tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts | 5 +---- .../src/test/MarkdownEndToEnd.test.ts | 5 +---- 2 files changed, 2 insertions(+), 8 deletions(-) diff --git a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts index c5c22c95d33e..82b0df5df667 100644 --- a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts @@ -28,10 +28,7 @@ const testTemporaryDirectoryPath = Path.resolve(testTemporaryDirectoryPathBase, */ const snapshotsDirectoryPath = Path.resolve(snapshotsDirectoryPathBase, "html"); -const apiModels: string[] = [ - // TODO: empty model - "simple-suite-test", -]; +const apiModels: string[] = ["simple-suite-test"]; const testConfigs = new Map< string, diff --git a/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts index 796f18819819..3c7302bd04a9 100644 --- a/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts @@ -28,10 +28,7 @@ const testTemporaryDirectoryPath = Path.resolve(testTemporaryDirectoryPathBase, */ const snapshotsDirectoryPath = Path.resolve(snapshotsDirectoryPathBase, "markdown"); -const apiModels: string[] = [ - // TODO: empty model - "simple-suite-test", -]; +const apiModels: string[] = ["simple-suite-test"]; const testConfigs = new Map< string, From 1c6e34a78b0b73990d2f5cbcf005bc6d743ac79b Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Fri, 20 Dec 2024 22:22:49 +0000 Subject: [PATCH 26/54] test: Update test structure --- .../test/TransformApiModelEndToEnd.test.ts | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/tools/api-markdown-documenter/src/test/TransformApiModelEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/TransformApiModelEndToEnd.test.ts index 15540f0497ab..0e7eeb34148d 100644 --- a/tools/api-markdown-documenter/src/test/TransformApiModelEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/TransformApiModelEndToEnd.test.ts @@ -48,7 +48,7 @@ const testConfigs = new Map { +describe("API model transformation end-to-end tests", () => { for (const modelName of apiModels) { // Input directory for the model const modelDirectoryPath = Path.join(testDataDirectoryPath, modelName); @@ -59,17 +59,19 @@ describe("API item transformation end-to-end tests", () => { apiModel = await loadModel({ modelDirectoryPath }); }); - for (const [configName, inputConfig] of testConfigs) { - it(configName, async () => { - const options: ApiItemTransformationOptions = { - ...inputConfig, - apiModel, - }; + describe("Ensure no duplicate document paths", () => { + for (const [configName, inputConfig] of testConfigs) { + it(configName, async () => { + const options: ApiItemTransformationOptions = { + ...inputConfig, + apiModel, + }; - const documents = transformApiModel(options); - checkForDuplicateDocumentPaths(documents); - }); - } + const documents = transformApiModel(options); + checkForDuplicateDocumentPaths(documents); + }); + } + }); }); } }); From 2dc244793f57dc795b10058b12a1954e09ae9b15 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Fri, 20 Dec 2024 22:25:03 +0000 Subject: [PATCH 27/54] remove: Unused utility function --- .../src/utilities/ApiItemUtilities.ts | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts b/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts index 1ba38dad18bd..465b2dd760ac 100644 --- a/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts +++ b/tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts @@ -86,24 +86,6 @@ export type ApiMemberKind = Exclude< ApiItemKind.EntryPoint | ApiItemKind.Model | ApiItemKind.Package >; -/** - * Gets the {@link ApiMemberKind} for the provided API item. Throws if the item's kind is not a valid member kind. - */ -export function getApiMemberKind(apiItem: ApiItem): ApiMemberKind { - switch (apiItem.kind) { - case ApiItemKind.EntryPoint: - case ApiItemKind.Model: - case ApiItemKind.Package: { - throw new Error( - `Expected API item to be a member kind, but got "${apiItem.kind}": "${apiItem.displayName}".`, - ); - } - default: { - return getApiItemKind(apiItem) as ApiMemberKind; - } - } -} - /** * `ApiItem` union type representing function-like API kinds. * From 56b58e82e5ae58d67a9af7e46408e124653594dc Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Fri, 20 Dec 2024 23:07:24 +0000 Subject: [PATCH 28/54] test: Add deep config end-to-end tests --- .../src/test/HtmlEndToEnd.test.ts | 11 +- .../src/test/MarkdownEndToEnd.test.ts | 11 +- .../simple-suite-test/deep-config/index.html | 32 +++ .../deep-config/test-suite-a/index.html | 222 ++++++++++++++++++ .../_constructor_-constructor.html | 44 ++++ .../abstractpropertygetter-property.html | 21 ++ .../testabstractclass-class/index.html | 97 ++++++++ .../protectedproperty-property.html | 21 ++ .../publicabstractmethod-method.html | 20 ++ .../sealedmethod-method.html | 25 ++ .../virtualmethod-method.html | 25 ++ .../_constructor_-constructor.html | 61 +++++ .../abstractpropertygetter-property.html | 21 ++ .../test-suite-a/testclass-class/index.html | 196 ++++++++++++++++ .../publicabstractmethod-method.html | 20 ++ .../testclasseventproperty-property.html | 25 ++ .../testclassgetterproperty-property.html | 25 ++ .../testclassmethod-method.html | 52 ++++ .../testclassproperty-property.html | 25 ++ .../testclassstaticmethod-method.html | 44 ++++ .../testclassstaticproperty-property.html | 21 ++ .../testclass-class/virtualmethod-method.html | 24 ++ .../test-suite-a/testconst-variable.html | 25 ++ ...onstwithemptydeprecatedblock-variable.html | 24 ++ .../testemptyinterface-interface/index.html | 20 ++ .../test-suite-a/testenum-enum/index.html | 96 ++++++++ .../testenumvalue1-enummember.html | 24 ++ .../testenumvalue2-enummember.html | 24 ++ .../testenumvalue3-enummember.html | 24 ++ .../test-suite-a/testfunction-function.html | 84 +++++++ ...tfunctionreturninginlinetype-function.html | 25 ++ ...ionreturningintersectiontype-function.html | 28 +++ ...stfunctionreturninguniontype-function.html | 25 ++ .../_call_-callsignature.html | 24 ++ .../_call__1-callsignature.html | 24 ++ .../_new_-constructsignature.html | 24 ++ .../getterproperty-property.html | 21 ++ .../testinterface-interface/index.html | 162 +++++++++++++ ...badinheritdoctarget-propertysignature.html | 21 ++ .../setterproperty-property.html | 21 ++ ...tclasseventproperty-propertysignature.html | 25 ++ .../testinterfacemethod-methodsignature.html | 24 ++ ...stinterfaceproperty-propertysignature.html | 25 ++ ...alinterfaceproperty-propertysignature.html | 21 ++ .../index.html | 52 ++++ .../testmethod-methodsignature.html | 48 ++++ .../_indexer_-indexsignature.html | 20 ++ .../index.html | 37 +++ .../index.html | 62 +++++ .../testproperty-propertysignature.html | 25 ++ .../testmappedtype-typealias/index.html | 24 ++ .../testmodule-namespace/foo-variable.html | 20 ++ .../testmodule-namespace/index.html | 35 +++ .../testnamespace-namespace/index.html | 168 +++++++++++++ .../_constructor_-constructor.html | 39 +++ .../testclass-class/index.html | 77 ++++++ .../testclassmethod-method.html | 52 ++++ .../testclassproperty-property.html | 21 ++ .../testconst-variable.html | 21 ++ .../testenum-enum/index.html | 55 +++++ .../testenumvalue1-enummember.html | 20 ++ .../testenumvalue2-enummember.html | 20 ++ .../testfunction-function.html | 48 ++++ .../testinterface-interface/index.html | 64 +++++ .../testinterfacemethod-methodsignature.html | 21 ++ ...stinterfaceproperty-propertysignature.html | 22 ++ .../testsubnamespace-namespace/index.html | 20 ++ .../testtypealias-typealias/index.html | 20 ++ .../typealias-typealias/index.html | 24 ++ .../foo-interface/bar-propertysignature.html | 25 ++ .../test-suite-b/foo-interface/index.html | 39 +++ .../deep-config/test-suite-b/index.html | 31 +++ .../simple-suite-test/deep-config/index.md | 8 + .../deep-config/test-suite-a/index.md | 92 ++++++++ .../_constructor_-constructor.md | 18 ++ .../abstractpropertygetter-property.md | 13 + .../testabstractclass-class/index.md | 32 +++ .../protectedproperty-property.md | 13 + .../publicabstractmethod-method.md | 11 + .../sealedmethod-method.md | 18 ++ .../virtualmethod-method.md | 18 ++ .../_constructor_-constructor.md | 24 ++ .../abstractpropertygetter-property.md | 13 + .../test-suite-a/testclass-class/index.md | 68 ++++++ .../publicabstractmethod-method.md | 11 + .../testclasseventproperty-property.md | 17 ++ .../testclassgetterproperty-property.md | 19 ++ .../testclass-class/testclassmethod-method.md | 32 +++ .../testclassproperty-property.md | 17 ++ .../testclassstaticmethod-method.md | 23 ++ .../testclassstaticproperty-property.md | 13 + .../testclass-class/virtualmethod-method.md | 16 ++ .../test-suite-a/testconst-variable.md | 17 ++ ...tconstwithemptydeprecatedblock-variable.md | 15 ++ .../testemptyinterface-interface/index.md | 11 + .../test-suite-a/testenum-enum/index.md | 77 ++++++ .../testenumvalue1-enummember.md | 15 ++ .../testenumvalue2-enummember.md | 15 ++ .../testenumvalue3-enummember.md | 15 ++ .../test-suite-a/testfunction-function.md | 40 ++++ ...estfunctionreturninginlinetype-function.md | 20 ++ ...ctionreturningintersectiontype-function.md | 21 ++ ...testfunctionreturninguniontype-function.md | 17 ++ .../_call_-callsignature.md | 15 ++ .../_call__1-callsignature.md | 15 ++ .../_new_-constructsignature.md | 15 ++ .../getterproperty-property.md | 13 + .../testinterface-interface/index.md | 60 +++++ ...thbadinheritdoctarget-propertysignature.md | 11 + .../setterproperty-property.md | 14 ++ ...estclasseventproperty-propertysignature.md | 17 ++ .../testinterfacemethod-methodsignature.md | 15 ++ ...testinterfaceproperty-propertysignature.md | 17 ++ ...onalinterfaceproperty-propertysignature.md | 13 + .../index.md | 31 +++ .../testmethod-methodsignature.md | 27 +++ .../_indexer_-indexsignature.md | 13 + .../index.md | 17 ++ .../index.md | 27 +++ .../testproperty-propertysignature.md | 17 ++ .../testmappedtype-typealias/index.md | 17 ++ .../testmodule-namespace/foo-variable.md | 11 + .../testmodule-namespace/index.md | 9 + .../testnamespace-namespace/index.md | 77 ++++++ .../_constructor_-constructor.md | 17 ++ .../testclass-class/index.md | 29 +++ .../testclass-class/testclassmethod-method.md | 31 +++ .../testclassproperty-property.md | 13 + .../testconst-variable.md | 13 + .../testenum-enum/index.md | 34 +++ .../testenumvalue1-enummember.md | 11 + .../testenumvalue2-enummember.md | 11 + .../testfunction-function.md | 27 +++ .../testinterface-interface/index.md | 27 +++ .../testinterfacemethod-methodsignature.md | 13 + ...testinterfaceproperty-propertysignature.md | 15 ++ .../testsubnamespace-namespace/index.md | 11 + .../testtypealias-typealias/index.md | 11 + .../test-suite-a/typealias-typealias/index.md | 15 ++ .../foo-interface/bar-propertysignature.md | 17 ++ .../test-suite-b/foo-interface/index.md | 17 ++ .../deep-config/test-suite-b/index.md | 9 + 142 files changed, 4453 insertions(+), 2 deletions(-) create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/_constructor_-constructor.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/abstractpropertygetter-property.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/protectedproperty-property.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/publicabstractmethod-method.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/sealedmethod-method.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/virtualmethod-method.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/_constructor_-constructor.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/abstractpropertygetter-property.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/publicabstractmethod-method.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclasseventproperty-property.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassgetterproperty-property.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassmethod-method.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassproperty-property.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticmethod-method.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticproperty-property.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/virtualmethod-method.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testconst-variable.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testconstwithemptydeprecatedblock-variable.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testemptyinterface-interface/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue1-enummember.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue2-enummember.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue3-enummember.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunction-function.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturninginlinetype-function.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturningintersectiontype-function.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturninguniontype-function.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call_-callsignature.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call__1-callsignature.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_new_-constructsignature.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/getterproperty-property.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/setterproperty-property.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testclasseventproperty-propertysignature.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfacemethod-methodsignature.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmappedtype-typealias/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/foo-variable.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testconst-variable.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testfunction-function.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testsubnamespace-namespace/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testtypealias-typealias/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/typealias-typealias/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/foo-interface/bar-propertysignature.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/foo-interface/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/index.html create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/_constructor_-constructor.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/abstractpropertygetter-property.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/protectedproperty-property.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/publicabstractmethod-method.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/sealedmethod-method.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/virtualmethod-method.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/_constructor_-constructor.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/abstractpropertygetter-property.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/publicabstractmethod-method.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclasseventproperty-property.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassgetterproperty-property.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassmethod-method.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassproperty-property.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticmethod-method.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticproperty-property.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/virtualmethod-method.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testconst-variable.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testconstwithemptydeprecatedblock-variable.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testemptyinterface-interface/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue1-enummember.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue2-enummember.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue3-enummember.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunction-function.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturninginlinetype-function.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturningintersectiontype-function.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturninguniontype-function.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call_-callsignature.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call__1-callsignature.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_new_-constructsignature.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/getterproperty-property.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/setterproperty-property.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testclasseventproperty-propertysignature.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfacemethod-methodsignature.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmappedtype-typealias/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/foo-variable.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testconst-variable.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testfunction-function.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testsubnamespace-namespace/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testtypealias-typealias/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/typealias-typealias/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/foo-interface/bar-propertysignature.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/foo-interface/index.md create mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/index.md diff --git a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts index 82b0df5df667..e87a4253b31f 100644 --- a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts @@ -67,7 +67,16 @@ const testConfigs = new Map< }, ], - // TODO: deep config + // A sample "deep" configuration. + // All "parent" API items generate hierarchy. + // All other items are rendered as documents under their parent hierarchy. + [ + "deep-config", + { + uriRoot: ".", + hierarchy: HierarchyConfigs.deep, + }, + ], ]); describe("HTML end-to-end tests", () => { diff --git a/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts index 3c7302bd04a9..d72107c1142f 100644 --- a/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts @@ -67,7 +67,16 @@ const testConfigs = new Map< }, ], - // TODO: deep config + // A sample "deep" configuration. + // All "parent" API items generate hierarchy. + // All other items are rendered as documents under their parent hierarchy. + [ + "deep-config", + { + uriRoot: ".", + hierarchy: HierarchyConfigs.deep, + }, + ], ]); describe("Markdown end-to-end tests", () => { diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/index.html new file mode 100644 index 000000000000..e6bc549b6dba --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/index.html @@ -0,0 +1,32 @@ + + + + + + +
+

API Overview

+
+

Packages

+ + + + + + + + + + + + + + + + + +
PackageDescription
test-suite-aTest package
test-suite-b
+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/index.html new file mode 100644 index 000000000000..69b329f3c37e --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/index.html @@ -0,0 +1,222 @@ + + + + + + +
+

test-suite-a

+
+

Packages > test-suite-a

+
+
+

Test package

+
+
+

Remarks

+

+

This remarks block includes a bulleted list!

+

- Bullet 1

+

- Bullet 2

+

And an ordered list for good measure!

+

1. List item 1

+

2. List item 2

+

3. List item 3

+

Also, here is a link test, including a bad link, because we should have some reasonable support if this happens:

+

- Good link (no alias): TestClass

+

- Good link (with alias): function alias text

+

- Bad link (no alias): InvalidItem

+

- Bad link (with alias): even though I link to an invalid item, I would still like this text to be rendered

+

+
+
+

Example

+

+

A test example

const foo = bar; +

+
+
+

Interfaces

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
InterfaceDescription
TestEmptyInterfaceAn empty interface
TestInterfaceTest interface
TestInterfaceExtendingOtherInterfacesTest interface that extends other interfaces
TestInterfaceWithIndexSignatureAn interface with an index signature.
TestInterfaceWithTypeParameterTest interface with generic type parameter
+
+
+

Classes

+ + + + + + + + + + + + + + + + + +
ClassDescription
TestAbstractClassA test abstract class.
TestClassTest class
+
+
+

Enumerations

+ + + + + + + + + + + + + +
EnumDescription
TestEnumTest Enum
+
+
+

Types

+ + + + + + + + + + + + + + + + + +
TypeAliasDescription
TestMappedTypeTest Mapped Type, using TestEnum
TypeAliasTest Type-Alias
+
+
+

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FunctionAlertsReturn TypeDescription
testFunction(testParameter, testOptionalParameter)AlphaTTypeParameterTest function
testFunctionReturningInlineType(){ foo: number; bar: TestEnum; }Test function that returns an inline type
testFunctionReturningIntersectionType()DeprecatedTestEmptyInterface & TestInterfaceWithTypeParameter<number>Test function that returns an inline type
testFunctionReturningUnionType()string | TestInterfaceTest function that returns an inline type
+
+
+

Variables

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
VariableAlertsModifiersTypeDescription
testConstBetareadonlyTest Constant
testConstWithEmptyDeprecatedBlockDeprecatedreadonlystringI have a @deprecated tag with an empty comment block.
+
+
+

Namespaces

+ + + + + + + + + + + + + + + + + +
NamespaceDescription
TestModule
TestNamespaceTest Namespace
+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/_constructor_-constructor.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/_constructor_-constructor.html new file mode 100644 index 000000000000..01f49f0eac47 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/_constructor_-constructor.html @@ -0,0 +1,44 @@ + + + + + + +
+

(constructor)

+
+

Packages > test-suite-a > TestAbstractClass > (constructor)(privateProperty, protectedProperty)

+
+
+

This is a {@customTag constructor}.

+
+
+

Signature

protected constructor(privateProperty: number, protectedProperty: TestEnum); +
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
privatePropertynumber
protectedPropertyTestEnum
+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/abstractpropertygetter-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/abstractpropertygetter-property.html new file mode 100644 index 000000000000..78a68165c32c --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/abstractpropertygetter-property.html @@ -0,0 +1,21 @@ + + + + + + +
+

abstractPropertyGetter

+
+

Packages > test-suite-a > TestAbstractClass > abstractPropertyGetter

+
+
+

A test abstract getter property.

+
+
+

Signature

abstract get abstractPropertyGetter(): TestMappedType; +

Type: TestMappedType

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/index.html new file mode 100644 index 000000000000..2d2fba82118e --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/index.html @@ -0,0 +1,97 @@ + + + + + + +
+

TestAbstractClass

+
+

Packages > test-suite-a > TestAbstractClass

+
+
+

A test abstract class.

+
+
+

Signature

export declare abstract class TestAbstractClass +
+
+

Constructors

+ + + + + + + + + + + + + +
ConstructorDescription
(constructor)(privateProperty, protectedProperty)This is a {@customTag constructor}.
+
+
+

Properties

+ + + + + + + + + + + + + + + + + + + + + + + +
PropertyModifiersTypeDescription
abstractPropertyGetterreadonlyTestMappedTypeA test abstract getter property.
protectedPropertyreadonlyTestEnumA test protected property.
+
+
+

Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodModifiersReturn TypeDescription
publicAbstractMethod()voidA test public abstract method.
sealedMethod()sealedstringA test @sealed method.
virtualMethod()virtualnumberA test @virtual method.
+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/protectedproperty-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/protectedproperty-property.html new file mode 100644 index 000000000000..8d4557344f00 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/protectedproperty-property.html @@ -0,0 +1,21 @@ + + + + + + +
+

protectedProperty

+
+

Packages > test-suite-a > TestAbstractClass > protectedProperty

+
+
+

A test protected property.

+
+
+

Signature

protected readonly protectedProperty: TestEnum; +

Type: TestEnum

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/publicabstractmethod-method.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/publicabstractmethod-method.html new file mode 100644 index 000000000000..a592fd8afe94 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/publicabstractmethod-method.html @@ -0,0 +1,20 @@ + + + + + + +
+

publicAbstractMethod

+
+

Packages > test-suite-a > TestAbstractClass > publicAbstractMethod()

+
+
+

A test public abstract method.

+
+
+

Signature

abstract publicAbstractMethod(): void; +
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/sealedmethod-method.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/sealedmethod-method.html new file mode 100644 index 000000000000..3e07abc323ba --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/sealedmethod-method.html @@ -0,0 +1,25 @@ + + + + + + +
+

sealedMethod

+
+

Packages > test-suite-a > TestAbstractClass > sealedMethod()

+
+
+

A test @sealed method.

+
+
+

Signature

/** @sealed */
protected sealedMethod(): string; +
+
+

Returns

+

A string!

+

Return type: string

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/virtualmethod-method.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/virtualmethod-method.html new file mode 100644 index 000000000000..0a0ad7de3210 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/virtualmethod-method.html @@ -0,0 +1,25 @@ + + + + + + +
+

virtualMethod

+
+

Packages > test-suite-a > TestAbstractClass > virtualMethod()

+
+
+

A test @virtual method.

+
+
+

Signature

/** @virtual */
protected virtualMethod(): number; +
+
+

Returns

+

A number!

+

Return type: number

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/_constructor_-constructor.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/_constructor_-constructor.html new file mode 100644 index 000000000000..c1f361e3cbc9 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/_constructor_-constructor.html @@ -0,0 +1,61 @@ + + + + + + +
+

(constructor)

+
+

Packages > test-suite-a > TestClass > (constructor)(privateProperty, protectedProperty, testClassProperty, testClassEventProperty)

+
+
+

Test class constructor

+
+
+

Signature

constructor(privateProperty: number, protectedProperty: TestEnum, testClassProperty: TTypeParameterB, testClassEventProperty: () => void); +
+
+

Remarks

+

Here are some remarks about the constructor

+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
privatePropertynumberSee TestAbstractClass's constructor.
protectedPropertyTestEnum +

Some notes about the parameter.

+

See protectedProperty.

+
testClassPropertyTTypeParameterBSee testClassProperty.
testClassEventProperty() => voidSee testClassEventProperty.
+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/abstractpropertygetter-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/abstractpropertygetter-property.html new file mode 100644 index 000000000000..bb178bcc3ba0 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/abstractpropertygetter-property.html @@ -0,0 +1,21 @@ + + + + + + +
+

abstractPropertyGetter

+
+

Packages > test-suite-a > TestClass > abstractPropertyGetter

+
+
+

A test abstract getter property.

+
+
+

Signature

get abstractPropertyGetter(): TestMappedType; +

Type: TestMappedType

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/index.html new file mode 100644 index 000000000000..917df3feb68c --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/index.html @@ -0,0 +1,196 @@ + + + + + + +
+

TestClass

+
+

Packages > test-suite-a > TestClass

+
+
+

Test class

+
+
+

Signature

export declare class TestClass<TTypeParameterA, TTypeParameterB> extends TestAbstractClass +

+

Extends: TestAbstractClass

+

+

+

Type Parameters

+ + + + + + + + + + + + + + + + + +
ParameterDescription
TTypeParameterAA type parameter
TTypeParameterBAnother type parameter
+
+

+

+
+
+

Remarks

+

Here are some remarks about the class

+
+
+

Constructors

+ + + + + + + + + + + + + +
ConstructorDescription
(constructor)(privateProperty, protectedProperty, testClassProperty, testClassEventProperty)Test class constructor
+
+
+

Static Properties

+ + + + + + + + + + + + + + + +
PropertyTypeDescription
testClassStaticProperty(foo: number) => stringTest static class property
+
+
+

Static Methods

+ + + + + + + + + + + + + + + +
MethodReturn TypeDescription
testClassStaticMethod(foo)stringTest class static method
+
+
+

Events

+ + + + + + + + + + + + + + + + + +
PropertyModifiersTypeDescription
testClassEventPropertyreadonly() => voidTest class event property
+
+
+

Properties

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyModifiersTypeDescription
abstractPropertyGetterreadonlyTestMappedTypeA test abstract getter property.
testClassGetterPropertyvirtualnumberTest class property with both a getter and a setter.
testClassPropertyreadonlyTTypeParameterBTest class property
+
+
+

Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodModifiersReturn TypeDescription
publicAbstractMethod()voidA test public abstract method.
testClassMethod(input)sealedTTypeParameterATest class method
virtualMethod()numberOverrides virtualMethod().
+
+
+

See Also

+

TestAbstractClass

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/publicabstractmethod-method.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/publicabstractmethod-method.html new file mode 100644 index 000000000000..f6b972c7f55e --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/publicabstractmethod-method.html @@ -0,0 +1,20 @@ + + + + + + +
+

publicAbstractMethod

+
+

Packages > test-suite-a > TestClass > publicAbstractMethod()

+
+
+

A test public abstract method.

+
+
+

Signature

publicAbstractMethod(): void; +
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclasseventproperty-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclasseventproperty-property.html new file mode 100644 index 000000000000..c9481deb7915 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclasseventproperty-property.html @@ -0,0 +1,25 @@ + + + + + + +
+

testClassEventProperty

+
+

Packages > test-suite-a > TestClass > testClassEventProperty

+
+
+

Test class event property

+
+
+

Signature

readonly testClassEventProperty: () => void; +

Type: () => void

+
+
+

Remarks

+

Here are some remarks about the property

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassgetterproperty-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassgetterproperty-property.html new file mode 100644 index 000000000000..931105145467 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassgetterproperty-property.html @@ -0,0 +1,25 @@ + + + + + + +
+

testClassGetterProperty

+
+

Packages > test-suite-a > TestClass > testClassGetterProperty

+
+
+

Test class property with both a getter and a setter.

+
+
+

Signature

/** @virtual */
get testClassGetterProperty(): number;


set testClassGetterProperty(newValue: number); +

Type: number

+
+
+

Remarks

+

Here are some remarks about the getter-only property

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassmethod-method.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassmethod-method.html new file mode 100644 index 000000000000..061dfeb57cfd --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassmethod-method.html @@ -0,0 +1,52 @@ + + + + + + +
+

testClassMethod

+
+

Packages > test-suite-a > TestClass > testClassMethod(input)

+
+
+

Test class method

+
+
+

Signature

/** @sealed */
testClassMethod(input: TTypeParameterA): TTypeParameterA; +
+
+

Remarks

+

Here are some remarks about the method

+
+
+

Parameters

+ + + + + + + + + + + + + + + +
ParameterTypeDescription
inputTTypeParameterA
+
+
+

Returns

+

Return type: TTypeParameterA

+
+
+

Throws

+

Some sort of error in 1 case.

+

Some other sort of error in another case. For example, a case where some thing happens.

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassproperty-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassproperty-property.html new file mode 100644 index 000000000000..dc1eeaf89412 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassproperty-property.html @@ -0,0 +1,25 @@ + + + + + + +
+

testClassProperty

+
+

Packages > test-suite-a > TestClass > testClassProperty

+
+
+

Test class property

+
+
+

Signature

readonly testClassProperty: TTypeParameterB; +

Type: TTypeParameterB

+
+
+

Remarks

+

Here are some remarks about the property

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticmethod-method.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticmethod-method.html new file mode 100644 index 000000000000..be05c50d4e8e --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticmethod-method.html @@ -0,0 +1,44 @@ + + + + + + +
+

testClassStaticMethod

+
+

Packages > test-suite-a > TestClass > testClassStaticMethod(foo)

+
+
+

Test class static method

+
+
+

Signature

static testClassStaticMethod(foo: number): string; +
+
+

Parameters

+ + + + + + + + + + + + + + + +
ParameterTypeDescription
foonumberSome number
+
+
+

Returns

+

- Some string

+

Return type: string

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticproperty-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticproperty-property.html new file mode 100644 index 000000000000..460d23903051 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticproperty-property.html @@ -0,0 +1,21 @@ + + + + + + +
+

testClassStaticProperty

+
+

Packages > test-suite-a > TestClass > testClassStaticProperty

+
+
+

Test static class property

+
+
+

Signature

static testClassStaticProperty: (foo: number) => string; +

Type: (foo: number) => string

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/virtualmethod-method.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/virtualmethod-method.html new file mode 100644 index 000000000000..cd2dc520c6b9 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/virtualmethod-method.html @@ -0,0 +1,24 @@ + + + + + + +
+

virtualMethod

+
+

Packages > test-suite-a > TestClass > virtualMethod()

+
+
+

Overrides virtualMethod().

+
+
+

Signature

/** @override */
protected virtualMethod(): number; +
+
+

Returns

+

Return type: number

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testconst-variable.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testconst-variable.html new file mode 100644 index 000000000000..0ce147bd98c7 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testconst-variable.html @@ -0,0 +1,25 @@ + + + + + + +
+

testConst

+
+

Packages > test-suite-a > testConst

+
+
+

Test Constant

+
+
WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.
+
+

Signature

testConst = 42 +
+
+

Remarks

+

Here are some remarks about the variable

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testconstwithemptydeprecatedblock-variable.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testconstwithemptydeprecatedblock-variable.html new file mode 100644 index 000000000000..abfdf1c3ba7e --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testconstwithemptydeprecatedblock-variable.html @@ -0,0 +1,24 @@ + + + + + + +
+

testConstWithEmptyDeprecatedBlock

+
+

Packages > test-suite-a > testConstWithEmptyDeprecatedBlock

+
+
+

I have a @deprecated tag with an empty comment block.

+
+
+

WARNING: This API is deprecated and will be removed in a future release.

+
+
+

Signature

testConstWithEmptyDeprecatedBlock: string +

Type: string

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testemptyinterface-interface/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testemptyinterface-interface/index.html new file mode 100644 index 000000000000..f5552788ae85 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testemptyinterface-interface/index.html @@ -0,0 +1,20 @@ + + + + + + +
+

TestEmptyInterface

+
+

Packages > test-suite-a > TestEmptyInterface

+
+
+

An empty interface

+
+
+

Signature

export interface TestEmptyInterface +
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/index.html new file mode 100644 index 000000000000..c5f9b097620b --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/index.html @@ -0,0 +1,96 @@ + + + + + + +
+

TestEnum

+
+

Packages > test-suite-a > TestEnum

+
+
+

Test Enum

+
+
+

Signature

export declare enum TestEnum +
+
+

Remarks

+

Here are some remarks about the enum

+
+
+

Examples

+
+

Example 1

+

+

Some example

const foo = TestEnum.TestEnumValue1 +

+
+
+

Example 2

+

+

Another example

const bar = TestEnum.TestEnumValue2 +

+
+
+
+

Flags

+ + + + + + + + + + + + + + + + + + + + + +
FlagDescription
TestEnumValue1Test enum value 1 (string)
TestEnumValue2Test enum value 2 (number)
TestEnumValue3Test enum value 3 (default)
+
+
+
+

Test enum value 1 (string)

+
+
+

Signature

TestEnumValue1 = "test-enum-value-1" +
+
+

Remarks

+

Here are some remarks about the enum value

+
+
+

Test enum value 2 (number)

+
+
+

Signature

TestEnumValue2 = 3 +
+
+

Remarks

+

Here are some remarks about the enum value

+
+
+

Test enum value 3 (default)

+
+
+

Signature

TestEnumValue3 = 4 +
+
+

Remarks

+

Here are some remarks about the enum value

+
+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue1-enummember.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue1-enummember.html new file mode 100644 index 000000000000..57399fb71808 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue1-enummember.html @@ -0,0 +1,24 @@ + + + + + + +
+

TestEnumValue1

+
+

Packages > test-suite-a > TestEnum > TestEnumValue1

+
+
+

Test enum value 1 (string)

+
+
+

Signature

TestEnumValue1 = "test-enum-value-1" +
+
+

Remarks

+

Here are some remarks about the enum value

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue2-enummember.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue2-enummember.html new file mode 100644 index 000000000000..ab1e131365cc --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue2-enummember.html @@ -0,0 +1,24 @@ + + + + + + +
+

TestEnumValue2

+
+

Packages > test-suite-a > TestEnum > TestEnumValue2

+
+
+

Test enum value 2 (number)

+
+
+

Signature

TestEnumValue2 = 3 +
+
+

Remarks

+

Here are some remarks about the enum value

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue3-enummember.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue3-enummember.html new file mode 100644 index 000000000000..2fc410d631bd --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue3-enummember.html @@ -0,0 +1,24 @@ + + + + + + +
+

TestEnumValue3

+
+

Packages > test-suite-a > TestEnum > TestEnumValue3

+
+
+

Test enum value 3 (default)

+
+
+

Signature

TestEnumValue3 = 4 +
+
+

Remarks

+

Here are some remarks about the enum value

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunction-function.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunction-function.html new file mode 100644 index 000000000000..34889dcf7286 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunction-function.html @@ -0,0 +1,84 @@ + + + + + + +
+

testFunction

+
+

Packages > test-suite-a > testFunction(testParameter, testOptionalParameter)

+
+
+

Test function

+
+
WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.
+
+

Signature

export declare function testFunction<TTypeParameter extends TestInterface = TestInterface>(testParameter: TTypeParameter, testOptionalParameter?: TTypeParameter): TTypeParameter; +

+

+

Type Parameters

+ + + + + + + + + + + + + + + + + +
ParameterConstraintDefaultDescription
TTypeParameterTestInterfaceTestInterfaceA test type parameter
+
+

+
+
+

Remarks

+

This is a test link to another API member

+
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
ParameterModifiersTypeDescription
testParameterTTypeParameterA test parameter
testOptionalParameteroptionalTTypeParameter
+
+
+

Returns

+

The provided parameter

+

Return type: TTypeParameter

+
+
+

Throws

+

An Error when something bad happens.

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturninginlinetype-function.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturninginlinetype-function.html new file mode 100644 index 000000000000..7e7062b3ec7a --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturninginlinetype-function.html @@ -0,0 +1,25 @@ + + + + + + +
+

testFunctionReturningInlineType

+
+

Packages > test-suite-a > testFunctionReturningInlineType()

+
+
+

Test function that returns an inline type

+
+
+

Signature

export declare function testFunctionReturningInlineType(): {
foo: number;
bar: TestEnum;
}; +
+
+

Returns

+

An inline type

+

Return type: { foo: number; bar: TestEnum; }

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturningintersectiontype-function.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturningintersectiontype-function.html new file mode 100644 index 000000000000..25f716239136 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturningintersectiontype-function.html @@ -0,0 +1,28 @@ + + + + + + +
+

testFunctionReturningIntersectionType

+
+

Packages > test-suite-a > testFunctionReturningIntersectionType()

+
+
+

Test function that returns an inline type

+
+
+

WARNING: This API is deprecated and will be removed in a future release.

This is a test deprecation notice. Here is a link to something else!

+
+
+

Signature

export declare function testFunctionReturningIntersectionType(): TestEmptyInterface & TestInterfaceWithTypeParameter<number>; +
+
+

Returns

+

an intersection type

+

Return type: TestEmptyInterface & TestInterfaceWithTypeParameter<number>

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturninguniontype-function.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturninguniontype-function.html new file mode 100644 index 000000000000..5a5999633ab7 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturninguniontype-function.html @@ -0,0 +1,25 @@ + + + + + + +
+

testFunctionReturningUnionType

+
+

Packages > test-suite-a > testFunctionReturningUnionType()

+
+
+

Test function that returns an inline type

+
+
+

Signature

export declare function testFunctionReturningUnionType(): string | TestInterface; +
+
+

Returns

+

A union type

+

Return type: string | TestInterface

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call_-callsignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call_-callsignature.html new file mode 100644 index 000000000000..1bb3cec8d9c6 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call_-callsignature.html @@ -0,0 +1,24 @@ + + + + + + +
+

(event: 'testCallSignature', listener: (input: unknown) => void): any

+
+

Packages > test-suite-a > TestInterface > (event: 'testCallSignature', listener: (input: unknown) => void): any

+
+
+

Test interface event call signature

+
+
+

Signature

(event: 'testCallSignature', listener: (input: unknown) => void): any; +
+
+

Remarks

+

Here are some remarks about the event call signature

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call__1-callsignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call__1-callsignature.html new file mode 100644 index 000000000000..1ebbf183381e --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call__1-callsignature.html @@ -0,0 +1,24 @@ + + + + + + +
+

(event: 'anotherTestCallSignature', listener: (input: number) => string): number

+
+

Packages > test-suite-a > TestInterface > (event: 'anotherTestCallSignature', listener: (input: number) => string): number

+
+
+

Another example call signature

+
+
+

Signature

(event: 'anotherTestCallSignature', listener: (input: number) => string): number; +
+
+

Remarks

+

Here are some remarks about the event call signature

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_new_-constructsignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_new_-constructsignature.html new file mode 100644 index 000000000000..cacb80c9c0d1 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_new_-constructsignature.html @@ -0,0 +1,24 @@ + + + + + + +
+

new (): TestInterface

+
+

Packages > test-suite-a > TestInterface > new (): TestInterface

+
+
+

Test construct signature.

+
+
+

Signature

new (): TestInterface; +
+
+

Returns

+

Return type: TestInterface

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/getterproperty-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/getterproperty-property.html new file mode 100644 index 000000000000..c24cbf5dc74e --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/getterproperty-property.html @@ -0,0 +1,21 @@ + + + + + + +
+

getterProperty

+
+

Packages > test-suite-a > TestInterface > getterProperty

+
+
+

A test getter-only interface property.

+
+
+

Signature

get getterProperty(): boolean; +

Type: boolean

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/index.html new file mode 100644 index 000000000000..cffec89b7906 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/index.html @@ -0,0 +1,162 @@ + + + + + + +
+

TestInterface

+
+

Packages > test-suite-a > TestInterface

+
+
+

Test interface

+
+
+

Signature

export interface TestInterface +
+
+

Remarks

+

Here are some remarks about the interface

+
+
+

Construct Signatures

+ + + + + + + + + + + + + + + +
ConstructSignatureReturn TypeDescription
new (): TestInterfaceTestInterfaceTest construct signature.
+
+
+

Events

+ + + + + + + + + + + + + + + + + +
PropertyModifiersTypeDescription
testClassEventPropertyreadonly() => voidTest interface event property
+
+
+

Properties

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyModifiersDefault ValueTypeDescription
getterPropertyreadonlybooleanA test getter-only interface property.
propertyWithBadInheritDocTargetboolean
setterPropertybooleanA test property with a getter and a setter.
testInterfacePropertynumberTest interface property
testOptionalInterfacePropertyoptional0numberTest optional property
+
+
+

Methods

+ + + + + + + + + + + + + + + +
MethodReturn TypeDescription
testInterfaceMethod()voidTest interface method
+
+
+

Call Signatures

+ + + + + + + + + + + + + + + + + +
CallSignatureDescription
(event: 'testCallSignature', listener: (input: unknown) => void): anyTest interface event call signature
(event: 'anotherTestCallSignature', listener: (input: number) => string): numberAnother example call signature
+
+
+

See Also

+

testInterfaceMethod()

+

testInterfaceProperty

+

testOptionalInterfaceProperty

+

testClassEventProperty

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature.html new file mode 100644 index 000000000000..4bacb75a530a --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature.html @@ -0,0 +1,21 @@ + + + + + + +
+

propertyWithBadInheritDocTarget

+
+

Packages > test-suite-a > TestInterface > propertyWithBadInheritDocTarget

+
+
+

+
+
+

Signature

propertyWithBadInheritDocTarget: boolean; +

Type: boolean

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/setterproperty-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/setterproperty-property.html new file mode 100644 index 000000000000..8a170ed0040e --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/setterproperty-property.html @@ -0,0 +1,21 @@ + + + + + + +
+

setterProperty

+
+

Packages > test-suite-a > TestInterface > setterProperty

+
+
+

A test property with a getter and a setter.

+
+
+

Signature

get setterProperty(): boolean;


set setterProperty(newValue: boolean); +

Type: boolean

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testclasseventproperty-propertysignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testclasseventproperty-propertysignature.html new file mode 100644 index 000000000000..cc3e3982f7a2 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testclasseventproperty-propertysignature.html @@ -0,0 +1,25 @@ + + + + + + +
+

testClassEventProperty

+
+

Packages > test-suite-a > TestInterface > testClassEventProperty

+
+
+

Test interface event property

+
+
+

Signature

readonly testClassEventProperty: () => void; +

Type: () => void

+
+
+

Remarks

+

Here are some remarks about the event property

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfacemethod-methodsignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfacemethod-methodsignature.html new file mode 100644 index 000000000000..488753fe08a4 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfacemethod-methodsignature.html @@ -0,0 +1,24 @@ + + + + + + +
+

testInterfaceMethod

+
+

Packages > test-suite-a > TestInterface > testInterfaceMethod()

+
+
+

Test interface method

+
+
+

Signature

testInterfaceMethod(): void; +
+
+

Remarks

+

Here are some remarks about the method

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature.html new file mode 100644 index 000000000000..78743f3ec621 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature.html @@ -0,0 +1,25 @@ + + + + + + +
+

testInterfaceProperty

+
+

Packages > test-suite-a > TestInterface > testInterfaceProperty

+
+
+

Test interface property

+
+
+

Signature

testInterfaceProperty: number; +

Type: number

+
+
+

Remarks

+

Here are some remarks about the property

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature.html new file mode 100644 index 000000000000..38d4d1e34c97 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature.html @@ -0,0 +1,21 @@ + + + + + + +
+

testOptionalInterfaceProperty

+
+

Packages > test-suite-a > TestInterface > testOptionalInterfaceProperty

+
+
+

Test optional property

+
+
+

Signature

testOptionalInterfaceProperty?: number; +

Type: number

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/index.html new file mode 100644 index 000000000000..6d103c866d97 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/index.html @@ -0,0 +1,52 @@ + + + + + + +
+

TestInterfaceExtendingOtherInterfaces

+
+

Packages > test-suite-a > TestInterfaceExtendingOtherInterfaces

+
+
+

Test interface that extends other interfaces

+
+
+

Signature

export interface TestInterfaceExtendingOtherInterfaces extends TestInterface, TestMappedType, TestInterfaceWithTypeParameter<number> +

Extends: TestInterface, TestMappedType, TestInterfaceWithTypeParameter<number>

+
+
+

Remarks

+

Here are some remarks about the interface

+
+
+

Methods

+ + + + + + + + + + + + + + + +
MethodReturn TypeDescription
testMethod(input)numberTest interface method accepting a string and returning a number.
+
+
+

See Also

+

+

- TestInterface

+

- TestInterfaceWithTypeParameter

+

- TestMappedType

+

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature.html new file mode 100644 index 000000000000..255cc2a629fd --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature.html @@ -0,0 +1,48 @@ + + + + + + +
+

testMethod

+
+

Packages > test-suite-a > TestInterfaceExtendingOtherInterfaces > testMethod(input)

+
+
+

Test interface method accepting a string and returning a number.

+
+
+

Signature

testMethod(input: string): number; +
+
+

Remarks

+

Here are some remarks about the method

+
+
+

Parameters

+ + + + + + + + + + + + + + + +
ParameterTypeDescription
inputstringA string
+
+
+

Returns

+

A number

+

Return type: number

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature.html new file mode 100644 index 000000000000..fdd8de4c6fe4 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature.html @@ -0,0 +1,20 @@ + + + + + + +
+

[foo: number]: { bar: string; }

+
+

Packages > test-suite-a > TestInterfaceWithIndexSignature > [foo: number]: { bar: string; }

+
+
+

Test index signature.

+
+
+

Signature

[foo: number]: {
bar: string;
}; +
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/index.html new file mode 100644 index 000000000000..f4a88fee87e9 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/index.html @@ -0,0 +1,37 @@ + + + + + + +
+

TestInterfaceWithIndexSignature

+
+

Packages > test-suite-a > TestInterfaceWithIndexSignature

+
+
+

An interface with an index signature.

+
+
+

Signature

export interface TestInterfaceWithIndexSignature +
+
+

Index Signatures

+ + + + + + + + + + + + + +
IndexSignatureDescription
[foo: number]: { bar: string; }Test index signature.
+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/index.html new file mode 100644 index 000000000000..113f38820f3a --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/index.html @@ -0,0 +1,62 @@ + + + + + + +
+

TestInterfaceWithTypeParameter

+
+

Packages > test-suite-a > TestInterfaceWithTypeParameter

+
+
+

Test interface with generic type parameter

+
+
+

Signature

export interface TestInterfaceWithTypeParameter<T> +

+

+

Type Parameters

+ + + + + + + + + + + + + +
ParameterDescription
TA type parameter
+
+

+
+
+

Remarks

+

Here are some remarks about the interface

+
+
+

Properties

+ + + + + + + + + + + + + + + +
PropertyTypeDescription
testPropertyTA test interface property using generic type parameter
+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature.html new file mode 100644 index 000000000000..639a4ff429b0 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature.html @@ -0,0 +1,25 @@ + + + + + + +
+

testProperty

+
+

Packages > test-suite-a > TestInterfaceWithTypeParameter > testProperty

+
+
+

A test interface property using generic type parameter

+
+
+

Signature

testProperty: T; +

Type: T

+
+
+

Remarks

+

Here are some remarks about the property

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmappedtype-typealias/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmappedtype-typealias/index.html new file mode 100644 index 000000000000..864c6083ff7b --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmappedtype-typealias/index.html @@ -0,0 +1,24 @@ + + + + + + +
+

TestMappedType

+
+

Packages > test-suite-a > TestMappedType

+
+
+

Test Mapped Type, using TestEnum

+
+
+

Signature

export type TestMappedType = {
[K in TestEnum]: boolean;
}; +
+
+

Remarks

+

Here are some remarks about the mapped type

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/foo-variable.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/foo-variable.html new file mode 100644 index 000000000000..ca8b80f47e50 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/foo-variable.html @@ -0,0 +1,20 @@ + + + + + + +
+

foo

+
+

Packages > test-suite-a > TestModule > foo

+
+
+

Test constant in module.

+
+
+

Signature

foo = 2 +
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/index.html new file mode 100644 index 000000000000..96667a9e9517 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/index.html @@ -0,0 +1,35 @@ + + + + + + +
+

TestModule

+
+

Packages > test-suite-a > TestModule

+
+
+

Variables

+ + + + + + + + + + + + + + + + + +
VariableModifiersTypeDescription
fooreadonlyTest constant in module.
+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/index.html new file mode 100644 index 000000000000..b58d65593523 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/index.html @@ -0,0 +1,168 @@ + + + + + + +
+

TestNamespace

+
+

Packages > test-suite-a > TestNamespace

+
+
+

Test Namespace

+
+
+

Signature

export declare namespace TestNamespace +
+
+

Remarks

+

Here are some remarks about the namespace

+
+
+

Examples

+
+

Example: TypeScript Example

+

+

const foo: Foo = {
bar: "Hello world!";
baz = 42;
}; +

+
+
+

Example: JavaScript Example

+

+

const foo = {
bar: "Hello world!";
baz = 42;
}; +

+
+
+
+

Interfaces

+ + + + + + + + + + + + + + + +
InterfaceAlertsDescription
TestInterfaceAlphaTest interface
+
+
+

Classes

+ + + + + + + + + + + + + +
ClassDescription
TestClassTest class
+
+
+

Enumerations

+ + + + + + + + + + + + + +
EnumDescription
TestEnumTest Enum
+
+
+

Types

+ + + + + + + + + + + + + +
TypeAliasDescription
TestTypeAliasTest Type-Alias
+
+
+

Functions

+ + + + + + + + + + + + + + + +
FunctionReturn TypeDescription
testFunction(testParameter)numberTest function
+
+
+

Variables

+ + + + + + + + + + + + + + + + + + + +
VariableAlertsModifiersTypeDescription
TestConstBetareadonlyTest Constant
+
+
+

Namespaces

+ + + + + + + + + + + + + +
NamespaceDescription
TestSubNamespaceTest sub-namespace
+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor.html new file mode 100644 index 000000000000..58e53c22695c --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor.html @@ -0,0 +1,39 @@ + + + + + + +
+

(constructor)

+
+

Packages > test-suite-a > TestNamespace > TestClass > (constructor)(testClassProperty)

+
+
+

Test class constructor

+
+
+

Signature

constructor(testClassProperty: string); +
+
+

Parameters

+ + + + + + + + + + + + + + + +
ParameterTypeDescription
testClassPropertystringSee testClassProperty
+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/index.html new file mode 100644 index 000000000000..b488f1d60c02 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/index.html @@ -0,0 +1,77 @@ + + + + + + +
+

TestClass

+
+

Packages > test-suite-a > TestNamespace > TestClass

+
+
+

Test class

+
+
+

Signature

class TestClass +
+
+

Constructors

+ + + + + + + + + + + + + +
ConstructorDescription
(constructor)(testClassProperty)Test class constructor
+
+
+

Properties

+ + + + + + + + + + + + + + + + + +
PropertyModifiersTypeDescription
testClassPropertyreadonlystringTest interface property
+
+
+

Methods

+ + + + + + + + + + + + + + + +
MethodReturn TypeDescription
testClassMethod(testParameter)Promise<string>Test class method
+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method.html new file mode 100644 index 000000000000..4182400579e8 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method.html @@ -0,0 +1,52 @@ + + + + + + +
+

testClassMethod

+
+

Packages > test-suite-a > TestNamespace > TestClass > testClassMethod(testParameter)

+
+
+

Test class method

+
+
+

Signature

testClassMethod(testParameter: string): Promise<string>; +
+
+

Parameters

+ + + + + + + + + + + + + + + +
ParameterTypeDescription
testParameterstringA string
+
+
+

Returns

+

A Promise

+

Return type: Promise<string>

+
+
+

Throws

+

An Error when something happens for which an error should be thrown. Except in the cases where another kind of error is thrown. We don't throw this error in those cases.

+

+

A different kind of error when a thing happens, but not when the first kind of error is thrown instead.

+

😁

+

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property.html new file mode 100644 index 000000000000..601113c407fd --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property.html @@ -0,0 +1,21 @@ + + + + + + +
+

testClassProperty

+
+

Packages > test-suite-a > TestNamespace > TestClass > testClassProperty

+
+
+

Test interface property

+
+
+

Signature

readonly testClassProperty: string; +

Type: string

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testconst-variable.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testconst-variable.html new file mode 100644 index 000000000000..881248685062 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testconst-variable.html @@ -0,0 +1,21 @@ + + + + + + +
+

TestConst

+
+

Packages > test-suite-a > TestNamespace > TestConst

+
+
+

Test Constant

+
+
WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.
+
+

Signature

TestConst = "Hello world!" +
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/index.html new file mode 100644 index 000000000000..aadd401dd9e2 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/index.html @@ -0,0 +1,55 @@ + + + + + + +
+

TestEnum

+
+

Packages > test-suite-a > TestNamespace > TestEnum

+
+
+

Test Enum

+
+
+

Signature

enum TestEnum +
+
+

Flags

+ + + + + + + + + + + + + + + + + +
FlagDescription
TestEnumValue1Test enum value 1
TestEnumValue2Test enum value 2
+
+
+
+

Test enum value 1

+
+
+

Signature

TestEnumValue1 = 0 +
+
+

Test enum value 2

+
+
+

Signature

TestEnumValue2 = 1 +
+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember.html new file mode 100644 index 000000000000..fcda24ca526d --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember.html @@ -0,0 +1,20 @@ + + + + + + +
+

TestEnumValue1

+
+

Packages > test-suite-a > TestNamespace > TestEnum > TestEnumValue1

+
+
+

Test enum value 1

+
+
+

Signature

TestEnumValue1 = 0 +
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember.html new file mode 100644 index 000000000000..f5a95a5acb7c --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember.html @@ -0,0 +1,20 @@ + + + + + + +
+

TestEnumValue2

+
+

Packages > test-suite-a > TestNamespace > TestEnum > TestEnumValue2

+
+
+

Test enum value 2

+
+
+

Signature

TestEnumValue2 = 1 +
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testfunction-function.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testfunction-function.html new file mode 100644 index 000000000000..deb8e56b5aec --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testfunction-function.html @@ -0,0 +1,48 @@ + + + + + + +
+

testFunction

+
+

Packages > test-suite-a > TestNamespace > testFunction(testParameter)

+
+
+

Test function

+
+
+

Signature

function testFunction(testParameter: number): number; +
+
+

Parameters

+ + + + + + + + + + + + + + + +
ParameterTypeDescription
testParameternumber
+
+
+

Returns

+

A number

+

Return type: number

+
+
+

Throws

+

An Error

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/index.html new file mode 100644 index 000000000000..c5d44d04aded --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/index.html @@ -0,0 +1,64 @@ + + + + + + +
+

TestInterface

+
+

Packages > test-suite-a > TestNamespace > TestInterface

+
+
+

Test interface

+
+
WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.
+
+

Signature

interface TestInterface extends TestInterfaceWithTypeParameter<TestEnum> +

Extends: TestInterfaceWithTypeParameter<TestEnum>

+
+
+

Properties

+ + + + + + + + + + + + + + + + + +
PropertyAlertsTypeDescription
testInterfacePropertyAlphabooleanTest interface property
+
+
+

Methods

+ + + + + + + + + + + + + + + + + +
MethodAlertsReturn TypeDescription
testInterfaceMethod()AlphavoidTest interface method
+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature.html new file mode 100644 index 000000000000..3b489d5671ab --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature.html @@ -0,0 +1,21 @@ + + + + + + +
+

testInterfaceMethod

+
+

Packages > test-suite-a > TestNamespace > TestInterface > testInterfaceMethod()

+
+
+

Test interface method

+
+
WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.
+
+

Signature

testInterfaceMethod(): void; +
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature.html new file mode 100644 index 000000000000..86286ff0e9c3 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature.html @@ -0,0 +1,22 @@ + + + + + + +
+

testInterfaceProperty

+
+

Packages > test-suite-a > TestNamespace > TestInterface > testInterfaceProperty

+
+
+

Test interface property

+
+
WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.
+
+

Signature

testInterfaceProperty: boolean; +

Type: boolean

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testsubnamespace-namespace/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testsubnamespace-namespace/index.html new file mode 100644 index 000000000000..48fc6ff9b0d4 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testsubnamespace-namespace/index.html @@ -0,0 +1,20 @@ + + + + + + +
+

TestSubNamespace

+
+

Packages > test-suite-a > TestNamespace > TestSubNamespace

+
+
+

Test sub-namespace

+
+
+

Signature

namespace TestSubNamespace +
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testtypealias-typealias/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testtypealias-typealias/index.html new file mode 100644 index 000000000000..89c03a3b2c02 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testtypealias-typealias/index.html @@ -0,0 +1,20 @@ + + + + + + +
+

TestTypeAlias

+
+

Packages > test-suite-a > TestNamespace > TestTypeAlias

+
+
+

Test Type-Alias

+
+
+

Signature

type TestTypeAlias = boolean; +
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/typealias-typealias/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/typealias-typealias/index.html new file mode 100644 index 000000000000..6b10e181bd48 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/typealias-typealias/index.html @@ -0,0 +1,24 @@ + + + + + + +
+

TypeAlias

+
+

Packages > test-suite-a > TypeAlias

+
+
+

Test Type-Alias

+
+
+

Signature

export type TypeAlias = string; +
+
+

Remarks

+

Here are some remarks about the type alias

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/foo-interface/bar-propertysignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/foo-interface/bar-propertysignature.html new file mode 100644 index 000000000000..ba0cf8d6a230 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/foo-interface/bar-propertysignature.html @@ -0,0 +1,25 @@ + + + + + + +
+

bar

+
+

Packages > test-suite-b > Foo > bar

+
+
+

Test Enum

+
+
+

Signature

bar: TestEnum; +

Type: TestEnum

+
+
+

Remarks

+

Here are some remarks about the enum

+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/foo-interface/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/foo-interface/index.html new file mode 100644 index 000000000000..02971c93289e --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/foo-interface/index.html @@ -0,0 +1,39 @@ + + + + + + +
+

Foo

+
+

Packages > test-suite-b > Foo

+
+
+

Bar

+
+
+

Signature

export interface Foo +
+
+

Properties

+ + + + + + + + + + + + + + + +
PropertyTypeDescription
barTestEnumTest Enum
+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/index.html new file mode 100644 index 000000000000..37ab3d58ea5b --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/index.html @@ -0,0 +1,31 @@ + + + + + + +
+

test-suite-b

+
+

Packages > test-suite-b

+
+
+

Interfaces

+ + + + + + + + + + + + + +
InterfaceDescription
FooBar
+
+
+ + diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/index.md new file mode 100644 index 000000000000..d8ae823a9570 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/index.md @@ -0,0 +1,8 @@ +# API Overview + +## Packages + +| Package | Description | +| --- | --- | +| [test-suite-a](./test-suite-a/) | Test package | +| [test-suite-b](./test-suite-b/) | | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/index.md new file mode 100644 index 000000000000..39d59df9e9ed --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/index.md @@ -0,0 +1,92 @@ +# test-suite-a + +[Packages](./) > [test-suite-a](./test-suite-a/) + +Test package + +## Remarks {#test-suite-a-remarks} + +This remarks block includes a bulleted list! + +- Bullet 1 + +- Bullet 2 + +And an ordered list for good measure! + +1. List item 1 + +2. List item 2 + +3. List item 3 + +Also, here is a link test, including a bad link, because we should have some reasonable support if this happens: + +- Good link (no alias): [TestClass](./test-suite-a/testclass-class/) + +- Good link (with alias): [function alias text](./test-suite-a/testfunction-function) + +- Bad link (no alias): _InvalidItem_ + +- Bad link (with alias): _even though I link to an invalid item, I would still like this text to be rendered_ + +## Example {#test-suite-a-example} + +A test example + +```typescript +const foo = bar; +``` + +## Interfaces + +| Interface | Description | +| --- | --- | +| [TestEmptyInterface](./test-suite-a/testemptyinterface-interface/) | An empty interface | +| [TestInterface](./test-suite-a/testinterface-interface/) | Test interface | +| [TestInterfaceExtendingOtherInterfaces](./test-suite-a/testinterfaceextendingotherinterfaces-interface/) | Test interface that extends other interfaces | +| [TestInterfaceWithIndexSignature](./test-suite-a/testinterfacewithindexsignature-interface/) | An interface with an index signature. | +| [TestInterfaceWithTypeParameter](./test-suite-a/testinterfacewithtypeparameter-interface/) | Test interface with generic type parameter | + +## Classes + +| Class | Description | +| --- | --- | +| [TestAbstractClass](./test-suite-a/testabstractclass-class/) | A test abstract class. | +| [TestClass](./test-suite-a/testclass-class/) | Test class | + +## Enumerations + +| Enum | Description | +| --- | --- | +| [TestEnum](./test-suite-a/testenum-enum/) | Test Enum | + +## Types + +| TypeAlias | Description | +| --- | --- | +| [TestMappedType](./test-suite-a/testmappedtype-typealias/) | Test Mapped Type, using [TestEnum](./test-suite-a/testenum-enum/) | +| [TypeAlias](./test-suite-a/typealias-typealias/) | Test Type-Alias | + +## Functions + +| Function | Alerts | Return Type | Description | +| --- | --- | --- | --- | +| [testFunction(testParameter, testOptionalParameter)](./test-suite-a/testfunction-function) | `Alpha` | TTypeParameter | Test function | +| [testFunctionReturningInlineType()](./test-suite-a/testfunctionreturninginlinetype-function) | | { foo: number; bar: [TestEnum](./test-suite-a/testenum-enum/); } | Test function that returns an inline type | +| [testFunctionReturningIntersectionType()](./test-suite-a/testfunctionreturningintersectiontype-function) | `Deprecated` | [TestEmptyInterface](./test-suite-a/testemptyinterface-interface/) & [TestInterfaceWithTypeParameter](./test-suite-a/testinterfacewithtypeparameter-interface/)<number> | Test function that returns an inline type | +| [testFunctionReturningUnionType()](./test-suite-a/testfunctionreturninguniontype-function) | | string \| [TestInterface](./test-suite-a/testinterface-interface/) | Test function that returns an inline type | + +## Variables + +| Variable | Alerts | Modifiers | Type | Description | +| --- | --- | --- | --- | --- | +| [testConst](./test-suite-a/testconst-variable) | `Beta` | `readonly` | | Test Constant | +| [testConstWithEmptyDeprecatedBlock](./test-suite-a/testconstwithemptydeprecatedblock-variable) | `Deprecated` | `readonly` | string | I have a `@deprecated` tag with an empty comment block. | + +## Namespaces + +| Namespace | Description | +| --- | --- | +| [TestModule](./test-suite-a/testmodule-namespace/) | | +| [TestNamespace](./test-suite-a/testnamespace-namespace/) | Test Namespace | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/_constructor_-constructor.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/_constructor_-constructor.md new file mode 100644 index 000000000000..e841a169957e --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/_constructor_-constructor.md @@ -0,0 +1,18 @@ +# (constructor) + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestAbstractClass](./test-suite-a/testabstractclass-class/) > [(constructor)(privateProperty, protectedProperty)](./test-suite-a/testabstractclass-class/_constructor_-constructor) + +This is a _{@customTag constructor}_. + +## Signature {#\_constructor\_-signature} + +```typescript +protected constructor(privateProperty: number, protectedProperty: TestEnum); +``` + +## Parameters {#\_constructor\_-parameters} + +| Parameter | Type | Description | +| --- | --- | --- | +| privateProperty | number | | +| protectedProperty | [TestEnum](./test-suite-a/testenum-enum/) | | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/abstractpropertygetter-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/abstractpropertygetter-property.md new file mode 100644 index 000000000000..b80f6ae7e538 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/abstractpropertygetter-property.md @@ -0,0 +1,13 @@ +# abstractPropertyGetter + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestAbstractClass](./test-suite-a/testabstractclass-class/) > [abstractPropertyGetter](./test-suite-a/testabstractclass-class/abstractpropertygetter-property) + +A test abstract getter property. + +## Signature {#abstractpropertygetter-signature} + +```typescript +abstract get abstractPropertyGetter(): TestMappedType; +``` + +**Type:** [TestMappedType](./test-suite-a/testmappedtype-typealias/) diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/index.md new file mode 100644 index 000000000000..355797f91c4e --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/index.md @@ -0,0 +1,32 @@ +# TestAbstractClass + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestAbstractClass](./test-suite-a/testabstractclass-class/) + +A test abstract class. + +## Signature {#testabstractclass-signature} + +```typescript +export declare abstract class TestAbstractClass +``` + +## Constructors + +| Constructor | Description | +| --- | --- | +| [(constructor)(privateProperty, protectedProperty)](./test-suite-a/testabstractclass-class/_constructor_-constructor) | This is a _{@customTag constructor}_. | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [abstractPropertyGetter](./test-suite-a/testabstractclass-class/abstractpropertygetter-property) | `readonly` | [TestMappedType](./test-suite-a/testmappedtype-typealias/) | A test abstract getter property. | +| [protectedProperty](./test-suite-a/testabstractclass-class/protectedproperty-property) | `readonly` | [TestEnum](./test-suite-a/testenum-enum/) | A test protected property. | + +## Methods + +| Method | Modifiers | Return Type | Description | +| --- | --- | --- | --- | +| [publicAbstractMethod()](./test-suite-a/testabstractclass-class/publicabstractmethod-method) | | void | A test public abstract method. | +| [sealedMethod()](./test-suite-a/testabstractclass-class/sealedmethod-method) | `sealed` | string | A test `@sealed` method. | +| [virtualMethod()](./test-suite-a/testabstractclass-class/virtualmethod-method) | `virtual` | number | A test `@virtual` method. | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/protectedproperty-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/protectedproperty-property.md new file mode 100644 index 000000000000..29ad04377551 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/protectedproperty-property.md @@ -0,0 +1,13 @@ +# protectedProperty + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestAbstractClass](./test-suite-a/testabstractclass-class/) > [protectedProperty](./test-suite-a/testabstractclass-class/protectedproperty-property) + +A test protected property. + +## Signature {#protectedproperty-signature} + +```typescript +protected readonly protectedProperty: TestEnum; +``` + +**Type:** [TestEnum](./test-suite-a/testenum-enum/) diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/publicabstractmethod-method.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/publicabstractmethod-method.md new file mode 100644 index 000000000000..a4fa120e1ab6 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/publicabstractmethod-method.md @@ -0,0 +1,11 @@ +# publicAbstractMethod + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestAbstractClass](./test-suite-a/testabstractclass-class/) > [publicAbstractMethod()](./test-suite-a/testabstractclass-class/publicabstractmethod-method) + +A test public abstract method. + +## Signature {#publicabstractmethod-signature} + +```typescript +abstract publicAbstractMethod(): void; +``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/sealedmethod-method.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/sealedmethod-method.md new file mode 100644 index 000000000000..12d56cb8db70 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/sealedmethod-method.md @@ -0,0 +1,18 @@ +# sealedMethod + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestAbstractClass](./test-suite-a/testabstractclass-class/) > [sealedMethod()](./test-suite-a/testabstractclass-class/sealedmethod-method) + +A test `@sealed` method. + +## Signature {#sealedmethod-signature} + +```typescript +/** @sealed */ +protected sealedMethod(): string; +``` + +## Returns {#sealedmethod-returns} + +A string! + +**Return type:** string diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/virtualmethod-method.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/virtualmethod-method.md new file mode 100644 index 000000000000..09e47b29d7c9 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/virtualmethod-method.md @@ -0,0 +1,18 @@ +# virtualMethod + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestAbstractClass](./test-suite-a/testabstractclass-class/) > [virtualMethod()](./test-suite-a/testabstractclass-class/virtualmethod-method) + +A test `@virtual` method. + +## Signature {#virtualmethod-signature} + +```typescript +/** @virtual */ +protected virtualMethod(): number; +``` + +## Returns {#virtualmethod-returns} + +A number! + +**Return type:** number diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/_constructor_-constructor.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/_constructor_-constructor.md new file mode 100644 index 000000000000..900d4e2a0c1e --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/_constructor_-constructor.md @@ -0,0 +1,24 @@ +# (constructor) + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [(constructor)(privateProperty, protectedProperty, testClassProperty, testClassEventProperty)](./test-suite-a/testclass-class/_constructor_-constructor) + +Test class constructor + +## Signature {#\_constructor\_-signature} + +```typescript +constructor(privateProperty: number, protectedProperty: TestEnum, testClassProperty: TTypeParameterB, testClassEventProperty: () => void); +``` + +## Remarks {#\_constructor\_-remarks} + +Here are some remarks about the constructor + +## Parameters {#\_constructor\_-parameters} + +| Parameter | Type | Description | +| --- | --- | --- | +| privateProperty | number | See [TestAbstractClass](./test-suite-a/testabstractclass-class/)'s constructor. | +| protectedProperty | [TestEnum](./test-suite-a/testenum-enum/) |

Some notes about the parameter.

See protectedProperty.

| +| testClassProperty | TTypeParameterB | See [testClassProperty](./test-suite-a/testclass-class/testclassproperty-property). | +| testClassEventProperty | () => void | See [testClassEventProperty](./test-suite-a/testclass-class/testclasseventproperty-property). | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/abstractpropertygetter-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/abstractpropertygetter-property.md new file mode 100644 index 000000000000..7f04e03f8c49 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/abstractpropertygetter-property.md @@ -0,0 +1,13 @@ +# abstractPropertyGetter + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [abstractPropertyGetter](./test-suite-a/testclass-class/abstractpropertygetter-property) + +A test abstract getter property. + +## Signature {#abstractpropertygetter-signature} + +```typescript +get abstractPropertyGetter(): TestMappedType; +``` + +**Type:** [TestMappedType](./test-suite-a/testmappedtype-typealias/) diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/index.md new file mode 100644 index 000000000000..c37ae228439e --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/index.md @@ -0,0 +1,68 @@ +# TestClass + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) + +Test class + +## Signature {#testclass-signature} + +```typescript +export declare class TestClass extends TestAbstractClass +``` + +**Extends:** [TestAbstractClass](./test-suite-a/testabstractclass-class/) + +### Type Parameters + +| Parameter | Description | +| --- | --- | +| TTypeParameterA | A type parameter | +| TTypeParameterB | Another type parameter | + +## Remarks {#testclass-remarks} + +Here are some remarks about the class + +## Constructors + +| Constructor | Description | +| --- | --- | +| [(constructor)(privateProperty, protectedProperty, testClassProperty, testClassEventProperty)](./test-suite-a/testclass-class/_constructor_-constructor) | Test class constructor | + +## Static Properties + +| Property | Type | Description | +| --- | --- | --- | +| [testClassStaticProperty](./test-suite-a/testclass-class/testclassstaticproperty-property) | (foo: number) => string | Test static class property | + +## Static Methods + +| Method | Return Type | Description | +| --- | --- | --- | +| [testClassStaticMethod(foo)](./test-suite-a/testclass-class/testclassstaticmethod-method) | string | Test class static method | + +## Events + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [testClassEventProperty](./test-suite-a/testclass-class/testclasseventproperty-property) | `readonly` | () => void | Test class event property | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [abstractPropertyGetter](./test-suite-a/testclass-class/abstractpropertygetter-property) | `readonly` | [TestMappedType](./test-suite-a/testmappedtype-typealias/) | A test abstract getter property. | +| [testClassGetterProperty](./test-suite-a/testclass-class/testclassgetterproperty-property) | `virtual` | number | Test class property with both a getter and a setter. | +| [testClassProperty](./test-suite-a/testclass-class/testclassproperty-property) | `readonly` | TTypeParameterB | Test class property | + +## Methods + +| Method | Modifiers | Return Type | Description | +| --- | --- | --- | --- | +| [publicAbstractMethod()](./test-suite-a/testclass-class/publicabstractmethod-method) | | void | A test public abstract method. | +| [testClassMethod(input)](./test-suite-a/testclass-class/testclassmethod-method) | `sealed` | TTypeParameterA | Test class method | +| [virtualMethod()](./test-suite-a/testclass-class/virtualmethod-method) | | number | Overrides [virtualMethod()](./test-suite-a/testabstractclass-class/virtualmethod-method). | + +## See Also {#testclass-see-also} + +[TestAbstractClass](./test-suite-a/testabstractclass-class/) diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/publicabstractmethod-method.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/publicabstractmethod-method.md new file mode 100644 index 000000000000..7f039a2242a7 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/publicabstractmethod-method.md @@ -0,0 +1,11 @@ +# publicAbstractMethod + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [publicAbstractMethod()](./test-suite-a/testclass-class/publicabstractmethod-method) + +A test public abstract method. + +## Signature {#publicabstractmethod-signature} + +```typescript +publicAbstractMethod(): void; +``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclasseventproperty-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclasseventproperty-property.md new file mode 100644 index 000000000000..5309a5bebdc0 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclasseventproperty-property.md @@ -0,0 +1,17 @@ +# testClassEventProperty + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [testClassEventProperty](./test-suite-a/testclass-class/testclasseventproperty-property) + +Test class event property + +## Signature {#testclasseventproperty-signature} + +```typescript +readonly testClassEventProperty: () => void; +``` + +**Type:** () => void + +## Remarks {#testclasseventproperty-remarks} + +Here are some remarks about the property diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassgetterproperty-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassgetterproperty-property.md new file mode 100644 index 000000000000..252f535f42c6 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassgetterproperty-property.md @@ -0,0 +1,19 @@ +# testClassGetterProperty + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [testClassGetterProperty](./test-suite-a/testclass-class/testclassgetterproperty-property) + +Test class property with both a getter and a setter. + +## Signature {#testclassgetterproperty-signature} + +```typescript +/** @virtual */ +get testClassGetterProperty(): number; +set testClassGetterProperty(newValue: number); +``` + +**Type:** number + +## Remarks {#testclassgetterproperty-remarks} + +Here are some remarks about the getter-only property diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassmethod-method.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassmethod-method.md new file mode 100644 index 000000000000..19b30bd6dd25 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassmethod-method.md @@ -0,0 +1,32 @@ +# testClassMethod + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [testClassMethod(input)](./test-suite-a/testclass-class/testclassmethod-method) + +Test class method + +## Signature {#testclassmethod-signature} + +```typescript +/** @sealed */ +testClassMethod(input: TTypeParameterA): TTypeParameterA; +``` + +## Remarks {#testclassmethod-remarks} + +Here are some remarks about the method + +## Parameters {#testclassmethod-parameters} + +| Parameter | Type | Description | +| --- | --- | --- | +| input | TTypeParameterA | | + +## Returns {#testclassmethod-returns} + +**Return type:** TTypeParameterA + +## Throws {#testclassmethod-throws} + +Some sort of error in 1 case. + +Some other sort of error in another case. For example, a case where some thing happens. diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassproperty-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassproperty-property.md new file mode 100644 index 000000000000..5ce1e6f7f288 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassproperty-property.md @@ -0,0 +1,17 @@ +# testClassProperty + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [testClassProperty](./test-suite-a/testclass-class/testclassproperty-property) + +Test class property + +## Signature {#testclassproperty-signature} + +```typescript +readonly testClassProperty: TTypeParameterB; +``` + +**Type:** TTypeParameterB + +## Remarks {#testclassproperty-remarks} + +Here are some remarks about the property diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticmethod-method.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticmethod-method.md new file mode 100644 index 000000000000..25859dfec07b --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticmethod-method.md @@ -0,0 +1,23 @@ +# testClassStaticMethod + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [testClassStaticMethod(foo)](./test-suite-a/testclass-class/testclassstaticmethod-method) + +Test class static method + +## Signature {#testclassstaticmethod-signature} + +```typescript +static testClassStaticMethod(foo: number): string; +``` + +## Parameters {#testclassstaticmethod-parameters} + +| Parameter | Type | Description | +| --- | --- | --- | +| foo | number | Some number | + +## Returns {#testclassstaticmethod-returns} + +- Some string + +**Return type:** string diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticproperty-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticproperty-property.md new file mode 100644 index 000000000000..6d6001f30f52 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticproperty-property.md @@ -0,0 +1,13 @@ +# testClassStaticProperty + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [testClassStaticProperty](./test-suite-a/testclass-class/testclassstaticproperty-property) + +Test static class property + +## Signature {#testclassstaticproperty-signature} + +```typescript +static testClassStaticProperty: (foo: number) => string; +``` + +**Type:** (foo: number) => string diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/virtualmethod-method.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/virtualmethod-method.md new file mode 100644 index 000000000000..7c2df61225ed --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/virtualmethod-method.md @@ -0,0 +1,16 @@ +# virtualMethod + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [virtualMethod()](./test-suite-a/testclass-class/virtualmethod-method) + +Overrides [virtualMethod()](./test-suite-a/testabstractclass-class/virtualmethod-method). + +## Signature {#virtualmethod-signature} + +```typescript +/** @override */ +protected virtualMethod(): number; +``` + +## Returns {#virtualmethod-returns} + +**Return type:** number diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testconst-variable.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testconst-variable.md new file mode 100644 index 000000000000..660e92e199d6 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testconst-variable.md @@ -0,0 +1,17 @@ +# testConst + +[Packages](./) > [test-suite-a](./test-suite-a/) > [testConst](./test-suite-a/testconst-variable) + +Test Constant + +**WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.** + +## Signature {#testconst-signature} + +```typescript +testConst = 42 +``` + +## Remarks {#testconst-remarks} + +Here are some remarks about the variable diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testconstwithemptydeprecatedblock-variable.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testconstwithemptydeprecatedblock-variable.md new file mode 100644 index 000000000000..720e219ac11c --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testconstwithemptydeprecatedblock-variable.md @@ -0,0 +1,15 @@ +# testConstWithEmptyDeprecatedBlock + +[Packages](./) > [test-suite-a](./test-suite-a/) > [testConstWithEmptyDeprecatedBlock](./test-suite-a/testconstwithemptydeprecatedblock-variable) + +I have a `@deprecated` tag with an empty comment block. + +**WARNING: This API is deprecated and will be removed in a future release.** + +## Signature {#testconstwithemptydeprecatedblock-signature} + +```typescript +testConstWithEmptyDeprecatedBlock: string +``` + +**Type:** string diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testemptyinterface-interface/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testemptyinterface-interface/index.md new file mode 100644 index 000000000000..d1f8b21536a5 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testemptyinterface-interface/index.md @@ -0,0 +1,11 @@ +# TestEmptyInterface + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestEmptyInterface](./test-suite-a/testemptyinterface-interface/) + +An empty interface + +## Signature {#testemptyinterface-signature} + +```typescript +export interface TestEmptyInterface +``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/index.md new file mode 100644 index 000000000000..97691f5456a2 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/index.md @@ -0,0 +1,77 @@ +# TestEnum + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestEnum](./test-suite-a/testenum-enum/) + +Test Enum + +## Signature {#testenum-signature} + +```typescript +export declare enum TestEnum +``` + +## Remarks {#testenum-remarks} + +Here are some remarks about the enum + +## Examples {#testenum-examples} + +### Example 1 {#testenum-example1} + +Some example + +```typescript +const foo = TestEnum.TestEnumValue1 +``` + +### Example 2 {#testenum-example2} + +Another example + +```ts +const bar = TestEnum.TestEnumValue2 +``` + +## Flags + +| Flag | Description | +| --- | --- | +| [TestEnumValue1](./test-suite-a/testenum-enum/testenumvalue1-enummember) | Test enum value 1 (string) | +| [TestEnumValue2](./test-suite-a/testenum-enum/testenumvalue2-enummember) | Test enum value 2 (number) | +| [TestEnumValue3](./test-suite-a/testenum-enum/testenumvalue3-enummember) | Test enum value 3 (default) | + +Test enum value 1 (string) + +### Signature {#testenumvalue1-signature} + +```typescript +TestEnumValue1 = "test-enum-value-1" +``` + +### Remarks {#testenumvalue1-remarks} + +Here are some remarks about the enum value + +Test enum value 2 (number) + +### Signature {#testenumvalue2-signature} + +```typescript +TestEnumValue2 = 3 +``` + +### Remarks {#testenumvalue2-remarks} + +Here are some remarks about the enum value + +Test enum value 3 (default) + +### Signature {#testenumvalue3-signature} + +```typescript +TestEnumValue3 = 4 +``` + +### Remarks {#testenumvalue3-remarks} + +Here are some remarks about the enum value diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue1-enummember.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue1-enummember.md new file mode 100644 index 000000000000..28dc1db6fc13 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue1-enummember.md @@ -0,0 +1,15 @@ +# TestEnumValue1 + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestEnum](./test-suite-a/testenum-enum/) > [TestEnumValue1](./test-suite-a/testenum-enum/testenumvalue1-enummember) + +Test enum value 1 (string) + +## Signature {#testenumvalue1-signature} + +```typescript +TestEnumValue1 = "test-enum-value-1" +``` + +## Remarks {#testenumvalue1-remarks} + +Here are some remarks about the enum value diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue2-enummember.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue2-enummember.md new file mode 100644 index 000000000000..058b0e361279 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue2-enummember.md @@ -0,0 +1,15 @@ +# TestEnumValue2 + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestEnum](./test-suite-a/testenum-enum/) > [TestEnumValue2](./test-suite-a/testenum-enum/testenumvalue2-enummember) + +Test enum value 2 (number) + +## Signature {#testenumvalue2-signature} + +```typescript +TestEnumValue2 = 3 +``` + +## Remarks {#testenumvalue2-remarks} + +Here are some remarks about the enum value diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue3-enummember.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue3-enummember.md new file mode 100644 index 000000000000..38d5f92e2c0d --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue3-enummember.md @@ -0,0 +1,15 @@ +# TestEnumValue3 + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestEnum](./test-suite-a/testenum-enum/) > [TestEnumValue3](./test-suite-a/testenum-enum/testenumvalue3-enummember) + +Test enum value 3 (default) + +## Signature {#testenumvalue3-signature} + +```typescript +TestEnumValue3 = 4 +``` + +## Remarks {#testenumvalue3-remarks} + +Here are some remarks about the enum value diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunction-function.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunction-function.md new file mode 100644 index 000000000000..5d6630bb2af4 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunction-function.md @@ -0,0 +1,40 @@ +# testFunction + +[Packages](./) > [test-suite-a](./test-suite-a/) > [testFunction(testParameter, testOptionalParameter)](./test-suite-a/testfunction-function) + +Test function + +**WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.** + +## Signature {#testfunction-signature} + +```typescript +export declare function testFunction(testParameter: TTypeParameter, testOptionalParameter?: TTypeParameter): TTypeParameter; +``` + +### Type Parameters + +| Parameter | Constraint | Default | Description | +| --- | --- | --- | --- | +| TTypeParameter | [TestInterface](./test-suite-a/testinterface-interface/) | [TestInterface](./test-suite-a/testinterface-interface/) | A test type parameter | + +## Remarks {#testfunction-remarks} + +This is a test [link](./test-suite-a/testinterface-interface/) to another API member + +## Parameters {#testfunction-parameters} + +| Parameter | Modifiers | Type | Description | +| --- | --- | --- | --- | +| testParameter | | TTypeParameter | A test parameter | +| testOptionalParameter | optional | TTypeParameter | | + +## Returns {#testfunction-returns} + +The provided parameter + +**Return type:** TTypeParameter + +## Throws {#testfunction-throws} + +An Error when something bad happens. diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturninginlinetype-function.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturninginlinetype-function.md new file mode 100644 index 000000000000..9d6e2a5fb10c --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturninginlinetype-function.md @@ -0,0 +1,20 @@ +# testFunctionReturningInlineType + +[Packages](./) > [test-suite-a](./test-suite-a/) > [testFunctionReturningInlineType()](./test-suite-a/testfunctionreturninginlinetype-function) + +Test function that returns an inline type + +## Signature {#testfunctionreturninginlinetype-signature} + +```typescript +export declare function testFunctionReturningInlineType(): { + foo: number; + bar: TestEnum; +}; +``` + +## Returns {#testfunctionreturninginlinetype-returns} + +An inline type + +**Return type:** { foo: number; bar: [TestEnum](./test-suite-a/testenum-enum/); } diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturningintersectiontype-function.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturningintersectiontype-function.md new file mode 100644 index 000000000000..5725f72cebf6 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturningintersectiontype-function.md @@ -0,0 +1,21 @@ +# testFunctionReturningIntersectionType + +[Packages](./) > [test-suite-a](./test-suite-a/) > [testFunctionReturningIntersectionType()](./test-suite-a/testfunctionreturningintersectiontype-function) + +Test function that returns an inline type + +**WARNING: This API is deprecated and will be removed in a future release.** + +_This is a test deprecation notice. Here is a_ [_link_](./test-suite-a/testfunctionreturninguniontype-function) _to something else!_ + +## Signature {#testfunctionreturningintersectiontype-signature} + +```typescript +export declare function testFunctionReturningIntersectionType(): TestEmptyInterface & TestInterfaceWithTypeParameter; +``` + +## Returns {#testfunctionreturningintersectiontype-returns} + +an intersection type + +**Return type:** [TestEmptyInterface](./test-suite-a/testemptyinterface-interface/) & [TestInterfaceWithTypeParameter](./test-suite-a/testinterfacewithtypeparameter-interface/)<number> diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturninguniontype-function.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturninguniontype-function.md new file mode 100644 index 000000000000..c5c7ef474ae1 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturninguniontype-function.md @@ -0,0 +1,17 @@ +# testFunctionReturningUnionType + +[Packages](./) > [test-suite-a](./test-suite-a/) > [testFunctionReturningUnionType()](./test-suite-a/testfunctionreturninguniontype-function) + +Test function that returns an inline type + +## Signature {#testfunctionreturninguniontype-signature} + +```typescript +export declare function testFunctionReturningUnionType(): string | TestInterface; +``` + +## Returns {#testfunctionreturninguniontype-returns} + +A union type + +**Return type:** string \| [TestInterface](./test-suite-a/testinterface-interface/) diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call_-callsignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call_-callsignature.md new file mode 100644 index 000000000000..8ab0989a91c0 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call_-callsignature.md @@ -0,0 +1,15 @@ +# (event: 'testCallSignature', listener: (input: unknown) => void): any + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [(event: 'testCallSignature', listener: (input: unknown) => void): any](./test-suite-a/testinterface-interface/_call_-callsignature) + +Test interface event call signature + +## Signature {#\_call\_-signature} + +```typescript +(event: 'testCallSignature', listener: (input: unknown) => void): any; +``` + +## Remarks {#\_call\_-remarks} + +Here are some remarks about the event call signature diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call__1-callsignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call__1-callsignature.md new file mode 100644 index 000000000000..b3055d99c94c --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call__1-callsignature.md @@ -0,0 +1,15 @@ +# (event: 'anotherTestCallSignature', listener: (input: number) => string): number + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [(event: 'anotherTestCallSignature', listener: (input: number) => string): number](./test-suite-a/testinterface-interface/_call__1-callsignature) + +Another example call signature + +## Signature {#\_call\_\_1-signature} + +```typescript +(event: 'anotherTestCallSignature', listener: (input: number) => string): number; +``` + +## Remarks {#\_call\_\_1-remarks} + +Here are some remarks about the event call signature diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_new_-constructsignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_new_-constructsignature.md new file mode 100644 index 000000000000..5d07085f787a --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_new_-constructsignature.md @@ -0,0 +1,15 @@ +# new (): TestInterface + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [new (): TestInterface](./test-suite-a/testinterface-interface/_new_-constructsignature) + +Test construct signature. + +## Signature {#\_new\_-signature} + +```typescript +new (): TestInterface; +``` + +## Returns {#\_new\_-returns} + +**Return type:** [TestInterface](./test-suite-a/testinterface-interface/) diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/getterproperty-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/getterproperty-property.md new file mode 100644 index 000000000000..8ba7a2708f75 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/getterproperty-property.md @@ -0,0 +1,13 @@ +# getterProperty + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [getterProperty](./test-suite-a/testinterface-interface/getterproperty-property) + +A test getter-only interface property. + +## Signature {#getterproperty-signature} + +```typescript +get getterProperty(): boolean; +``` + +**Type:** boolean diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/index.md new file mode 100644 index 000000000000..10a1e90a2f7d --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/index.md @@ -0,0 +1,60 @@ +# TestInterface + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) + +Test interface + +## Signature {#testinterface-signature} + +```typescript +export interface TestInterface +``` + +## Remarks {#testinterface-remarks} + +Here are some remarks about the interface + +## Construct Signatures + +| ConstructSignature | Return Type | Description | +| --- | --- | --- | +| [new (): TestInterface](./test-suite-a/testinterface-interface/_new_-constructsignature) | [TestInterface](./test-suite-a/testinterface-interface/) | Test construct signature. | + +## Events + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [testClassEventProperty](./test-suite-a/testinterface-interface/testclasseventproperty-propertysignature) | `readonly` | () => void | Test interface event property | + +## Properties + +| Property | Modifiers | Default Value | Type | Description | +| --- | --- | --- | --- | --- | +| [getterProperty](./test-suite-a/testinterface-interface/getterproperty-property) | `readonly` | | boolean | A test getter-only interface property. | +| [propertyWithBadInheritDocTarget](./test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature) | | | boolean | | +| [setterProperty](./test-suite-a/testinterface-interface/setterproperty-property) | | | boolean | A test property with a getter and a setter. | +| [testInterfaceProperty](./test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature) | | | number | Test interface property | +| [testOptionalInterfaceProperty](./test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature) | `optional` | 0 | number | Test optional property | + +## Methods + +| Method | Return Type | Description | +| --- | --- | --- | +| [testInterfaceMethod()](./test-suite-a/testinterface-interface/testinterfacemethod-methodsignature) | void | Test interface method | + +## Call Signatures + +| CallSignature | Description | +| --- | --- | +| [(event: 'testCallSignature', listener: (input: unknown) => void): any](./test-suite-a/testinterface-interface/_call_-callsignature) | Test interface event call signature | +| [(event: 'anotherTestCallSignature', listener: (input: number) => string): number](./test-suite-a/testinterface-interface/_call__1-callsignature) | Another example call signature | + +## See Also {#testinterface-see-also} + +[testInterfaceMethod()](./test-suite-a/testinterface-interface/testinterfacemethod-methodsignature) + +[testInterfaceProperty](./test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature) + +[testOptionalInterfaceProperty](./test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature) + +[testClassEventProperty](./test-suite-a/testinterface-interface/testclasseventproperty-propertysignature) diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature.md new file mode 100644 index 000000000000..e81429daac44 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature.md @@ -0,0 +1,11 @@ +# propertyWithBadInheritDocTarget + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [propertyWithBadInheritDocTarget](./test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature) + +## Signature {#propertywithbadinheritdoctarget-signature} + +```typescript +propertyWithBadInheritDocTarget: boolean; +``` + +**Type:** boolean diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/setterproperty-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/setterproperty-property.md new file mode 100644 index 000000000000..00f56367f160 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/setterproperty-property.md @@ -0,0 +1,14 @@ +# setterProperty + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [setterProperty](./test-suite-a/testinterface-interface/setterproperty-property) + +A test property with a getter and a setter. + +## Signature {#setterproperty-signature} + +```typescript +get setterProperty(): boolean; +set setterProperty(newValue: boolean); +``` + +**Type:** boolean diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testclasseventproperty-propertysignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testclasseventproperty-propertysignature.md new file mode 100644 index 000000000000..85d8d5b93b2f --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testclasseventproperty-propertysignature.md @@ -0,0 +1,17 @@ +# testClassEventProperty + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [testClassEventProperty](./test-suite-a/testinterface-interface/testclasseventproperty-propertysignature) + +Test interface event property + +## Signature {#testclasseventproperty-signature} + +```typescript +readonly testClassEventProperty: () => void; +``` + +**Type:** () => void + +## Remarks {#testclasseventproperty-remarks} + +Here are some remarks about the event property diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfacemethod-methodsignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfacemethod-methodsignature.md new file mode 100644 index 000000000000..211fdfa3ddb2 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfacemethod-methodsignature.md @@ -0,0 +1,15 @@ +# testInterfaceMethod + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [testInterfaceMethod()](./test-suite-a/testinterface-interface/testinterfacemethod-methodsignature) + +Test interface method + +## Signature {#testinterfacemethod-signature} + +```typescript +testInterfaceMethod(): void; +``` + +## Remarks {#testinterfacemethod-remarks} + +Here are some remarks about the method diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature.md new file mode 100644 index 000000000000..e09fcb713294 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature.md @@ -0,0 +1,17 @@ +# testInterfaceProperty + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [testInterfaceProperty](./test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature) + +Test interface property + +## Signature {#testinterfaceproperty-signature} + +```typescript +testInterfaceProperty: number; +``` + +**Type:** number + +## Remarks {#testinterfaceproperty-remarks} + +Here are some remarks about the property diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature.md new file mode 100644 index 000000000000..c037d5610e6a --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature.md @@ -0,0 +1,13 @@ +# testOptionalInterfaceProperty + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [testOptionalInterfaceProperty](./test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature) + +Test optional property + +## Signature {#testoptionalinterfaceproperty-signature} + +```typescript +testOptionalInterfaceProperty?: number; +``` + +**Type:** number diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/index.md new file mode 100644 index 000000000000..704342163ce8 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/index.md @@ -0,0 +1,31 @@ +# TestInterfaceExtendingOtherInterfaces + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterfaceExtendingOtherInterfaces](./test-suite-a/testinterfaceextendingotherinterfaces-interface/) + +Test interface that extends other interfaces + +## Signature {#testinterfaceextendingotherinterfaces-signature} + +```typescript +export interface TestInterfaceExtendingOtherInterfaces extends TestInterface, TestMappedType, TestInterfaceWithTypeParameter +``` + +**Extends:** [TestInterface](./test-suite-a/testinterface-interface/), [TestMappedType](./test-suite-a/testmappedtype-typealias/), [TestInterfaceWithTypeParameter](./test-suite-a/testinterfacewithtypeparameter-interface/)<number> + +## Remarks {#testinterfaceextendingotherinterfaces-remarks} + +Here are some remarks about the interface + +## Methods + +| Method | Return Type | Description | +| --- | --- | --- | +| [testMethod(input)](./test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature) | number | Test interface method accepting a string and returning a number. | + +## See Also {#testinterfaceextendingotherinterfaces-see-also} + +- [TestInterface](./test-suite-a/testinterface-interface/) + +- [TestInterfaceWithTypeParameter](./test-suite-a/testinterfacewithtypeparameter-interface/) + +- [TestMappedType](./test-suite-a/testmappedtype-typealias/) diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature.md new file mode 100644 index 000000000000..8c0dd32030f8 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature.md @@ -0,0 +1,27 @@ +# testMethod + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterfaceExtendingOtherInterfaces](./test-suite-a/testinterfaceextendingotherinterfaces-interface/) > [testMethod(input)](./test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature) + +Test interface method accepting a string and returning a number. + +## Signature {#testmethod-signature} + +```typescript +testMethod(input: string): number; +``` + +## Remarks {#testmethod-remarks} + +Here are some remarks about the method + +## Parameters {#testmethod-parameters} + +| Parameter | Type | Description | +| --- | --- | --- | +| input | string | A string | + +## Returns {#testmethod-returns} + +A number + +**Return type:** number diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature.md new file mode 100644 index 000000000000..dcfa5215c972 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature.md @@ -0,0 +1,13 @@ +# \[foo: number\]: { bar: string; } + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterfaceWithIndexSignature](./test-suite-a/testinterfacewithindexsignature-interface/) > [\[foo: number\]: { bar: string; }](./test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature) + +Test index signature. + +## Signature {#\_indexer\_-signature} + +```typescript +[foo: number]: { + bar: string; + }; +``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/index.md new file mode 100644 index 000000000000..a3bd5063e563 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/index.md @@ -0,0 +1,17 @@ +# TestInterfaceWithIndexSignature + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterfaceWithIndexSignature](./test-suite-a/testinterfacewithindexsignature-interface/) + +An interface with an index signature. + +## Signature {#testinterfacewithindexsignature-signature} + +```typescript +export interface TestInterfaceWithIndexSignature +``` + +## Index Signatures + +| IndexSignature | Description | +| --- | --- | +| [\[foo: number\]: { bar: string; }](./test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature) | Test index signature. | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/index.md new file mode 100644 index 000000000000..63d540c7ea65 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/index.md @@ -0,0 +1,27 @@ +# TestInterfaceWithTypeParameter + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterfaceWithTypeParameter](./test-suite-a/testinterfacewithtypeparameter-interface/) + +Test interface with generic type parameter + +## Signature {#testinterfacewithtypeparameter-signature} + +```typescript +export interface TestInterfaceWithTypeParameter +``` + +### Type Parameters + +| Parameter | Description | +| --- | --- | +| T | A type parameter | + +## Remarks {#testinterfacewithtypeparameter-remarks} + +Here are some remarks about the interface + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [testProperty](./test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature) | T | A test interface property using generic type parameter | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature.md new file mode 100644 index 000000000000..8879124e471a --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature.md @@ -0,0 +1,17 @@ +# testProperty + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterfaceWithTypeParameter](./test-suite-a/testinterfacewithtypeparameter-interface/) > [testProperty](./test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature) + +A test interface property using generic type parameter + +## Signature {#testproperty-signature} + +```typescript +testProperty: T; +``` + +**Type:** T + +## Remarks {#testproperty-remarks} + +Here are some remarks about the property diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmappedtype-typealias/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmappedtype-typealias/index.md new file mode 100644 index 000000000000..07b38df823d8 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmappedtype-typealias/index.md @@ -0,0 +1,17 @@ +# TestMappedType + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestMappedType](./test-suite-a/testmappedtype-typealias/) + +Test Mapped Type, using [TestEnum](./test-suite-a/testenum-enum/) + +## Signature {#testmappedtype-signature} + +```typescript +export type TestMappedType = { + [K in TestEnum]: boolean; +}; +``` + +## Remarks {#testmappedtype-remarks} + +Here are some remarks about the mapped type diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/foo-variable.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/foo-variable.md new file mode 100644 index 000000000000..412aab1038d9 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/foo-variable.md @@ -0,0 +1,11 @@ +# foo + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestModule](./test-suite-a/testmodule-namespace/) > [foo](./test-suite-a/testmodule-namespace/foo-variable) + +Test constant in module. + +## Signature {#foo-signature} + +```typescript +foo = 2 +``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/index.md new file mode 100644 index 000000000000..1d7718103821 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/index.md @@ -0,0 +1,9 @@ +# TestModule + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestModule](./test-suite-a/testmodule-namespace/) + +## Variables + +| Variable | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [foo](./test-suite-a/testmodule-namespace/foo-variable) | `readonly` | | Test constant in module. | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/index.md new file mode 100644 index 000000000000..968d10a5bf40 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/index.md @@ -0,0 +1,77 @@ +# TestNamespace + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) + +Test Namespace + +## Signature {#testnamespace-signature} + +```typescript +export declare namespace TestNamespace +``` + +## Remarks {#testnamespace-remarks} + +Here are some remarks about the namespace + +## Examples {#testnamespace-examples} + +### Example: TypeScript Example {#testnamespace-example1} + +```typescript +const foo: Foo = { + bar: "Hello world!"; + baz = 42; +}; +``` + +### Example: JavaScript Example {#testnamespace-example2} + +```javascript +const foo = { + bar: "Hello world!"; + baz = 42; +}; +``` + +## Interfaces + +| Interface | Alerts | Description | +| --- | --- | --- | +| [TestInterface](./test-suite-a/testnamespace-namespace/testinterface-interface/) | `Alpha` | Test interface | + +## Classes + +| Class | Description | +| --- | --- | +| [TestClass](./test-suite-a/testnamespace-namespace/testclass-class/) | Test class | + +## Enumerations + +| Enum | Description | +| --- | --- | +| [TestEnum](./test-suite-a/testnamespace-namespace/testenum-enum/) | Test Enum | + +## Types + +| TypeAlias | Description | +| --- | --- | +| [TestTypeAlias](./test-suite-a/testnamespace-namespace/testtypealias-typealias/) | Test Type-Alias | + +## Functions + +| Function | Return Type | Description | +| --- | --- | --- | +| [testFunction(testParameter)](./test-suite-a/testnamespace-namespace/testfunction-function) | number | Test function | + +## Variables + +| Variable | Alerts | Modifiers | Type | Description | +| --- | --- | --- | --- | --- | +| [TestConst](./test-suite-a/testnamespace-namespace/testconst-variable) | `Beta` | `readonly` | | Test Constant | + +## Namespaces + +| Namespace | Description | +| --- | --- | +| [TestSubNamespace](./test-suite-a/testnamespace-namespace/testsubnamespace-namespace/) | Test sub-namespace | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor.md new file mode 100644 index 000000000000..f3db36a74d71 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor.md @@ -0,0 +1,17 @@ +# (constructor) + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestClass](./test-suite-a/testnamespace-namespace/testclass-class/) > [(constructor)(testClassProperty)](./test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor) + +Test class constructor + +## Signature {#\_constructor\_-signature} + +```typescript +constructor(testClassProperty: string); +``` + +## Parameters {#\_constructor\_-parameters} + +| Parameter | Type | Description | +| --- | --- | --- | +| testClassProperty | string | See [testClassProperty](./test-suite-a/testclass-class/testclassproperty-property) | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/index.md new file mode 100644 index 000000000000..a2a163202e9a --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/index.md @@ -0,0 +1,29 @@ +# TestClass + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestClass](./test-suite-a/testnamespace-namespace/testclass-class/) + +Test class + +## Signature {#testclass-signature} + +```typescript +class TestClass +``` + +## Constructors + +| Constructor | Description | +| --- | --- | +| [(constructor)(testClassProperty)](./test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor) | Test class constructor | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [testClassProperty](./test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property) | `readonly` | string | Test interface property | + +## Methods + +| Method | Return Type | Description | +| --- | --- | --- | +| [testClassMethod(testParameter)](./test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method) | Promise<string> | Test class method | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method.md new file mode 100644 index 000000000000..66a8a38f9e22 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method.md @@ -0,0 +1,31 @@ +# testClassMethod + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestClass](./test-suite-a/testnamespace-namespace/testclass-class/) > [testClassMethod(testParameter)](./test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method) + +Test class method + +## Signature {#testclassmethod-signature} + +```typescript +testClassMethod(testParameter: string): Promise; +``` + +## Parameters {#testclassmethod-parameters} + +| Parameter | Type | Description | +| --- | --- | --- | +| testParameter | string | A string | + +## Returns {#testclassmethod-returns} + +A Promise + +**Return type:** Promise<string> + +## Throws {#testclassmethod-throws} + +An Error when something happens for which an error should be thrown. Except in the cases where another kind of error is thrown. We don't throw this error in those cases. + +A different kind of error when a thing happens, but not when the first kind of error is thrown instead. + +😁 diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property.md new file mode 100644 index 000000000000..9c993b1ff6d9 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property.md @@ -0,0 +1,13 @@ +# testClassProperty + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestClass](./test-suite-a/testnamespace-namespace/testclass-class/) > [testClassProperty](./test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property) + +Test interface property + +## Signature {#testclassproperty-signature} + +```typescript +readonly testClassProperty: string; +``` + +**Type:** string diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testconst-variable.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testconst-variable.md new file mode 100644 index 000000000000..343608f24e1c --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testconst-variable.md @@ -0,0 +1,13 @@ +# TestConst + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestConst](./test-suite-a/testnamespace-namespace/testconst-variable) + +Test Constant + +**WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.** + +## Signature {#testconst-signature} + +```typescript +TestConst = "Hello world!" +``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/index.md new file mode 100644 index 000000000000..18920c2edba3 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/index.md @@ -0,0 +1,34 @@ +# TestEnum + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestEnum](./test-suite-a/testnamespace-namespace/testenum-enum/) + +Test Enum + +## Signature {#testenum-signature} + +```typescript +enum TestEnum +``` + +## Flags + +| Flag | Description | +| --- | --- | +| [TestEnumValue1](./test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember) | Test enum value 1 | +| [TestEnumValue2](./test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember) | Test enum value 2 | + +Test enum value 1 + +### Signature {#testenumvalue1-signature} + +```typescript +TestEnumValue1 = 0 +``` + +Test enum value 2 + +### Signature {#testenumvalue2-signature} + +```typescript +TestEnumValue2 = 1 +``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember.md new file mode 100644 index 000000000000..17fc20c60c5e --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember.md @@ -0,0 +1,11 @@ +# TestEnumValue1 + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestEnum](./test-suite-a/testnamespace-namespace/testenum-enum/) > [TestEnumValue1](./test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember) + +Test enum value 1 + +## Signature {#testenumvalue1-signature} + +```typescript +TestEnumValue1 = 0 +``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember.md new file mode 100644 index 000000000000..cc0f1df5018d --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember.md @@ -0,0 +1,11 @@ +# TestEnumValue2 + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestEnum](./test-suite-a/testnamespace-namespace/testenum-enum/) > [TestEnumValue2](./test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember) + +Test enum value 2 + +## Signature {#testenumvalue2-signature} + +```typescript +TestEnumValue2 = 1 +``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testfunction-function.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testfunction-function.md new file mode 100644 index 000000000000..29bb76f19c72 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testfunction-function.md @@ -0,0 +1,27 @@ +# testFunction + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [testFunction(testParameter)](./test-suite-a/testnamespace-namespace/testfunction-function) + +Test function + +## Signature {#testfunction-signature} + +```typescript +function testFunction(testParameter: number): number; +``` + +## Parameters {#testfunction-parameters} + +| Parameter | Type | Description | +| --- | --- | --- | +| testParameter | number | | + +## Returns {#testfunction-returns} + +A number + +**Return type:** number + +## Throws {#testfunction-throws} + +An Error diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/index.md new file mode 100644 index 000000000000..33639ebe1a9a --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/index.md @@ -0,0 +1,27 @@ +# TestInterface + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestInterface](./test-suite-a/testnamespace-namespace/testinterface-interface/) + +Test interface + +**WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.** + +## Signature {#testinterface-signature} + +```typescript +interface TestInterface extends TestInterfaceWithTypeParameter +``` + +**Extends:** [TestInterfaceWithTypeParameter](./test-suite-a/testinterfacewithtypeparameter-interface/)<[TestEnum](./test-suite-a/testnamespace-namespace/testenum-enum/)> + +## Properties + +| Property | Alerts | Type | Description | +| --- | --- | --- | --- | +| [testInterfaceProperty](./test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature) | `Alpha` | boolean | Test interface property | + +## Methods + +| Method | Alerts | Return Type | Description | +| --- | --- | --- | --- | +| [testInterfaceMethod()](./test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature) | `Alpha` | void | Test interface method | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature.md new file mode 100644 index 000000000000..430c8bcc5eb2 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature.md @@ -0,0 +1,13 @@ +# testInterfaceMethod + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestInterface](./test-suite-a/testnamespace-namespace/testinterface-interface/) > [testInterfaceMethod()](./test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature) + +Test interface method + +**WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.** + +## Signature {#testinterfacemethod-signature} + +```typescript +testInterfaceMethod(): void; +``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature.md new file mode 100644 index 000000000000..0ed96d9bc24f --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature.md @@ -0,0 +1,15 @@ +# testInterfaceProperty + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestInterface](./test-suite-a/testnamespace-namespace/testinterface-interface/) > [testInterfaceProperty](./test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature) + +Test interface property + +**WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.** + +## Signature {#testinterfaceproperty-signature} + +```typescript +testInterfaceProperty: boolean; +``` + +**Type:** boolean diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testsubnamespace-namespace/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testsubnamespace-namespace/index.md new file mode 100644 index 000000000000..55e0cbb15b66 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testsubnamespace-namespace/index.md @@ -0,0 +1,11 @@ +# TestSubNamespace + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestSubNamespace](./test-suite-a/testnamespace-namespace/testsubnamespace-namespace/) + +Test sub-namespace + +## Signature {#testsubnamespace-signature} + +```typescript +namespace TestSubNamespace +``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testtypealias-typealias/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testtypealias-typealias/index.md new file mode 100644 index 000000000000..6040f34e8a83 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testtypealias-typealias/index.md @@ -0,0 +1,11 @@ +# TestTypeAlias + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestTypeAlias](./test-suite-a/testnamespace-namespace/testtypealias-typealias/) + +Test Type-Alias + +## Signature {#testtypealias-signature} + +```typescript +type TestTypeAlias = boolean; +``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/typealias-typealias/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/typealias-typealias/index.md new file mode 100644 index 000000000000..f7d3a9bb916b --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/typealias-typealias/index.md @@ -0,0 +1,15 @@ +# TypeAlias + +[Packages](./) > [test-suite-a](./test-suite-a/) > [TypeAlias](./test-suite-a/typealias-typealias/) + +Test Type-Alias + +## Signature {#typealias-signature} + +```typescript +export type TypeAlias = string; +``` + +## Remarks {#typealias-remarks} + +Here are some remarks about the type alias diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/foo-interface/bar-propertysignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/foo-interface/bar-propertysignature.md new file mode 100644 index 000000000000..d5f9594c2ebe --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/foo-interface/bar-propertysignature.md @@ -0,0 +1,17 @@ +# bar + +[Packages](./) > [test-suite-b](./test-suite-b/) > [Foo](./test-suite-b/foo-interface/) > [bar](./test-suite-b/foo-interface/bar-propertysignature) + +Test Enum + +## Signature {#bar-signature} + +```typescript +bar: TestEnum; +``` + +**Type:** [TestEnum](./test-suite-a/testenum-enum/) + +## Remarks {#bar-remarks} + +Here are some remarks about the enum diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/foo-interface/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/foo-interface/index.md new file mode 100644 index 000000000000..9f9671ba3479 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/foo-interface/index.md @@ -0,0 +1,17 @@ +# Foo + +[Packages](./) > [test-suite-b](./test-suite-b/) > [Foo](./test-suite-b/foo-interface/) + +Bar + +## Signature {#foo-signature} + +```typescript +export interface Foo +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [bar](./test-suite-b/foo-interface/bar-propertysignature) | [TestEnum](./test-suite-a/testenum-enum/) | Test Enum | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/index.md new file mode 100644 index 000000000000..ad85c0991f22 --- /dev/null +++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/index.md @@ -0,0 +1,9 @@ +# test-suite-b + +[Packages](./) > [test-suite-b](./test-suite-b/) + +## Interfaces + +| Interface | Description | +| --- | --- | +| [Foo](./test-suite-b/foo-interface/) | Bar | From 5c7d60a0e394424a5f1604fc8a6f53ab06c84e1e Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Sat, 21 Dec 2024 00:27:02 +0000 Subject: [PATCH 29/54] refactor: More hierarchy options flexibility --- .../api-markdown-documenter.alpha.api.md | 11 +- .../api-markdown-documenter.beta.api.md | 11 +- .../api-markdown-documenter.public.api.md | 11 +- .../configuration/DocumentationSuite.ts | 7 +- .../configuration/Hierarchy.ts | 117 +++++++++++++++--- .../configuration/index.ts | 11 +- .../src/api-item-transforms/index.ts | 11 +- tools/api-markdown-documenter/src/index.ts | 1 + .../src/test/EndToEndTestUtilities.ts | 113 ++++++++--------- .../src/utilities/TypeUtilities.ts | 5 + 10 files changed, 203 insertions(+), 95 deletions(-) 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 a1e50a2ee7de..14225a4a3a36 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 @@ -322,7 +322,7 @@ export interface DocumentationSuiteConfiguration { // @public export type DocumentationSuiteOptions = Omit, "hierarchy"> & { - readonly hierarchy?: Partial; + readonly hierarchy?: HierarchyOptions; }; // @public @@ -492,6 +492,15 @@ export enum HierarchyKind { Section = "section" } +// @public +export type HierarchyOptions = { + [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyConfiguration; +} & { + [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; + [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; +}; + // @public export class HorizontalRuleNode implements MultiLineDocumentationNode { constructor(); 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 dfdb168b559d..79046da662ff 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 @@ -322,7 +322,7 @@ export interface DocumentationSuiteConfiguration { // @public export type DocumentationSuiteOptions = Omit, "hierarchy"> & { - readonly hierarchy?: Partial; + readonly hierarchy?: HierarchyOptions; }; // @public @@ -492,6 +492,15 @@ export enum HierarchyKind { Section = "section" } +// @public +export type HierarchyOptions = { + [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyConfiguration; +} & { + [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; + [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; +}; + // @public export class HorizontalRuleNode implements MultiLineDocumentationNode { constructor(); 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 6896d3438ead..e28c9f79f5a4 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 @@ -322,7 +322,7 @@ export interface DocumentationSuiteConfiguration { // @public export type DocumentationSuiteOptions = Omit, "hierarchy"> & { - readonly hierarchy?: Partial; + readonly hierarchy?: HierarchyOptions; }; // @public @@ -492,6 +492,15 @@ export enum HierarchyKind { Section = "section" } +// @public +export type HierarchyOptions = { + [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyConfiguration; +} & { + [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; + [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; +}; + // @public export class HorizontalRuleNode implements MultiLineDocumentationNode { constructor(); 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 345580ed72fb..01fe8ab7da93 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 @@ -20,9 +20,9 @@ import { } from "../../utilities/index.js"; import { - defaultHierarchyConfiguration, getHierarchyOptionsWithDefaults, type HierarchyConfiguration, + type HierarchyOptions, } from "./Hierarchy.js"; import { trimTrailingSemicolon } from "./Utilities.js"; @@ -143,7 +143,7 @@ export type DocumentationSuiteOptions = Omit< /** * {@inheritDoc DocumentationSuiteConfiguration.hierarchy} */ - readonly hierarchy?: Partial; + readonly hierarchy?: HierarchyOptions; }; /** @@ -227,8 +227,7 @@ export namespace DefaultDocumentationSuiteConfiguration { /** * Default {@link DocumentationSuiteConfiguration}. */ -const defaultDocumentationSuiteConfiguration: DocumentationSuiteConfiguration = { - hierarchy: defaultHierarchyConfiguration, +const defaultDocumentationSuiteConfiguration: Omit = { includeTopLevelDocumentHeading: true, includeBreadcrumb: true, getUriBaseOverrideForItem: diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts index 806cc46667d9..e0889e13b807 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts @@ -9,6 +9,7 @@ import { getSingleLineExcerptText, getApiItemKind, type ValidApiItemKind, + type Mutable, } from "../../utilities/index.js"; import { trimTrailingSemicolon } from "./Utilities.js"; @@ -162,10 +163,8 @@ export type DocumentationHierarchyConfiguration = * - CallSignature, ConstructSignature, IndexSignature: Uses a cleaned up variation on the type signature. * * - Model: Uses "API Overview". - * - * @privateRemarks Exported for testing purposes. */ -export function defaultHeadingText(apiItem: ApiItem): string { +function defaultHeadingText(apiItem: ApiItem): string { const kind = getApiItemKind(apiItem); switch (kind) { case ApiItemKind.Model: { @@ -188,7 +187,6 @@ export function defaultHeadingText(apiItem: ApiItem): string { /** * Default {@link SectionHierarchyConfiguration} used by the system. - * @privateRemarks Exported for testing purposes. */ export const defaultSectionHierarchyConfig: SectionHierarchyConfiguration = { kind: HierarchyKind.Section, @@ -202,14 +200,15 @@ export const defaultSectionHierarchyConfig: SectionHierarchyConfiguration = { * * - Model: "index" * - * @privateRemarks Exported for testing purposes. + * - Package: Use the unscoped package name. */ -export function defaultDocumentName(apiItem: ApiItem): string | undefined { +function defaultDocumentName(apiItem: ApiItem): string | undefined { const kind = getApiItemKind(apiItem); switch (kind) { case ApiItemKind.Model: { return "index"; } + // TODO: package handler default: { // Let the system generate a unique name that accounts for folder hierarchy. return undefined; @@ -219,7 +218,6 @@ export function defaultDocumentName(apiItem: ApiItem): string | undefined { /** * Default {@link DocumentHierarchyConfiguration} used by the system. - * @privateRemarks Exported for testing purposes. */ export const defaultDocumentHierarchyConfig: DocumentHierarchyConfiguration = { kind: HierarchyKind.Document, @@ -229,14 +227,12 @@ export const defaultDocumentHierarchyConfig: DocumentHierarchyConfiguration = { /** * Default {@link SectionHierarchyConfiguration} used by the system. - * - * @privateRemarks Exported for testing purposes. */ -export const defaultFolderName = undefined; +// TODO: package handler +const defaultFolderName = undefined; /** * Default {@link FolderHierarchyConfiguration} used by the system. - * @privateRemarks Exported for testing purposes. */ export const defaultFolderHierarchyConfig: FolderHierarchyConfiguration = { kind: HierarchyKind.Folder, @@ -248,7 +244,7 @@ export const defaultFolderHierarchyConfig: FolderHierarchyConfiguration = { }; /** - * Hierarchy options by API item kind. + * Complete hierarchy configuration by API item kind. * * @public */ @@ -295,10 +291,69 @@ export type HierarchyConfiguration = { [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; }; +/** + * Input hierarchy options by API item kind. + * + * @remarks + * For each option, you may provide 1 of 2 options: + * + * - {@link HierarchyKind}: the default configuration for that kind will be used. + * + * - A complete {@link DocumentationHierarchyConfiguration} to be used in place of any default. + * + * @public + */ +export type HierarchyOptions = { + /** + * Hierarchy configuration for the API item kind. + */ + [Kind in Exclude< + ValidApiItemKind, + ApiItemKind.Model | ApiItemKind.EntryPoint | ApiItemKind.Package + >]?: HierarchyKind | DocumentationHierarchyConfiguration; +} & { + /** + * Hierarchy configuration for the `Model` API item kind. + * + * @remarks + * Always its own document. Never introduces folder hierarchy. + * This is an important invariant, as it ensures that there is always at least one document in the output. + */ + [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + + /** + * Hierarchy configuration for the `Package` API item kind. + * + * @remarks Must be either a folder or document hierarchy configuration. + * + * @privateRemarks + * TODO: Allow all hierarchy configurations for packages. + * There isn't a real reason to restrict this, except the way the code is currently structured. + */ + [ApiItemKind.Package]?: + | HierarchyKind.Document + | HierarchyKind.Folder + | DocumentHierarchyConfiguration + | FolderHierarchyConfiguration; + + /** + * Hierarchy configuration for the `EntryPoint` API item kind. + * + * @remarks + * Always its own document, adjacent to the package document. + * When a package only has a single entrypoint, this is skipped entirely and entrypoint children are rendered directly to the package document. + * + * @privateRemarks + * TODO: Allow all hierarchy configurations for packages. + * There isn't a real reason to restrict this, except the way the code is currently structured. + */ + [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; +}; + /** * Default {@link HierarchyConfiguration}. */ -export const defaultHierarchyConfiguration: HierarchyConfiguration = { +const defaultHierarchyConfiguration: HierarchyConfiguration = { [ApiItemKind.Model]: { kind: HierarchyKind.Document, headingText: "API Overview", @@ -330,12 +385,44 @@ export const defaultHierarchyConfiguration: HierarchyConfiguration = { [ApiItemKind.Variable]: defaultSectionHierarchyConfig, }; +/** + * Maps an input option to a complete {@link DocumentationHierarchyConfiguration}. + */ +function getHierarchyConfiguration( + option: HierarchyKind | DocumentationHierarchyConfiguration, +): DocumentationHierarchyConfiguration { + switch (option) { + case HierarchyKind.Section: { + return defaultSectionHierarchyConfig; + } + case HierarchyKind.Document: { + return defaultDocumentHierarchyConfig; + } + case HierarchyKind.Folder: { + return defaultFolderHierarchyConfig; + } + default: { + return option; + } + } +} + /** * Gets a complete {@link HierarchyConfiguration} using the provided partial configuration, and filling * in the remainder with defaults. */ export function getHierarchyOptionsWithDefaults( - inputOptions?: Partial, + options?: HierarchyOptions, ): HierarchyConfiguration { - return { ...defaultHierarchyConfiguration, ...inputOptions }; + if (options === undefined) { + return defaultHierarchyConfiguration; + } + + const result: Mutable = { ...defaultHierarchyConfiguration }; + for (const [key, maybeValue] of Object.entries(options)) { + if (maybeValue !== undefined) { + result[key] = getHierarchyConfiguration(maybeValue); + } + } + return result; } diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts index 49b5554669b2..2842a6e459c2 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts @@ -16,13 +16,6 @@ export { getDocumentationSuiteConfigurationWithDefaults as getDocumentationSuiteOptionsWithDefaults, } from "./DocumentationSuite.js"; export { - defaultDocumentHierarchyConfig, - defaultDocumentName, - defaultFolderName, - defaultHeadingText, - defaultFolderHierarchyConfig, - defaultHierarchyConfiguration, - defaultSectionHierarchyConfig, type DocumentationHierarchyConfiguration, type DocumentationHierarchyConfigurationBase, type DocumentHierarchyConfiguration, @@ -30,7 +23,11 @@ export { FolderDocumentPlacement, type FolderHierarchyConfiguration, type FolderHierarchyProperties, + defaultDocumentHierarchyConfig, + defaultFolderHierarchyConfig, + defaultSectionHierarchyConfig, type HierarchyConfiguration, + type HierarchyOptions, HierarchyKind, type SectionHierarchyConfiguration, type SectionHierarchyProperties, diff --git a/tools/api-markdown-documenter/src/api-item-transforms/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/index.ts index b0f9d60d450a..061629189de1 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/index.ts @@ -21,13 +21,6 @@ export { type ApiItemTransformationOptions, type ApiItemTransformations, type DefaultDocumentationSuiteConfiguration, - defaultDocumentHierarchyConfig, - defaultDocumentName, - defaultFolderName, - defaultHeadingText, - defaultFolderHierarchyConfig, - defaultHierarchyConfiguration, - defaultSectionHierarchyConfig, type DocumentHierarchyConfiguration, type DocumentHierarchyProperties, type DocumentationSuiteConfiguration, @@ -36,10 +29,14 @@ export { type FolderHierarchyConfiguration, type FolderHierarchyProperties, getApiItemTransformationConfigurationWithDefaults, + defaultDocumentHierarchyConfig, + defaultFolderHierarchyConfig, + defaultSectionHierarchyConfig, type DocumentationHierarchyConfiguration, type DocumentationHierarchyConfigurationBase, HierarchyKind, type HierarchyConfiguration, + type HierarchyOptions, type SectionHierarchyConfiguration, type SectionHierarchyProperties, type TransformApiItemWithChildren, diff --git a/tools/api-markdown-documenter/src/index.ts b/tools/api-markdown-documenter/src/index.ts index c39c6ca69f91..32ef408af72f 100644 --- a/tools/api-markdown-documenter/src/index.ts +++ b/tools/api-markdown-documenter/src/index.ts @@ -32,6 +32,7 @@ export { type DocumentationHierarchyConfigurationBase, HierarchyKind, type HierarchyConfiguration, + type HierarchyOptions, type SectionHierarchyConfiguration, type SectionHierarchyProperties, type TransformApiItemWithChildren, diff --git a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts index 899424d1435d..095aa431d2f1 100644 --- a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts +++ b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts @@ -11,16 +11,11 @@ import { FileSystem } from "@rushstack/node-core-library"; import { expect } from "chai"; import { compare } from "dir-compare"; -import { - defaultSectionHierarchyConfig, - defaultHeadingText, - defaultDocumentHierarchyConfig, - defaultFolderName, -} from "../api-item-transforms/index.js"; +import { defaultFolderHierarchyConfig } from "../api-item-transforms/index.js"; import { FolderDocumentPlacement, HierarchyKind, - type HierarchyConfiguration, + type HierarchyOptions, type FolderHierarchyConfiguration, } from "../index.js"; @@ -53,73 +48,73 @@ export namespace HierarchyConfigs { const outsideFolderConfig: FolderHierarchyConfiguration = { kind: HierarchyKind.Folder, documentPlacement: FolderDocumentPlacement.Outside, - folderName: defaultFolderName, - headingText: (apiItem) => apiItem.displayName, + folderName: defaultFolderHierarchyConfig.folderName, + headingText: defaultFolderHierarchyConfig.headingText, }; const insideFolderConfig: FolderHierarchyConfiguration = { kind: HierarchyKind.Folder, documentPlacement: FolderDocumentPlacement.Inside, documentName: "index", - folderName: defaultFolderName, - headingText: defaultHeadingText, + folderName: defaultFolderHierarchyConfig.folderName, + headingText: defaultFolderHierarchyConfig.headingText, }; /** * "Flat" hierarchy: Packages get their own documents, and all descendent API items are rendered as sections under that document. * @remarks Results in a small number of documents, but can lead to relatively large documents. */ - export const flat: Partial = { - [ApiItemKind.Package]: defaultDocumentHierarchyConfig, - - [ApiItemKind.CallSignature]: defaultSectionHierarchyConfig, - [ApiItemKind.Class]: defaultSectionHierarchyConfig, - [ApiItemKind.Constructor]: defaultSectionHierarchyConfig, - [ApiItemKind.ConstructSignature]: defaultSectionHierarchyConfig, - [ApiItemKind.Enum]: defaultSectionHierarchyConfig, - [ApiItemKind.EnumMember]: defaultSectionHierarchyConfig, - [ApiItemKind.Function]: defaultSectionHierarchyConfig, - [ApiItemKind.IndexSignature]: defaultSectionHierarchyConfig, - [ApiItemKind.Interface]: defaultSectionHierarchyConfig, - [ApiItemKind.Method]: defaultSectionHierarchyConfig, - [ApiItemKind.MethodSignature]: defaultSectionHierarchyConfig, - [ApiItemKind.Namespace]: defaultSectionHierarchyConfig, - [ApiItemKind.Property]: defaultSectionHierarchyConfig, - [ApiItemKind.PropertySignature]: defaultSectionHierarchyConfig, - [ApiItemKind.TypeAlias]: defaultSectionHierarchyConfig, - [ApiItemKind.Variable]: defaultSectionHierarchyConfig, + export const flat: HierarchyOptions = { + [ApiItemKind.Package]: HierarchyKind.Document, + + [ApiItemKind.CallSignature]: HierarchyKind.Section, + [ApiItemKind.Class]: HierarchyKind.Section, + [ApiItemKind.Constructor]: HierarchyKind.Section, + [ApiItemKind.ConstructSignature]: HierarchyKind.Section, + [ApiItemKind.Enum]: HierarchyKind.Section, + [ApiItemKind.EnumMember]: HierarchyKind.Section, + [ApiItemKind.Function]: HierarchyKind.Section, + [ApiItemKind.IndexSignature]: HierarchyKind.Section, + [ApiItemKind.Interface]: HierarchyKind.Section, + [ApiItemKind.Method]: HierarchyKind.Section, + [ApiItemKind.MethodSignature]: HierarchyKind.Section, + [ApiItemKind.Namespace]: HierarchyKind.Section, + [ApiItemKind.Property]: HierarchyKind.Section, + [ApiItemKind.PropertySignature]: HierarchyKind.Section, + [ApiItemKind.TypeAlias]: HierarchyKind.Section, + [ApiItemKind.Variable]: HierarchyKind.Section, }; /** * "Sparse" hierarchy: Packages yield folder hierarchy, and all descendent items get their own document under that folder. * @remarks Leads to many documents, but each document is likely to be relatively small. */ - export const sparse: Partial = { + export const sparse: HierarchyOptions = { [ApiItemKind.Package]: outsideFolderConfig, - [ApiItemKind.CallSignature]: defaultDocumentHierarchyConfig, - [ApiItemKind.Class]: defaultDocumentHierarchyConfig, - [ApiItemKind.Constructor]: defaultDocumentHierarchyConfig, - [ApiItemKind.ConstructSignature]: defaultDocumentHierarchyConfig, - [ApiItemKind.Enum]: defaultDocumentHierarchyConfig, - [ApiItemKind.EnumMember]: defaultDocumentHierarchyConfig, - [ApiItemKind.Function]: defaultDocumentHierarchyConfig, - [ApiItemKind.IndexSignature]: defaultDocumentHierarchyConfig, - [ApiItemKind.Interface]: defaultDocumentHierarchyConfig, - [ApiItemKind.Method]: defaultDocumentHierarchyConfig, - [ApiItemKind.MethodSignature]: defaultDocumentHierarchyConfig, - [ApiItemKind.Namespace]: defaultDocumentHierarchyConfig, - [ApiItemKind.Property]: defaultDocumentHierarchyConfig, - [ApiItemKind.PropertySignature]: defaultDocumentHierarchyConfig, - [ApiItemKind.TypeAlias]: defaultDocumentHierarchyConfig, - [ApiItemKind.Variable]: defaultDocumentHierarchyConfig, + [ApiItemKind.CallSignature]: HierarchyKind.Document, + [ApiItemKind.Class]: HierarchyKind.Document, + [ApiItemKind.Constructor]: HierarchyKind.Document, + [ApiItemKind.ConstructSignature]: HierarchyKind.Document, + [ApiItemKind.Enum]: HierarchyKind.Document, + [ApiItemKind.EnumMember]: HierarchyKind.Document, + [ApiItemKind.Function]: HierarchyKind.Document, + [ApiItemKind.IndexSignature]: HierarchyKind.Document, + [ApiItemKind.Interface]: HierarchyKind.Document, + [ApiItemKind.Method]: HierarchyKind.Document, + [ApiItemKind.MethodSignature]: HierarchyKind.Document, + [ApiItemKind.Namespace]: HierarchyKind.Document, + [ApiItemKind.Property]: HierarchyKind.Document, + [ApiItemKind.PropertySignature]: HierarchyKind.Document, + [ApiItemKind.TypeAlias]: HierarchyKind.Document, + [ApiItemKind.Variable]: HierarchyKind.Document, }; /** * "Deep" hierarchy: All "parent" API items generate hierarchy. All other items are rendered as documents under their parent hierarchy. * @remarks Leads to many documents, but each document is likely to be relatively small. */ - export const deep: Partial = { + export const deep: HierarchyOptions = { // Items that introduce folder hierarchy: [ApiItemKind.Namespace]: insideFolderConfig, [ApiItemKind.Package]: insideFolderConfig, @@ -129,17 +124,17 @@ export namespace HierarchyConfigs { [ApiItemKind.TypeAlias]: insideFolderConfig, // Items that get their own document, but do not introduce folder hierarchy: - [ApiItemKind.CallSignature]: defaultDocumentHierarchyConfig, - [ApiItemKind.Constructor]: defaultDocumentHierarchyConfig, - [ApiItemKind.ConstructSignature]: defaultDocumentHierarchyConfig, - [ApiItemKind.EnumMember]: defaultDocumentHierarchyConfig, - [ApiItemKind.Function]: defaultDocumentHierarchyConfig, - [ApiItemKind.IndexSignature]: defaultDocumentHierarchyConfig, - [ApiItemKind.Method]: defaultDocumentHierarchyConfig, - [ApiItemKind.MethodSignature]: defaultDocumentHierarchyConfig, - [ApiItemKind.Property]: defaultDocumentHierarchyConfig, - [ApiItemKind.PropertySignature]: defaultDocumentHierarchyConfig, - [ApiItemKind.Variable]: defaultDocumentHierarchyConfig, + [ApiItemKind.CallSignature]: HierarchyKind.Document, + [ApiItemKind.Constructor]: HierarchyKind.Document, + [ApiItemKind.ConstructSignature]: HierarchyKind.Document, + [ApiItemKind.EnumMember]: HierarchyKind.Document, + [ApiItemKind.Function]: HierarchyKind.Document, + [ApiItemKind.IndexSignature]: HierarchyKind.Document, + [ApiItemKind.Method]: HierarchyKind.Document, + [ApiItemKind.MethodSignature]: HierarchyKind.Document, + [ApiItemKind.Property]: HierarchyKind.Document, + [ApiItemKind.PropertySignature]: HierarchyKind.Document, + [ApiItemKind.Variable]: HierarchyKind.Document, }; } diff --git a/tools/api-markdown-documenter/src/utilities/TypeUtilities.ts b/tools/api-markdown-documenter/src/utilities/TypeUtilities.ts index 65ec24bc4ed0..c6d3db8c28b7 100644 --- a/tools/api-markdown-documenter/src/utilities/TypeUtilities.ts +++ b/tools/api-markdown-documenter/src/utilities/TypeUtilities.ts @@ -3,6 +3,11 @@ * Licensed under the MIT License. */ +/** + * Type that removes `readonly` from fields. + */ +export type Mutable = { -readonly [P in keyof T]: T[P] }; + /** * Represents a value that can be either a direct value of type `T` or a function that returns a value of type `T` given some parameters. */ From 21b1ea941324c97c21e2983317020afe7540fb29 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Sat, 21 Dec 2024 00:40:48 +0000 Subject: [PATCH 30/54] refactor: Simplify --- .../api-markdown-documenter.alpha.api.md | 12 ++-- .../api-markdown-documenter.beta.api.md | 12 ++-- .../api-markdown-documenter.public.api.md | 12 ++-- .../ApiItemTransformUtilities.ts | 11 +--- .../src/api-item-transforms/Utilities.ts | 6 +- .../configuration/DocumentationSuite.ts | 42 ++++++++++++ .../configuration/Hierarchy.ts | 64 ++----------------- .../configuration/index.ts | 1 - .../src/api-item-transforms/index.ts | 1 - tools/api-markdown-documenter/src/index.ts | 1 - .../src/test/EndToEndTestUtilities.ts | 2 - 11 files changed, 62 insertions(+), 102 deletions(-) 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 14225a4a3a36..239db9bced06 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 @@ -213,6 +213,7 @@ export const defaultConsoleLogger: Logger; // @public export namespace DefaultDocumentationSuiteConfiguration { export function defaultGetAlertsForItem(apiItem: ApiItem): string[]; + export function defaultGetHeadingTextForItem(apiItem: ApiItem): string; export function defaultGetLinkTextForItem(apiItem: ApiItem): string; export function defaultGetUriBaseOverrideForItem(): string | undefined; export function defaultSkipPackage(): boolean; @@ -311,6 +312,7 @@ export abstract class DocumentationParentNodeBase string[]; + readonly getHeadingTextForItem: (apiItem: ApiItem) => string; readonly getLinkTextForItem: (apiItem: ApiItem) => string; readonly getUriBaseOverrideForItem: (apiItem: ApiItem) => string | undefined; readonly hierarchy: HierarchyConfiguration; @@ -330,7 +332,7 @@ export interface DocumentHierarchyConfiguration extends DocumentationHierarchyCo } // @public -export interface DocumentHierarchyProperties extends SectionHierarchyProperties { +export interface DocumentHierarchyProperties { readonly documentName?: string | undefined | ((apiItem: ApiItem) => string | undefined); } @@ -750,13 +752,7 @@ function renderNode(node: DocumentationNode, writer: DocumentWriter, context: Ma function renderNodes(children: DocumentationNode[], writer: DocumentWriter, childContext: MarkdownRenderContext): void; // @public -export interface SectionHierarchyConfiguration extends DocumentationHierarchyConfigurationBase, SectionHierarchyProperties { -} - -// @public -export interface SectionHierarchyProperties { - readonly headingText: string | ((apiItem: ApiItem) => string); -} +export type SectionHierarchyConfiguration = DocumentationHierarchyConfigurationBase; // @public export class SectionNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { 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 79046da662ff..da53e8b61adb 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 @@ -213,6 +213,7 @@ export const defaultConsoleLogger: Logger; // @public export namespace DefaultDocumentationSuiteConfiguration { export function defaultGetAlertsForItem(apiItem: ApiItem): string[]; + export function defaultGetHeadingTextForItem(apiItem: ApiItem): string; export function defaultGetLinkTextForItem(apiItem: ApiItem): string; export function defaultGetUriBaseOverrideForItem(): string | undefined; export function defaultSkipPackage(): boolean; @@ -311,6 +312,7 @@ export abstract class DocumentationParentNodeBase string[]; + readonly getHeadingTextForItem: (apiItem: ApiItem) => string; readonly getLinkTextForItem: (apiItem: ApiItem) => string; readonly getUriBaseOverrideForItem: (apiItem: ApiItem) => string | undefined; readonly hierarchy: HierarchyConfiguration; @@ -330,7 +332,7 @@ export interface DocumentHierarchyConfiguration extends DocumentationHierarchyCo } // @public -export interface DocumentHierarchyProperties extends SectionHierarchyProperties { +export interface DocumentHierarchyProperties { readonly documentName?: string | undefined | ((apiItem: ApiItem) => string | undefined); } @@ -736,13 +738,7 @@ function renderNode(node: DocumentationNode, writer: DocumentWriter, context: Ma function renderNodes(children: DocumentationNode[], writer: DocumentWriter, childContext: MarkdownRenderContext): void; // @public -export interface SectionHierarchyConfiguration extends DocumentationHierarchyConfigurationBase, SectionHierarchyProperties { -} - -// @public -export interface SectionHierarchyProperties { - readonly headingText: string | ((apiItem: ApiItem) => string); -} +export type SectionHierarchyConfiguration = DocumentationHierarchyConfigurationBase; // @public export class SectionNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { 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 e28c9f79f5a4..0db41570440f 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 @@ -213,6 +213,7 @@ export const defaultConsoleLogger: Logger; // @public export namespace DefaultDocumentationSuiteConfiguration { export function defaultGetAlertsForItem(apiItem: ApiItem): string[]; + export function defaultGetHeadingTextForItem(apiItem: ApiItem): string; export function defaultGetLinkTextForItem(apiItem: ApiItem): string; export function defaultGetUriBaseOverrideForItem(): string | undefined; export function defaultSkipPackage(): boolean; @@ -311,6 +312,7 @@ export abstract class DocumentationParentNodeBase string[]; + readonly getHeadingTextForItem: (apiItem: ApiItem) => string; readonly getLinkTextForItem: (apiItem: ApiItem) => string; readonly getUriBaseOverrideForItem: (apiItem: ApiItem) => string | undefined; readonly hierarchy: HierarchyConfiguration; @@ -330,7 +332,7 @@ export interface DocumentHierarchyConfiguration extends DocumentationHierarchyCo } // @public -export interface DocumentHierarchyProperties extends SectionHierarchyProperties { +export interface DocumentHierarchyProperties { readonly documentName?: string | undefined | ((apiItem: ApiItem) => string | undefined); } @@ -714,13 +716,7 @@ function renderNode(node: DocumentationNode, writer: DocumentWriter, context: Ma function renderNodes(children: DocumentationNode[], writer: DocumentWriter, childContext: MarkdownRenderContext): void; // @public -export interface SectionHierarchyConfiguration extends DocumentationHierarchyConfigurationBase, SectionHierarchyProperties { -} - -// @public -export interface SectionHierarchyProperties { - readonly headingText: string | ((apiItem: ApiItem) => string); -} +export type SectionHierarchyConfiguration = DocumentationHierarchyConfigurationBase; // @public export class SectionNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { 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 c1b192799d0d..17f0a1aef4da 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts @@ -292,7 +292,7 @@ export function getHeadingForApiItem( const id = doesItemRequireOwnDocument(apiItem, config.hierarchy) ? undefined : getHeadingIdForApiItem(apiItem, config); - const title = getHeadingTextForApiItem(apiItem, config); + const title = config.getHeadingTextForItem(apiItem); return { title, @@ -301,15 +301,6 @@ export function getHeadingForApiItem( }; } -function getHeadingTextForApiItem( - apiItem: ApiItem, - config: ApiItemTransformationConfiguration, -): string { - const itemKind = getApiItemKind(apiItem); - const hierarchy = config.hierarchy[itemKind]; - return getValueOrDerived(hierarchy.headingText, apiItem); -} - // TODO: this doesn't actually return `undefined` for own document. Verify and fix. /** * Generates a heading ID for the provided API item. diff --git a/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts b/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts index 94d7f112c7e0..c455eecc7aae 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts @@ -8,7 +8,7 @@ import type { DocDeclarationReference } from "@microsoft/tsdoc"; import type { Link } from "../Link.js"; import { DocumentNode, type SectionNode } from "../documentation-domain/index.js"; -import { getApiItemKind, getValueOrDerived, resolveSymbolicReference } from "../utilities/index.js"; +import { resolveSymbolicReference } from "../utilities/index.js"; import { getDocumentPathForApiItem, @@ -33,9 +33,7 @@ export function createDocument( sections: SectionNode[], config: ApiItemTransformationConfiguration, ): DocumentNode { - const documentItemKind = getApiItemKind(documentItem); - const documentHierarchy = config.hierarchy[documentItemKind]; - const title = getValueOrDerived(documentHierarchy.headingText, documentItem); + const title = config.getHeadingTextForItem(documentItem); // Wrap sections in a root section if top-level heading is requested. const contents = config.includeTopLevelDocumentHeading 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 01fe8ab7da93..a52ec48643e6 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 @@ -72,6 +72,17 @@ export interface DocumentationSuiteConfiguration { */ readonly getUriBaseOverrideForItem: (apiItem: ApiItem) => string | undefined; + /** + * Generate heading text for the provided `ApiItem`. + * + * @param apiItem - The API item for which the heading is being generated. + * + * @returns The heading title for the API item. + * + * @defaultValue {@link DefaultDocumentationSuiteConfiguration.defaultGetHeadingTextForItem} + */ + readonly getHeadingTextForItem: (apiItem: ApiItem) => string; + /** * Generate link text for the provided `ApiItem`. * @@ -162,6 +173,36 @@ export namespace DefaultDocumentationSuiteConfiguration { return undefined; } + /** + * Default {@link DocumentationSuiteConfiguration.getHeadingTextForItem}. + * + * Uses the item's qualified API name, but is handled differently for the following items: + * + * - CallSignature, ConstructSignature, IndexSignature: Uses a cleaned up variation on the type signature. + * + * - Model: Uses "API Overview". + */ + export function defaultGetHeadingTextForItem(apiItem: ApiItem): string { + const kind = getApiItemKind(apiItem); + switch (kind) { + case ApiItemKind.Model: { + return "API Overview"; + } + case ApiItemKind.CallSignature: + case ApiItemKind.ConstructSignature: + case ApiItemKind.IndexSignature: { + // For signature items, the display-name is not particularly useful information + // ("(constructor)", "(call)", etc.). + // Instead, we will use a cleaned up variation on the type signature. + const excerpt = getSingleLineExcerptText((apiItem as ApiDeclaredItem).excerpt); + return trimTrailingSemicolon(excerpt); + } + default: { + return apiItem.displayName; + } + } + } + /** * Default {@link DocumentationSuiteConfiguration.getLinkTextForItem}. * @@ -232,6 +273,7 @@ const defaultDocumentationSuiteConfiguration: Omit string); -} - /** * The corresponding API item will be placed in a section under the document representing an ancestor of the API item. * * @public */ -export interface SectionHierarchyConfiguration - extends DocumentationHierarchyConfigurationBase, - SectionHierarchyProperties {} +export type SectionHierarchyConfiguration = + DocumentationHierarchyConfigurationBase; /** * {@link HierarchyKind.Document} hierarchy configuration properties. * * @public */ -export interface DocumentHierarchyProperties extends SectionHierarchyProperties { +export interface DocumentHierarchyProperties { /** * Document name to use for the API item. * @remarks `undefined` indicates that the system default should be used. @@ -155,42 +135,11 @@ export type DocumentationHierarchyConfiguration = | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; -/** - * Default {@link SectionHierarchyProperties.headingText}. - * - * Uses the item's qualified API name, but is handled differently for the following items: - * - * - CallSignature, ConstructSignature, IndexSignature: Uses a cleaned up variation on the type signature. - * - * - Model: Uses "API Overview". - */ -function defaultHeadingText(apiItem: ApiItem): string { - const kind = getApiItemKind(apiItem); - switch (kind) { - case ApiItemKind.Model: { - return "API Overview"; - } - case ApiItemKind.CallSignature: - case ApiItemKind.ConstructSignature: - case ApiItemKind.IndexSignature: { - // For signature items, the display-name is not particularly useful information - // ("(constructor)", "(call)", etc.). - // Instead, we will use a cleaned up variation on the type signature. - const excerpt = getSingleLineExcerptText((apiItem as ApiDeclaredItem).excerpt); - return trimTrailingSemicolon(excerpt); - } - default: { - return apiItem.displayName; - } - } -} - /** * Default {@link SectionHierarchyConfiguration} used by the system. */ export const defaultSectionHierarchyConfig: SectionHierarchyConfiguration = { kind: HierarchyKind.Section, - headingText: defaultHeadingText, }; /** @@ -221,7 +170,6 @@ function defaultDocumentName(apiItem: ApiItem): string | undefined { */ export const defaultDocumentHierarchyConfig: DocumentHierarchyConfiguration = { kind: HierarchyKind.Document, - headingText: defaultHeadingText, documentName: defaultDocumentName, }; @@ -236,7 +184,6 @@ const defaultFolderName = undefined; */ export const defaultFolderHierarchyConfig: FolderHierarchyConfiguration = { kind: HierarchyKind.Folder, - headingText: defaultHeadingText, documentName: defaultDocumentName, documentPlacement: FolderDocumentPlacement.Outside, // TODO // documentName: "index", // Documents for items that get their own folder are always named "index" by default. @@ -356,7 +303,6 @@ export type HierarchyOptions = { const defaultHierarchyConfiguration: HierarchyConfiguration = { [ApiItemKind.Model]: { kind: HierarchyKind.Document, - headingText: "API Overview", documentName: "index", }, diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts index 2842a6e459c2..908eda9902f7 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts @@ -30,7 +30,6 @@ export { type HierarchyOptions, HierarchyKind, type SectionHierarchyConfiguration, - type SectionHierarchyProperties, } from "./Hierarchy.js"; export { type ApiItemTransformations, diff --git a/tools/api-markdown-documenter/src/api-item-transforms/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/index.ts index 061629189de1..f455ef0cfec9 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/index.ts @@ -38,7 +38,6 @@ export { type HierarchyConfiguration, type HierarchyOptions, type SectionHierarchyConfiguration, - type SectionHierarchyProperties, type TransformApiItemWithChildren, type TransformApiItemWithoutChildren, } from "./configuration/index.js"; diff --git a/tools/api-markdown-documenter/src/index.ts b/tools/api-markdown-documenter/src/index.ts index 32ef408af72f..2e6fd38cc746 100644 --- a/tools/api-markdown-documenter/src/index.ts +++ b/tools/api-markdown-documenter/src/index.ts @@ -34,7 +34,6 @@ export { type HierarchyConfiguration, type HierarchyOptions, type SectionHierarchyConfiguration, - type SectionHierarchyProperties, type TransformApiItemWithChildren, type TransformApiItemWithoutChildren, transformApiModel, diff --git a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts index 095aa431d2f1..0238b87c77ed 100644 --- a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts +++ b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts @@ -49,7 +49,6 @@ export namespace HierarchyConfigs { kind: HierarchyKind.Folder, documentPlacement: FolderDocumentPlacement.Outside, folderName: defaultFolderHierarchyConfig.folderName, - headingText: defaultFolderHierarchyConfig.headingText, }; const insideFolderConfig: FolderHierarchyConfiguration = { @@ -57,7 +56,6 @@ export namespace HierarchyConfigs { documentPlacement: FolderDocumentPlacement.Inside, documentName: "index", folderName: defaultFolderHierarchyConfig.folderName, - headingText: defaultFolderHierarchyConfig.headingText, }; /** From 03812584fde4e88d946654438e6f39f81604a58e Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Sat, 21 Dec 2024 01:35:25 +0000 Subject: [PATCH 31/54] refactor: More simplifying --- .../configuration/Hierarchy.ts | 40 +++++++++++++++---- 1 file changed, 32 insertions(+), 8 deletions(-) diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts index dd5690a8534d..1d4052eaea41 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts @@ -3,9 +3,15 @@ * Licensed under the MIT License. */ -import { type ApiItem, ApiItemKind } from "@microsoft/api-extractor-model"; +import { type ApiItem, ApiItemKind, type ApiPackage } from "@microsoft/api-extractor-model"; -import { getApiItemKind, type ValidApiItemKind, type Mutable } from "../../utilities/index.js"; +import { + getApiItemKind, + type ValidApiItemKind, + type Mutable, + getFileSafeNameForApiItemName, + getUnscopedPackageName, +} from "../../utilities/index.js"; /** * Kind of documentation suite hierarchy. @@ -145,6 +151,7 @@ export const defaultSectionHierarchyConfig: SectionHierarchyConfiguration = { /** * Default {@link DocumentHierarchyProperties.documentName} for non-folder hierarchy documents. * + * @remarks * Uses the item's scoped and qualified API name, but is handled differently for the following items: * * - Model: "index" @@ -157,7 +164,9 @@ function defaultDocumentName(apiItem: ApiItem): string | undefined { case ApiItemKind.Model: { return "index"; } - // TODO: package handler + case ApiItemKind.Package: { + return getFileSafeNameForApiItemName(getUnscopedPackageName(apiItem as ApiPackage)); + } default: { // Let the system generate a unique name that accounts for folder hierarchy. return undefined; @@ -174,10 +183,25 @@ export const defaultDocumentHierarchyConfig: DocumentHierarchyConfiguration = { }; /** - * Default {@link SectionHierarchyConfiguration} used by the system. + * Default {@link DocumentHierarchyProperties.documentName} for non-folder hierarchy documents. + * + * @remarks + * Uses the item's scoped and qualified API name, but is handled differently for the following items: + * + * - Package: Use the unscoped package name. */ -// TODO: package handler -const defaultFolderName = undefined; +function defaultFolderName(apiItem: ApiItem): string | undefined { + const kind = getApiItemKind(apiItem); + switch (kind) { + case ApiItemKind.Package: { + return getFileSafeNameForApiItemName(getUnscopedPackageName(apiItem as ApiPackage)); + } + default: { + // Let the system generate a unique name that accounts for folder hierarchy. + return undefined; + } + } +} /** * Default {@link FolderHierarchyConfiguration} used by the system. @@ -334,7 +358,7 @@ const defaultHierarchyConfiguration: HierarchyConfiguration = { /** * Maps an input option to a complete {@link DocumentationHierarchyConfiguration}. */ -function getHierarchyConfiguration( +function mapHierarchyOption( option: HierarchyKind | DocumentationHierarchyConfiguration, ): DocumentationHierarchyConfiguration { switch (option) { @@ -367,7 +391,7 @@ export function getHierarchyOptionsWithDefaults( const result: Mutable = { ...defaultHierarchyConfiguration }; for (const [key, maybeValue] of Object.entries(options)) { if (maybeValue !== undefined) { - result[key] = getHierarchyConfiguration(maybeValue); + result[key] = mapHierarchyOption(maybeValue); } } return result; From f711e86363fcbb0c2601864987fc6a65466d1fb2 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Mon, 6 Jan 2025 22:41:01 +0000 Subject: [PATCH 32/54] refactor: Give more hierarchy config flexibility --- .../api-markdown-documenter.alpha.api.md | 38 ++++--- .../api-markdown-documenter.beta.api.md | 38 ++++--- .../api-markdown-documenter.public.api.md | 38 ++++--- .../ApiItemTransformUtilities.ts | 19 ++-- .../configuration/Hierarchy.ts | 104 +++++++++++++----- .../configuration/index.ts | 7 +- .../src/api-item-transforms/index.ts | 7 +- tools/api-markdown-documenter/src/index.ts | 12 +- .../src/test/EndToEndTestUtilities.ts | 25 ++--- .../src/test/HtmlEndToEnd.test.ts | 8 +- .../src/test/MarkdownEndToEnd.test.ts | 8 +- .../test/TransformApiModelEndToEnd.test.ts | 6 +- 12 files changed, 197 insertions(+), 113 deletions(-) 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 fcfd3d56e58d..25cc475d323c 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 @@ -219,7 +219,7 @@ export namespace DefaultDocumentationSuiteConfiguration { export function defaultSkipPackage(): boolean; } -// @public +// @public @sealed export type DocumentationHierarchyConfiguration = SectionHierarchyConfiguration | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; // @public @@ -227,6 +227,9 @@ export interface DocumentationHierarchyConfigurationBase extends Literal, DocumentationNode { readonly isLiteral: true; @@ -328,12 +331,14 @@ export type DocumentationSuiteOptions = Omit, DocumentHierarchyProperties { -} +export type DocumentHierarchyConfiguration = DocumentationHierarchyConfigurationBase & DocumentHierarchyProperties; + +// @public +export type DocumentHierarchyOptions = DocumentationHierarchyConfigurationBase & Partial; // @public export interface DocumentHierarchyProperties { - readonly documentName?: string | undefined | ((apiItem: ApiItem) => string | undefined); + readonly documentName: string | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string); } // @public @@ -400,14 +405,16 @@ export enum FolderDocumentPlacement { Outside = "outside" } -// @public -export interface FolderHierarchyConfiguration extends DocumentationHierarchyConfigurationBase, FolderHierarchyProperties { -} +// @public @sealed +export type FolderHierarchyConfiguration = DocumentationHierarchyConfigurationBase & FolderHierarchyProperties; -// @public +// @public @sealed +export type FolderHierarchyOptions = DocumentationHierarchyConfigurationBase & Partial; + +// @public @sealed export interface FolderHierarchyProperties extends DocumentHierarchyProperties { - readonly documentPlacement: FolderDocumentPlacement | ((apiItem: ApiItem) => FolderDocumentPlacement); - readonly folderName: string | undefined | ((apiItem: ApiItem) => string | undefined); + readonly documentPlacement: FolderDocumentPlacement; + readonly folderName: string | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string); } // @public @@ -496,11 +503,11 @@ export enum HierarchyKind { // @public export type HierarchyOptions = { - [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyConfiguration; + [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyOptions; } & { - [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; - [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; - [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyOptions; + [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyOptions | FolderHierarchyOptions; + [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyOptions; }; // @public @@ -754,6 +761,9 @@ function renderNodes(children: DocumentationNode[], writer: DocumentWriter, chil // @public export type SectionHierarchyConfiguration = DocumentationHierarchyConfigurationBase; +// @public +export type SectionHierarchyOptions = DocumentationHierarchyConfigurationBase; + // @public export class SectionNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { constructor(children: DocumentationNode[], heading?: HeadingNode); 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 f33b0167f424..999c00ee48f2 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 @@ -219,7 +219,7 @@ export namespace DefaultDocumentationSuiteConfiguration { export function defaultSkipPackage(): boolean; } -// @public +// @public @sealed export type DocumentationHierarchyConfiguration = SectionHierarchyConfiguration | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; // @public @@ -227,6 +227,9 @@ export interface DocumentationHierarchyConfigurationBase extends Literal, DocumentationNode { readonly isLiteral: true; @@ -328,12 +331,14 @@ export type DocumentationSuiteOptions = Omit, DocumentHierarchyProperties { -} +export type DocumentHierarchyConfiguration = DocumentationHierarchyConfigurationBase & DocumentHierarchyProperties; + +// @public +export type DocumentHierarchyOptions = DocumentationHierarchyConfigurationBase & Partial; // @public export interface DocumentHierarchyProperties { - readonly documentName?: string | undefined | ((apiItem: ApiItem) => string | undefined); + readonly documentName: string | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string); } // @public @@ -400,14 +405,16 @@ export enum FolderDocumentPlacement { Outside = "outside" } -// @public -export interface FolderHierarchyConfiguration extends DocumentationHierarchyConfigurationBase, FolderHierarchyProperties { -} +// @public @sealed +export type FolderHierarchyConfiguration = DocumentationHierarchyConfigurationBase & FolderHierarchyProperties; -// @public +// @public @sealed +export type FolderHierarchyOptions = DocumentationHierarchyConfigurationBase & Partial; + +// @public @sealed export interface FolderHierarchyProperties extends DocumentHierarchyProperties { - readonly documentPlacement: FolderDocumentPlacement | ((apiItem: ApiItem) => FolderDocumentPlacement); - readonly folderName: string | undefined | ((apiItem: ApiItem) => string | undefined); + readonly documentPlacement: FolderDocumentPlacement; + readonly folderName: string | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string); } // @public @@ -496,11 +503,11 @@ export enum HierarchyKind { // @public export type HierarchyOptions = { - [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyConfiguration; + [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyOptions; } & { - [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; - [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; - [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyOptions; + [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyOptions | FolderHierarchyOptions; + [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyOptions; }; // @public @@ -740,6 +747,9 @@ function renderNodes(children: DocumentationNode[], writer: DocumentWriter, chil // @public export type SectionHierarchyConfiguration = DocumentationHierarchyConfigurationBase; +// @public +export type SectionHierarchyOptions = DocumentationHierarchyConfigurationBase; + // @public export class SectionNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { constructor(children: DocumentationNode[], heading?: HeadingNode); 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 adbadf58a979..68879768a45f 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 @@ -219,7 +219,7 @@ export namespace DefaultDocumentationSuiteConfiguration { export function defaultSkipPackage(): boolean; } -// @public +// @public @sealed export type DocumentationHierarchyConfiguration = SectionHierarchyConfiguration | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; // @public @@ -227,6 +227,9 @@ export interface DocumentationHierarchyConfigurationBase extends Literal, DocumentationNode { readonly isLiteral: true; @@ -328,12 +331,14 @@ export type DocumentationSuiteOptions = Omit, DocumentHierarchyProperties { -} +export type DocumentHierarchyConfiguration = DocumentationHierarchyConfigurationBase & DocumentHierarchyProperties; + +// @public +export type DocumentHierarchyOptions = DocumentationHierarchyConfigurationBase & Partial; // @public export interface DocumentHierarchyProperties { - readonly documentName?: string | undefined | ((apiItem: ApiItem) => string | undefined); + readonly documentName: string | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string); } // @public @@ -400,14 +405,16 @@ export enum FolderDocumentPlacement { Outside = "outside" } -// @public -export interface FolderHierarchyConfiguration extends DocumentationHierarchyConfigurationBase, FolderHierarchyProperties { -} +// @public @sealed +export type FolderHierarchyConfiguration = DocumentationHierarchyConfigurationBase & FolderHierarchyProperties; -// @public +// @public @sealed +export type FolderHierarchyOptions = DocumentationHierarchyConfigurationBase & Partial; + +// @public @sealed export interface FolderHierarchyProperties extends DocumentHierarchyProperties { - readonly documentPlacement: FolderDocumentPlacement | ((apiItem: ApiItem) => FolderDocumentPlacement); - readonly folderName: string | undefined | ((apiItem: ApiItem) => string | undefined); + readonly documentPlacement: FolderDocumentPlacement; + readonly folderName: string | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string); } // @public @@ -496,11 +503,11 @@ export enum HierarchyKind { // @public export type HierarchyOptions = { - [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyConfiguration; + [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyOptions; } & { - [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; - [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; - [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyOptions; + [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyOptions | FolderHierarchyOptions; + [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyOptions; }; // @public @@ -718,6 +725,9 @@ function renderNodes(children: DocumentationNode[], writer: DocumentWriter, chil // @public export type SectionHierarchyConfiguration = DocumentationHierarchyConfigurationBase; +// @public +export type SectionHierarchyOptions = DocumentationHierarchyConfigurationBase; + // @public export class SectionNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { constructor(children: DocumentationNode[], heading?: HeadingNode); 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 d9a68844b5fa..c962e88747f2 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts @@ -224,24 +224,23 @@ function getDocumentNameForItem( item: ApiItemWithHierarchy, hierarchyConfig: HierarchyConfiguration, ): string { - return ( - getValueOrDerived(item.hierarchy.documentName, item.apiItem) ?? - createQualifiedDocumentNameForApiItem(item.apiItem, hierarchyConfig) - ); + return getValueOrDerived(item.hierarchy.documentName, item.apiItem, hierarchyConfig); } function getFolderNameForItem( item: ApiItemWithHierarchy, hierarchyConfig: HierarchyConfiguration, ): string { - return ( - getValueOrDerived(item.hierarchy.folderName, item.apiItem) ?? - // If no folder name is configured, use the system-default document name - createQualifiedDocumentNameForApiItem(item.apiItem, hierarchyConfig) - ); + return getValueOrDerived(item.hierarchy.folderName, item.apiItem, hierarchyConfig); } -function createQualifiedDocumentNameForApiItem( +/** + * Generates a qualified document name for the specified API item aimed at preventing name collisions, accounting for folder hierarchy. + * + * @param apiItem - The API item for which we are generating a qualified name + * @param hierarchyConfig - See {@link HierarchyConfiguration}. + */ +export function createQualifiedDocumentNameForApiItem( apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration, ): string { diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts index 1d4052eaea41..691dd150ecec 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts @@ -12,6 +12,7 @@ import { getFileSafeNameForApiItemName, getUnscopedPackageName, } from "../../utilities/index.js"; +import { createQualifiedDocumentNameForApiItem } from "../ApiItemTransformUtilities.js"; /** * Kind of documentation suite hierarchy. @@ -59,6 +60,14 @@ export interface DocumentationHierarchyConfigurationBase; +/** + * {@inheritDoc SectionHierarchyConfiguration} + * + * @public + */ +export type SectionHierarchyOptions = + DocumentationHierarchyConfigurationBase; + /** * {@link HierarchyKind.Document} hierarchy configuration properties. * @@ -69,7 +78,9 @@ export interface DocumentHierarchyProperties { * Document name to use for the API item. * @remarks `undefined` indicates that the system default should be used. */ - readonly documentName?: string | undefined | ((apiItem: ApiItem) => string | undefined); + readonly documentName: + | string + | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string); } /** @@ -77,9 +88,17 @@ export interface DocumentHierarchyProperties { * * @public */ -export interface DocumentHierarchyConfiguration - extends DocumentationHierarchyConfigurationBase, - DocumentHierarchyProperties {} +export type DocumentHierarchyConfiguration = + DocumentationHierarchyConfigurationBase & DocumentHierarchyProperties; + +/** + * {@inheritDoc DocumentHierarchyConfiguration} + * + * @public + */ +export type DocumentHierarchyOptions = + DocumentationHierarchyConfigurationBase & + Partial; /** * Placement of the API item's document relative to its generated folder. @@ -101,39 +120,48 @@ export enum FolderDocumentPlacement { } /** - * {@link HierarchyKind.Document} hierarchy configuration properties. + * {@link HierarchyKind.Folder} hierarchy configuration properties. * + * @sealed * @public */ export interface FolderHierarchyProperties extends DocumentHierarchyProperties { /** * Placement of the API item's document relative to its generated folder. - * `inside`: The document is placed inside its folder. - * `outside`: The document is placed outside (adjacent to) its folder. */ - readonly documentPlacement: - | FolderDocumentPlacement - | ((apiItem: ApiItem) => FolderDocumentPlacement); + readonly documentPlacement: FolderDocumentPlacement; /** * Folder name to use for the API item. * @remarks `undefined` indicates that the system default should be used. */ - readonly folderName: string | undefined | ((apiItem: ApiItem) => string | undefined); + readonly folderName: + | string + | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string); } /** * The corresponding API item will get its own document, in the folder for an ancestor of the API item. * + * @sealed * @public */ -export interface FolderHierarchyConfiguration - extends DocumentationHierarchyConfigurationBase, - FolderHierarchyProperties {} +export type FolderHierarchyConfiguration = + DocumentationHierarchyConfigurationBase & FolderHierarchyProperties; + +/** + * {@inheritDoc FolderHierarchyConfiguration} + * + * @sealed + * @public + */ +export type FolderHierarchyOptions = DocumentationHierarchyConfigurationBase & + Partial; /** * API item hierarchy configuration. * + * @sealed * @public */ export type DocumentationHierarchyConfiguration = @@ -141,6 +169,17 @@ export type DocumentationHierarchyConfiguration = | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; +/** + * API item hierarchy configuration. + * + * @sealed + * @public + */ +export type DocumentationHierarchyOptions = + | SectionHierarchyOptions + | DocumentHierarchyOptions + | FolderHierarchyOptions; + /** * Default {@link SectionHierarchyConfiguration} used by the system. */ @@ -158,7 +197,7 @@ export const defaultSectionHierarchyConfig: SectionHierarchyConfiguration = { * * - Package: Use the unscoped package name. */ -function defaultDocumentName(apiItem: ApiItem): string | undefined { +function defaultDocumentName(apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration): string { const kind = getApiItemKind(apiItem); switch (kind) { case ApiItemKind.Model: { @@ -168,8 +207,7 @@ function defaultDocumentName(apiItem: ApiItem): string | undefined { return getFileSafeNameForApiItemName(getUnscopedPackageName(apiItem as ApiPackage)); } default: { - // Let the system generate a unique name that accounts for folder hierarchy. - return undefined; + return createQualifiedDocumentNameForApiItem(apiItem, hierarchyConfig); } } } @@ -190,7 +228,7 @@ export const defaultDocumentHierarchyConfig: DocumentHierarchyConfiguration = { * * - Package: Use the unscoped package name. */ -function defaultFolderName(apiItem: ApiItem): string | undefined { +function defaultFolderName(apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration): string { const kind = getApiItemKind(apiItem); switch (kind) { case ApiItemKind.Package: { @@ -198,7 +236,7 @@ function defaultFolderName(apiItem: ApiItem): string | undefined { } default: { // Let the system generate a unique name that accounts for folder hierarchy. - return undefined; + return createQualifiedDocumentNameForApiItem(apiItem, hierarchyConfig); } } } @@ -281,7 +319,7 @@ export type HierarchyOptions = { [Kind in Exclude< ValidApiItemKind, ApiItemKind.Model | ApiItemKind.EntryPoint | ApiItemKind.Package - >]?: HierarchyKind | DocumentationHierarchyConfiguration; + >]?: HierarchyKind | DocumentationHierarchyOptions; } & { /** * Hierarchy configuration for the `Model` API item kind. @@ -290,7 +328,7 @@ export type HierarchyOptions = { * Always its own document. Never introduces folder hierarchy. * This is an important invariant, as it ensures that there is always at least one document in the output. */ - [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyOptions; /** * Hierarchy configuration for the `Package` API item kind. @@ -304,8 +342,8 @@ export type HierarchyOptions = { [ApiItemKind.Package]?: | HierarchyKind.Document | HierarchyKind.Folder - | DocumentHierarchyConfiguration - | FolderHierarchyConfiguration; + | DocumentHierarchyOptions + | FolderHierarchyOptions; /** * Hierarchy configuration for the `EntryPoint` API item kind. @@ -318,7 +356,7 @@ export type HierarchyOptions = { * TODO: Allow all hierarchy configurations for packages. * There isn't a real reason to restrict this, except the way the code is currently structured. */ - [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyOptions; }; /** @@ -359,7 +397,7 @@ const defaultHierarchyConfiguration: HierarchyConfiguration = { * Maps an input option to a complete {@link DocumentationHierarchyConfiguration}. */ function mapHierarchyOption( - option: HierarchyKind | DocumentationHierarchyConfiguration, + option: HierarchyKind | DocumentationHierarchyOptions, ): DocumentationHierarchyConfiguration { switch (option) { case HierarchyKind.Section: { @@ -372,7 +410,21 @@ function mapHierarchyOption( return defaultFolderHierarchyConfig; } default: { - return option; + const kind = option.kind; + switch (kind) { + case HierarchyKind.Section: { + return { ...defaultSectionHierarchyConfig, ...option }; + } + case HierarchyKind.Document: { + return { ...defaultDocumentHierarchyConfig, ...option }; + } + case HierarchyKind.Folder: { + return { ...defaultFolderHierarchyConfig, ...option }; + } + default: { + throw new Error(`Invalid hierarchy configuration kind: ${kind}`); + } + } } } } diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts index 908eda9902f7..7e9a37182f51 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts @@ -18,18 +18,19 @@ export { export { type DocumentationHierarchyConfiguration, type DocumentationHierarchyConfigurationBase, + type DocumentationHierarchyOptions, type DocumentHierarchyConfiguration, + type DocumentHierarchyOptions, type DocumentHierarchyProperties, FolderDocumentPlacement, type FolderHierarchyConfiguration, + type FolderHierarchyOptions, type FolderHierarchyProperties, - defaultDocumentHierarchyConfig, - defaultFolderHierarchyConfig, - defaultSectionHierarchyConfig, type HierarchyConfiguration, type HierarchyOptions, HierarchyKind, type SectionHierarchyConfiguration, + type SectionHierarchyOptions, } from "./Hierarchy.js"; export { type ApiItemTransformations, diff --git a/tools/api-markdown-documenter/src/api-item-transforms/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/index.ts index f455ef0cfec9..4c5a34b1f5a6 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/index.ts @@ -22,22 +22,23 @@ export { type ApiItemTransformations, type DefaultDocumentationSuiteConfiguration, type DocumentHierarchyConfiguration, + type DocumentHierarchyOptions, type DocumentHierarchyProperties, type DocumentationSuiteConfiguration, type DocumentationSuiteOptions, FolderDocumentPlacement, type FolderHierarchyConfiguration, + type FolderHierarchyOptions, type FolderHierarchyProperties, getApiItemTransformationConfigurationWithDefaults, - defaultDocumentHierarchyConfig, - defaultFolderHierarchyConfig, - defaultSectionHierarchyConfig, type DocumentationHierarchyConfiguration, type DocumentationHierarchyConfigurationBase, + type DocumentationHierarchyOptions, HierarchyKind, type HierarchyConfiguration, type HierarchyOptions, type SectionHierarchyConfiguration, + type SectionHierarchyOptions, type TransformApiItemWithChildren, type TransformApiItemWithoutChildren, } from "./configuration/index.js"; diff --git a/tools/api-markdown-documenter/src/index.ts b/tools/api-markdown-documenter/src/index.ts index 2e6fd38cc746..5d9c9107f74e 100644 --- a/tools/api-markdown-documenter/src/index.ts +++ b/tools/api-markdown-documenter/src/index.ts @@ -19,21 +19,25 @@ export { type ApiItemTransformationOptions, type ApiItemTransformations, type DefaultDocumentationSuiteConfiguration, - type DocumentHierarchyConfiguration, - type DocumentHierarchyProperties, + type DocumentationHierarchyConfiguration, + type DocumentationHierarchyConfigurationBase, + type DocumentationHierarchyOptions, type DocumentationSuiteConfiguration, type DocumentationSuiteOptions, + type DocumentHierarchyConfiguration, + type DocumentHierarchyOptions, + type DocumentHierarchyProperties, FolderDocumentPlacement, type FolderHierarchyConfiguration, + type FolderHierarchyOptions, type FolderHierarchyProperties, // TODO: remove this once utility APIs can be called with partial configs. getApiItemTransformationConfigurationWithDefaults, - type DocumentationHierarchyConfiguration, - type DocumentationHierarchyConfigurationBase, HierarchyKind, type HierarchyConfiguration, type HierarchyOptions, type SectionHierarchyConfiguration, + type SectionHierarchyOptions, type TransformApiItemWithChildren, type TransformApiItemWithoutChildren, transformApiModel, diff --git a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts index 0238b87c77ed..78ff9c825ed0 100644 --- a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts +++ b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts @@ -11,12 +11,11 @@ import { FileSystem } from "@rushstack/node-core-library"; import { expect } from "chai"; import { compare } from "dir-compare"; -import { defaultFolderHierarchyConfig } from "../api-item-transforms/index.js"; import { FolderDocumentPlacement, HierarchyKind, type HierarchyOptions, - type FolderHierarchyConfiguration, + type FolderHierarchyOptions, } from "../index.js"; const dirname = Path.dirname(fileURLToPath(import.meta.url)); @@ -39,23 +38,21 @@ export const snapshotsDirectoryPath = Path.resolve(dirname, "..", "..", "src", " export const testDataDirectoryPath = Path.resolve(dirname, "..", "..", "src", "test", "test-data"); /** - * Test hierarchy configs + * Test hierarchy configurations * * @privateRemarks TODO: Formalize and export some of these as pre-canned solutions? */ // eslint-disable-next-line @typescript-eslint/no-namespace -export namespace HierarchyConfigs { - const outsideFolderConfig: FolderHierarchyConfiguration = { +export namespace HierarchyConfigurations { + const outsideFolderConfig: FolderHierarchyOptions = { kind: HierarchyKind.Folder, documentPlacement: FolderDocumentPlacement.Outside, - folderName: defaultFolderHierarchyConfig.folderName, }; - const insideFolderConfig: FolderHierarchyConfiguration = { + const insideFolderOptions: FolderHierarchyOptions = { kind: HierarchyKind.Folder, documentPlacement: FolderDocumentPlacement.Inside, documentName: "index", - folderName: defaultFolderHierarchyConfig.folderName, }; /** @@ -114,12 +111,12 @@ export namespace HierarchyConfigs { */ export const deep: HierarchyOptions = { // Items that introduce folder hierarchy: - [ApiItemKind.Namespace]: insideFolderConfig, - [ApiItemKind.Package]: insideFolderConfig, - [ApiItemKind.Class]: insideFolderConfig, - [ApiItemKind.Enum]: insideFolderConfig, - [ApiItemKind.Interface]: insideFolderConfig, - [ApiItemKind.TypeAlias]: insideFolderConfig, + [ApiItemKind.Namespace]: insideFolderOptions, + [ApiItemKind.Package]: insideFolderOptions, + [ApiItemKind.Class]: insideFolderOptions, + [ApiItemKind.Enum]: insideFolderOptions, + [ApiItemKind.Interface]: insideFolderOptions, + [ApiItemKind.TypeAlias]: insideFolderOptions, // Items that get their own document, but do not introduce folder hierarchy: [ApiItemKind.CallSignature]: HierarchyKind.Document, diff --git a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts index e87a4253b31f..051304b9bbc5 100644 --- a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts @@ -11,7 +11,7 @@ import { HtmlRenderer, loadModel } from "../index.js"; import { compareDocumentationSuiteSnapshot, - HierarchyConfigs, + HierarchyConfigurations, snapshotsDirectoryPath as snapshotsDirectoryPathBase, testDataDirectoryPath, testTemporaryDirectoryPath as testTemporaryDirectoryPathBase, @@ -48,7 +48,7 @@ const testConfigs = new Map< uriRoot: "docs", includeBreadcrumb: true, includeTopLevelDocumentHeading: false, - hierarchy: HierarchyConfigs.flat, + hierarchy: HierarchyConfigurations.flat, minimumReleaseLevel: ReleaseTag.Beta, // Only include `@public` and `beta` items in the docs suite }, ], @@ -60,7 +60,7 @@ const testConfigs = new Map< uriRoot: "docs", includeBreadcrumb: false, includeTopLevelDocumentHeading: true, - hierarchy: HierarchyConfigs.sparse, + hierarchy: HierarchyConfigurations.sparse, minimumReleaseLevel: ReleaseTag.Public, // Only include `@public` items in the docs suite skipPackage: (apiPackage) => apiPackage.name === "test-suite-b", // Skip test-suite-b package startingHeadingLevel: 2, @@ -74,7 +74,7 @@ const testConfigs = new Map< "deep-config", { uriRoot: ".", - hierarchy: HierarchyConfigs.deep, + hierarchy: HierarchyConfigurations.deep, }, ], ]); diff --git a/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts index d72107c1142f..9e95aaf09c0d 100644 --- a/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts @@ -11,7 +11,7 @@ import { loadModel, MarkdownRenderer } from "../index.js"; import { compareDocumentationSuiteSnapshot, - HierarchyConfigs, + HierarchyConfigurations, snapshotsDirectoryPath as snapshotsDirectoryPathBase, testDataDirectoryPath, testTemporaryDirectoryPath as testTemporaryDirectoryPathBase, @@ -48,7 +48,7 @@ const testConfigs = new Map< uriRoot: "docs", includeBreadcrumb: true, includeTopLevelDocumentHeading: false, - hierarchy: HierarchyConfigs.flat, + hierarchy: HierarchyConfigurations.flat, minimumReleaseLevel: ReleaseTag.Beta, // Only include `@public` and `beta` items in the docs suite }, ], @@ -60,7 +60,7 @@ const testConfigs = new Map< uriRoot: "docs", includeBreadcrumb: false, includeTopLevelDocumentHeading: true, - hierarchy: HierarchyConfigs.sparse, + hierarchy: HierarchyConfigurations.sparse, minimumReleaseLevel: ReleaseTag.Public, // Only include `@public` items in the docs suite skipPackage: (apiPackage) => apiPackage.name === "test-suite-b", // Skip test-suite-b package startingHeadingLevel: 2, @@ -74,7 +74,7 @@ const testConfigs = new Map< "deep-config", { uriRoot: ".", - hierarchy: HierarchyConfigs.deep, + hierarchy: HierarchyConfigurations.deep, }, ], ]); diff --git a/tools/api-markdown-documenter/src/test/TransformApiModelEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/TransformApiModelEndToEnd.test.ts index 0e7eeb34148d..f89a2b8ad036 100644 --- a/tools/api-markdown-documenter/src/test/TransformApiModelEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/TransformApiModelEndToEnd.test.ts @@ -10,7 +10,7 @@ import { ReleaseTag, type ApiModel } from "@microsoft/api-extractor-model"; import { checkForDuplicateDocumentPaths } from "../api-item-transforms/index.js"; import { loadModel, transformApiModel, type ApiItemTransformationOptions } from "../index.js"; -import { HierarchyConfigs, testDataDirectoryPath } from "./EndToEndTestUtilities.js"; +import { HierarchyConfigurations, testDataDirectoryPath } from "./EndToEndTestUtilities.js"; const apiModels: string[] = ["simple-suite-test"]; @@ -29,7 +29,7 @@ const testConfigs = new Map apiPackage.name === "test-suite-b", // Skip test-suite-b package }, From 42c752b8a8d584c8029ac930602f249f14f7f088 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Tue, 7 Jan 2025 00:30:48 +0000 Subject: [PATCH 33/54] WIP: Better hierarchical control over naming policy --- .../api-markdown-documenter.alpha.api.md | 12 +- .../api-markdown-documenter.beta.api.md | 12 +- .../api-markdown-documenter.public.api.md | 12 +- .../src/ApiItemUtilitiesModule.ts | 1 + .../ApiItemTransformUtilities.ts | 68 ++++++--- .../src/api-item-transforms/Utilities.ts | 2 +- .../configuration/DocumentationSuite.ts | 135 +++++++++++++++--- .../configuration/Hierarchy.ts | 76 ++-------- .../src/api-item-transforms/index.ts | 1 + .../src/test/EndToEndTestUtilities.ts | 4 +- 10 files changed, 212 insertions(+), 111 deletions(-) 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 25cc475d323c..5e7fcf743e84 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 @@ -106,6 +106,7 @@ export interface ApiItemTransformations { declare namespace ApiItemUtilities { export { + createQualifiedDocumentNameForApiItem, doesItemKindRequireOwnDocument, filterItems, getHeadingForApiItem, @@ -186,6 +187,9 @@ function createExamplesSection(apiItem: ApiItem, config: ApiItemTransformationCo // @public function createParametersSection(apiFunctionLike: ApiFunctionLike, config: ApiItemTransformationConfiguration): SectionNode | undefined; +// @public +function createQualifiedDocumentNameForApiItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; + // @public function createRemarksSection(apiItem: ApiItem, config: ApiItemTransformationConfiguration): SectionNode | undefined; @@ -213,6 +217,8 @@ export const defaultConsoleLogger: Logger; // @public export namespace DefaultDocumentationSuiteConfiguration { export function defaultGetAlertsForItem(apiItem: ApiItem): string[]; + export function defaultGetDocumentNameForItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; + export function defaultGetFolderNameForItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; export function defaultGetHeadingTextForItem(apiItem: ApiItem): string; export function defaultGetLinkTextForItem(apiItem: ApiItem): string; export function defaultGetUriBaseOverrideForItem(): string | undefined; @@ -315,6 +321,8 @@ export abstract class DocumentationParentNodeBase string[]; + readonly getDocumentNameForItem: (apiItem: ApiItem) => string; + readonly getFolderNameForItem: (apiItem: ApiItem) => string; readonly getHeadingTextForItem: (apiItem: ApiItem) => string; readonly getLinkTextForItem: (apiItem: ApiItem) => string; readonly getUriBaseOverrideForItem: (apiItem: ApiItem) => string | undefined; @@ -338,7 +346,7 @@ export type DocumentHierarchyOptions = DocumentationHierarchyConfigurationBase string); + readonly documentName: string | undefined | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string | undefined); } // @public @@ -414,7 +422,7 @@ export type FolderHierarchyOptions = DocumentationHierarchyConfigurationBase string); + readonly folderName: string | undefined | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string | undefined); } // @public 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 999c00ee48f2..506e471f5541 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 @@ -106,6 +106,7 @@ export interface ApiItemTransformations { declare namespace ApiItemUtilities { export { + createQualifiedDocumentNameForApiItem, doesItemKindRequireOwnDocument, filterItems, getHeadingForApiItem, @@ -186,6 +187,9 @@ function createExamplesSection(apiItem: ApiItem, config: ApiItemTransformationCo // @public function createParametersSection(apiFunctionLike: ApiFunctionLike, config: ApiItemTransformationConfiguration): SectionNode | undefined; +// @public +function createQualifiedDocumentNameForApiItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; + // @public function createRemarksSection(apiItem: ApiItem, config: ApiItemTransformationConfiguration): SectionNode | undefined; @@ -213,6 +217,8 @@ export const defaultConsoleLogger: Logger; // @public export namespace DefaultDocumentationSuiteConfiguration { export function defaultGetAlertsForItem(apiItem: ApiItem): string[]; + export function defaultGetDocumentNameForItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; + export function defaultGetFolderNameForItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; export function defaultGetHeadingTextForItem(apiItem: ApiItem): string; export function defaultGetLinkTextForItem(apiItem: ApiItem): string; export function defaultGetUriBaseOverrideForItem(): string | undefined; @@ -315,6 +321,8 @@ export abstract class DocumentationParentNodeBase string[]; + readonly getDocumentNameForItem: (apiItem: ApiItem) => string; + readonly getFolderNameForItem: (apiItem: ApiItem) => string; readonly getHeadingTextForItem: (apiItem: ApiItem) => string; readonly getLinkTextForItem: (apiItem: ApiItem) => string; readonly getUriBaseOverrideForItem: (apiItem: ApiItem) => string | undefined; @@ -338,7 +346,7 @@ export type DocumentHierarchyOptions = DocumentationHierarchyConfigurationBase string); + readonly documentName: string | undefined | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string | undefined); } // @public @@ -414,7 +422,7 @@ export type FolderHierarchyOptions = DocumentationHierarchyConfigurationBase string); + readonly folderName: string | undefined | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string | undefined); } // @public 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 68879768a45f..a33435cee31e 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 @@ -106,6 +106,7 @@ export interface ApiItemTransformations { declare namespace ApiItemUtilities { export { + createQualifiedDocumentNameForApiItem, doesItemKindRequireOwnDocument, filterItems, getHeadingForApiItem, @@ -186,6 +187,9 @@ function createExamplesSection(apiItem: ApiItem, config: ApiItemTransformationCo // @public function createParametersSection(apiFunctionLike: ApiFunctionLike, config: ApiItemTransformationConfiguration): SectionNode | undefined; +// @public +function createQualifiedDocumentNameForApiItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; + // @public function createRemarksSection(apiItem: ApiItem, config: ApiItemTransformationConfiguration): SectionNode | undefined; @@ -213,6 +217,8 @@ export const defaultConsoleLogger: Logger; // @public export namespace DefaultDocumentationSuiteConfiguration { export function defaultGetAlertsForItem(apiItem: ApiItem): string[]; + export function defaultGetDocumentNameForItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; + export function defaultGetFolderNameForItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; export function defaultGetHeadingTextForItem(apiItem: ApiItem): string; export function defaultGetLinkTextForItem(apiItem: ApiItem): string; export function defaultGetUriBaseOverrideForItem(): string | undefined; @@ -315,6 +321,8 @@ export abstract class DocumentationParentNodeBase string[]; + readonly getDocumentNameForItem: (apiItem: ApiItem) => string; + readonly getFolderNameForItem: (apiItem: ApiItem) => string; readonly getHeadingTextForItem: (apiItem: ApiItem) => string; readonly getLinkTextForItem: (apiItem: ApiItem) => string; readonly getUriBaseOverrideForItem: (apiItem: ApiItem) => string | undefined; @@ -338,7 +346,7 @@ export type DocumentHierarchyOptions = DocumentationHierarchyConfigurationBase string); + readonly documentName: string | undefined | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string | undefined); } // @public @@ -414,7 +422,7 @@ export type FolderHierarchyOptions = DocumentationHierarchyConfigurationBase string); + readonly folderName: string | undefined | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string | undefined); } // @public diff --git a/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts b/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts index 60e397638707..cca0cb5ff398 100644 --- a/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts +++ b/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts @@ -8,6 +8,7 @@ */ export { + createQualifiedDocumentNameForApiItem, doesItemKindRequireOwnDocument, filterItems, getHeadingForApiItem, 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 c962e88747f2..39114def93da 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts @@ -14,8 +14,8 @@ import { getFilteredParent, getFileSafeNameForApiItem, getReleaseTag, - getValueOrDerived, type ValidApiItemKind, + getValueOrDerived, } from "../utilities/index.js"; import { @@ -26,6 +26,7 @@ import { type FolderHierarchyConfiguration, type DocumentationHierarchyConfiguration, type HierarchyConfiguration, + type DocumentationSuiteConfiguration, } from "./configuration/index.js"; /** @@ -83,7 +84,7 @@ function getLinkUrlForApiItem( config: ApiItemTransformationConfiguration, ): string { const uriBase = config.getUriBaseOverrideForItem(apiItem) ?? config.uriRoot; - let documentPath = getDocumentPathForApiItem(apiItem, config.hierarchy); + let documentPath = getDocumentPathForApiItem(apiItem, config); // Omit "index" file name from path generated in links. // This can be considered an optimization in most cases, but some documentation systems also special-case @@ -137,7 +138,7 @@ function findInHierarchy( */ function getFirstAncestorWithOwnDocument( apiItem: ApiItem, - hierarchyConfig: Required, + hierarchyConfig: HierarchyConfiguration, ): ApiItemWithHierarchy { // Walk parentage until we reach an item kind that gets rendered to its own document. // That is the document we will target with the generated link. @@ -172,15 +173,14 @@ function getFirstAncestorWithOwnDocument( * The generated path is relative to {@link ApiItemTransformationConfiguration.uriRoot}. * * @param apiItem - The API item for which we are generating a file path. - * @param hierarchyConfig - See {@link HierarchyConfiguration}. + * @param config - See {@link ApiItemTransformationConfiguration} */ export function getDocumentPathForApiItem( apiItem: ApiItem, - hierarchyConfig: HierarchyConfiguration, + config: DocumentationSuiteConfiguration, ): string { - const targetDocument = getFirstAncestorWithOwnDocument(apiItem, hierarchyConfig); - - const documentName = getDocumentNameForItem(targetDocument, hierarchyConfig); + const targetDocument = getFirstAncestorWithOwnDocument(apiItem, config.hierarchy); + const targetDocumentName = getDocumentNameForItem(targetDocument, config); const pathSegments: string[] = []; @@ -191,23 +191,23 @@ export function getDocumentPathForApiItem( targetDocument.hierarchy.documentPlacement === FolderDocumentPlacement.Inside ) { const folderName = getFolderNameForItem( - targetDocument as ApiItemWithHierarchy, - hierarchyConfig, + { apiItem: targetDocument.apiItem, hierarchy: targetDocument.hierarchy }, + config, ); - pathSegments.push(`${folderName}/${documentName}`); + pathSegments.push(`${folderName}/${targetDocumentName}`); } else { - pathSegments.push(documentName); + pathSegments.push(targetDocumentName); } let currentItem: ApiItem | undefined = getFilteredParent(targetDocument.apiItem); while (currentItem !== undefined) { const currentItemKind = getApiItemKind(currentItem); - const currentItemHierarchy = hierarchyConfig[currentItemKind]; + const currentItemHierarchy = config.hierarchy[currentItemKind]; // Push path segments for all folders in the hierarchy if (currentItemHierarchy.kind === HierarchyKind.Folder) { const folderName = getFolderNameForItem( { apiItem: currentItem, hierarchy: currentItemHierarchy }, - hierarchyConfig, + config, ); pathSegments.push(folderName); } @@ -222,27 +222,53 @@ export function getDocumentPathForApiItem( function getDocumentNameForItem( item: ApiItemWithHierarchy, - hierarchyConfig: HierarchyConfiguration, + config: DocumentationSuiteConfiguration, ): string { - return getValueOrDerived(item.hierarchy.documentName, item.apiItem, hierarchyConfig); + // If the hierarchy config specifies a document name, use that. Otherwise, fall back to the suite configuration. + if (item.hierarchy.documentName !== undefined) { + const documentName = getValueOrDerived( + item.hierarchy.documentName, + item.apiItem, + config.hierarchy, + ); + if (documentName !== undefined) { + return documentName; + } + } + + return config.getDocumentNameForItem(item.apiItem); } function getFolderNameForItem( item: ApiItemWithHierarchy, - hierarchyConfig: HierarchyConfiguration, + config: DocumentationSuiteConfiguration, ): string { - return getValueOrDerived(item.hierarchy.folderName, item.apiItem, hierarchyConfig); + // If the hierarchy config specifies a document name, use that. Otherwise, fall back to the suite configuration. + if (item.hierarchy.folderName !== undefined) { + const folderName = getValueOrDerived( + item.hierarchy.folderName, + item.apiItem, + config.hierarchy, + ); + if (folderName !== undefined) { + return folderName; + } + } + + return config.getFolderNameForItem(item.apiItem); } /** * Generates a qualified document name for the specified API item aimed at preventing name collisions, accounting for folder hierarchy. * * @param apiItem - The API item for which we are generating a qualified name - * @param hierarchyConfig - See {@link HierarchyConfiguration}. + * @param config - See {@link DocumentationSuiteConfiguration} + * + * @public */ export function createQualifiedDocumentNameForApiItem( apiItem: ApiItem, - hierarchyConfig: HierarchyConfiguration, + config: DocumentationSuiteConfiguration, ): string { const apiItemKind = getApiItemKind(apiItem); let documentName = getFileSafeNameForApiItem(apiItem); @@ -262,7 +288,7 @@ export function createQualifiedDocumentNameForApiItem( while ( currentItem !== undefined && currentItem.kind !== "Model" && - hierarchyConfig[getApiItemKind(currentItem)].kind !== HierarchyKind.Folder + config.hierarchy[getApiItemKind(currentItem)].kind !== HierarchyKind.Folder ) { documentName = `${getFileSafeNameForApiItem(currentItem)}-${documentName}`; currentItem = getFilteredParent(currentItem); diff --git a/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts b/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts index c455eecc7aae..f52dbe8a1aec 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts @@ -43,7 +43,7 @@ export function createDocument( return new DocumentNode({ apiItem: documentItem, children: contents, - documentPath: getDocumentPathForApiItem(documentItem, config.hierarchy), + documentPath: getDocumentPathForApiItem(documentItem, config), }); } 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 b12b3e8f5f54..7a8c14deafdd 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 @@ -14,10 +14,14 @@ import { import { getApiItemKind, getConciseSignature, + getFileSafeNameForApiItemName, getReleaseTag, getSingleLineExcerptText, + getUnscopedPackageName, isDeprecated, + type Mutable, } from "../../utilities/index.js"; +import { createQualifiedDocumentNameForApiItem } from "../ApiItemTransformUtilities.js"; import { getHierarchyOptionsWithDefaults, @@ -56,6 +60,28 @@ export interface DocumentationSuiteConfiguration { */ readonly hierarchy: HierarchyConfiguration; + /** + * Generate the desired document name for the provided `ApiItem`. + * + * @remarks Will be invoked for any item configured to generate document or folder level hierarchy via {@link DocumentationSuiteConfiguration.hierarchy}. + * + * Can be further overridden on a per-item-kind basis via {@link DocumentationSuiteConfiguration.hierarchy}. + * + * @param apiItem - The API item in question. + */ + readonly getDocumentNameForItem: (apiItem: ApiItem) => string; + + /** + * Generate the desired folder name for the provided `ApiItem`. + * + * @remarks Will be invoked for any item configured to generate document or folder level hierarchy via {@link DocumentationSuiteConfiguration.hierarchy}. + * + * Can be further overridden on a per-item-kind basis via {@link DocumentationSuiteConfiguration.hierarchy}. + * + * @param apiItem - The API item in question. + */ + readonly getFolderNameForItem: (apiItem: ApiItem) => string; + /** * Optionally provide an override for the URI base used in links generated for the provided `ApiItem`. * @@ -164,6 +190,58 @@ export type DocumentationSuiteOptions = Omit< */ // eslint-disable-next-line @typescript-eslint/no-namespace export namespace DefaultDocumentationSuiteConfiguration { + /** + * Default {@link DocumentationSuiteConfiguration.getDocumentNameForItem}. + * + * @remarks + * Uses the item's scoped and qualified API name, but is handled differently for the following items: + * + * - Model: "index" + * + * - Package: Use the unscoped package name. + */ + export function defaultGetDocumentNameForItem( + apiItem: ApiItem, + config: DocumentationSuiteConfiguration, + ): string { + const kind = getApiItemKind(apiItem); + switch (kind) { + case ApiItemKind.Model: { + return "index"; + } + case ApiItemKind.Package: { + return getFileSafeNameForApiItemName(getUnscopedPackageName(apiItem as ApiPackage)); + } + default: { + return createQualifiedDocumentNameForApiItem(apiItem, config); + } + } + } + + /** + * Default {@link DocumentationSuiteConfiguration.getFolderNameForItem}. + * + * @remarks + * Uses the item's scoped and qualified API name, but is handled differently for the following items: + * + * - Package: Use the unscoped package name. + */ + export function defaultGetFolderNameForItem( + apiItem: ApiItem, + config: DocumentationSuiteConfiguration, + ): string { + const kind = getApiItemKind(apiItem); + switch (kind) { + case ApiItemKind.Package: { + return getFileSafeNameForApiItemName(getUnscopedPackageName(apiItem as ApiPackage)); + } + default: { + // Let the system generate a unique name that accounts for folder hierarchy. + return createQualifiedDocumentNameForApiItem(apiItem, config); + } + } + } + /** * Default {@link DocumentationSuiteConfiguration.getUriBaseOverrideForItem}. * @@ -265,21 +343,6 @@ export namespace DefaultDocumentationSuiteConfiguration { } } -/** - * Default {@link DocumentationSuiteConfiguration}. - */ -const defaultDocumentationSuiteConfiguration: Omit = { - includeTopLevelDocumentHeading: true, - includeBreadcrumb: true, - getUriBaseOverrideForItem: - DefaultDocumentationSuiteConfiguration.defaultGetUriBaseOverrideForItem, - getHeadingTextForItem: DefaultDocumentationSuiteConfiguration.defaultGetHeadingTextForItem, - getLinkTextForItem: DefaultDocumentationSuiteConfiguration.defaultGetLinkTextForItem, - getAlertsForItem: DefaultDocumentationSuiteConfiguration.defaultGetAlertsForItem, - skipPackage: DefaultDocumentationSuiteConfiguration.defaultSkipPackage, - minimumReleaseLevel: ReleaseTag.Internal, // Include everything in the input model -}; - /** * Gets a complete {@link DocumentationSuiteConfiguration} using the provided partial configuration, and filling * in the remainder with the documented defaults. @@ -288,9 +351,45 @@ export function getDocumentationSuiteConfigurationWithDefaults( options: DocumentationSuiteOptions, ): DocumentationSuiteConfiguration { const hierarchy: HierarchyConfiguration = getHierarchyOptionsWithDefaults(options.hierarchy); - return { - ...defaultDocumentationSuiteConfiguration, - ...options, + + const config: Mutable< + Omit + > = { hierarchy, + includeTopLevelDocumentHeading: options.includeTopLevelDocumentHeading ?? true, + includeBreadcrumb: options.includeBreadcrumb ?? true, + getUriBaseOverrideForItem: + options.getUriBaseOverrideForItem ?? + DefaultDocumentationSuiteConfiguration.defaultGetUriBaseOverrideForItem, + getHeadingTextForItem: + options.getHeadingTextForItem ?? + DefaultDocumentationSuiteConfiguration.defaultGetHeadingTextForItem, + getLinkTextForItem: + options.getLinkTextForItem ?? + DefaultDocumentationSuiteConfiguration.defaultGetLinkTextForItem, + getAlertsForItem: + options.getAlertsForItem ?? + DefaultDocumentationSuiteConfiguration.defaultGetAlertsForItem, + skipPackage: + options.skipPackage ?? DefaultDocumentationSuiteConfiguration.defaultSkipPackage, + minimumReleaseLevel: options.minimumReleaseLevel ?? ReleaseTag.Internal, }; + + (config as Mutable).getDocumentNameForItem = + options.getDocumentNameForItem ?? + ((apiItem) => + DefaultDocumentationSuiteConfiguration.defaultGetDocumentNameForItem( + apiItem, + config as DocumentationSuiteConfiguration, + )); + + (config as Mutable).getFolderNameForItem = + options.getFolderNameForItem ?? + ((apiItem) => + DefaultDocumentationSuiteConfiguration.defaultGetFolderNameForItem( + apiItem, + config as DocumentationSuiteConfiguration, + )); + + return config as DocumentationSuiteConfiguration; } diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts index 691dd150ecec..a7be78206744 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts @@ -3,16 +3,9 @@ * Licensed under the MIT License. */ -import { type ApiItem, ApiItemKind, type ApiPackage } from "@microsoft/api-extractor-model"; +import { type ApiItem, ApiItemKind } from "@microsoft/api-extractor-model"; -import { - getApiItemKind, - type ValidApiItemKind, - type Mutable, - getFileSafeNameForApiItemName, - getUnscopedPackageName, -} from "../../utilities/index.js"; -import { createQualifiedDocumentNameForApiItem } from "../ApiItemTransformUtilities.js"; +import type { ValidApiItemKind, Mutable } from "../../utilities/index.js"; /** * Kind of documentation suite hierarchy. @@ -76,11 +69,13 @@ export type SectionHierarchyOptions = export interface DocumentHierarchyProperties { /** * Document name to use for the API item. - * @remarks `undefined` indicates that the system default should be used. + * + * @defaultValue {@link DocumentationSuiteConfiguration.getFolderNameForItem} */ readonly documentName: | string - | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string); + | undefined + | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string | undefined); } /** @@ -133,11 +128,13 @@ export interface FolderHierarchyProperties extends DocumentHierarchyProperties { /** * Folder name to use for the API item. - * @remarks `undefined` indicates that the system default should be used. + * + * @defaultValue {@link DocumentationSuiteConfiguration.getFolderNameForItem} */ readonly folderName: | string - | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string); + | undefined + | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string | undefined); } /** @@ -187,69 +184,22 @@ export const defaultSectionHierarchyConfig: SectionHierarchyConfiguration = { kind: HierarchyKind.Section, }; -/** - * Default {@link DocumentHierarchyProperties.documentName} for non-folder hierarchy documents. - * - * @remarks - * Uses the item's scoped and qualified API name, but is handled differently for the following items: - * - * - Model: "index" - * - * - Package: Use the unscoped package name. - */ -function defaultDocumentName(apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration): string { - const kind = getApiItemKind(apiItem); - switch (kind) { - case ApiItemKind.Model: { - return "index"; - } - case ApiItemKind.Package: { - return getFileSafeNameForApiItemName(getUnscopedPackageName(apiItem as ApiPackage)); - } - default: { - return createQualifiedDocumentNameForApiItem(apiItem, hierarchyConfig); - } - } -} - /** * Default {@link DocumentHierarchyConfiguration} used by the system. */ export const defaultDocumentHierarchyConfig: DocumentHierarchyConfiguration = { kind: HierarchyKind.Document, - documentName: defaultDocumentName, + documentName: undefined, // Use suite configuration default. }; -/** - * Default {@link DocumentHierarchyProperties.documentName} for non-folder hierarchy documents. - * - * @remarks - * Uses the item's scoped and qualified API name, but is handled differently for the following items: - * - * - Package: Use the unscoped package name. - */ -function defaultFolderName(apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration): string { - const kind = getApiItemKind(apiItem); - switch (kind) { - case ApiItemKind.Package: { - return getFileSafeNameForApiItemName(getUnscopedPackageName(apiItem as ApiPackage)); - } - default: { - // Let the system generate a unique name that accounts for folder hierarchy. - return createQualifiedDocumentNameForApiItem(apiItem, hierarchyConfig); - } - } -} - /** * Default {@link FolderHierarchyConfiguration} used by the system. */ export const defaultFolderHierarchyConfig: FolderHierarchyConfiguration = { kind: HierarchyKind.Folder, - documentName: defaultDocumentName, + documentName: undefined, // Use suite configuration default. documentPlacement: FolderDocumentPlacement.Outside, // TODO - // documentName: "index", // Documents for items that get their own folder are always named "index" by default. - folderName: defaultFolderName, + folderName: undefined, // Use suite configuration default. }; /** diff --git a/tools/api-markdown-documenter/src/api-item-transforms/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/index.ts index 4c5a34b1f5a6..4fdba01eb0a2 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/index.ts @@ -8,6 +8,7 @@ */ export { + createQualifiedDocumentNameForApiItem, doesItemRequireOwnDocument, doesItemKindRequireOwnDocument, filterItems, diff --git a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts index 78ff9c825ed0..cab4da356672 100644 --- a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts +++ b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts @@ -14,8 +14,8 @@ import { compare } from "dir-compare"; import { FolderDocumentPlacement, HierarchyKind, - type HierarchyOptions, type FolderHierarchyOptions, + type HierarchyOptions, } from "../index.js"; const dirname = Path.dirname(fileURLToPath(import.meta.url)); @@ -81,7 +81,7 @@ export namespace HierarchyConfigurations { }; /** - * "Sparse" hierarchy: Packages yield folder hierarchy, and all descendent items get their own document under that folder. + * "Sparse" hierarchy: Packages yield folder hierarchy, and each descendent item gets its own document under that folder. * @remarks Leads to many documents, but each document is likely to be relatively small. */ export const sparse: HierarchyOptions = { From 338e12abc70e9dae7aa3cfb4fba6a4883958a5c3 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Tue, 7 Jan 2025 01:19:53 +0000 Subject: [PATCH 34/54] WIP: More input flexibility progress --- .../api-markdown-documenter.alpha.api.md | 8 +- .../api-markdown-documenter.beta.api.md | 8 +- .../api-markdown-documenter.public.api.md | 8 +- .../ApiItemTransformUtilities.ts | 62 +++------ .../src/api-item-transforms/Utilities.ts | 2 +- .../configuration/DocumentationSuite.ts | 73 +++++----- .../configuration/Hierarchy.ts | 130 ++++++++++-------- 7 files changed, 141 insertions(+), 150 deletions(-) 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 5e7fcf743e84..f4009b53e9d7 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 @@ -321,8 +321,6 @@ export abstract class DocumentationParentNodeBase string[]; - readonly getDocumentNameForItem: (apiItem: ApiItem) => string; - readonly getFolderNameForItem: (apiItem: ApiItem) => string; readonly getHeadingTextForItem: (apiItem: ApiItem) => string; readonly getLinkTextForItem: (apiItem: ApiItem) => string; readonly getUriBaseOverrideForItem: (apiItem: ApiItem) => string | undefined; @@ -336,6 +334,8 @@ export interface DocumentationSuiteConfiguration { // @public export type DocumentationSuiteOptions = Omit, "hierarchy"> & { readonly hierarchy?: HierarchyOptions; + readonly getDocumentNameForItem?: (apiItem: ApiItem) => string; + readonly getFolderNameForItem?: (apiItem: ApiItem) => string; }; // @public @@ -346,7 +346,7 @@ export type DocumentHierarchyOptions = DocumentationHierarchyConfigurationBase string | undefined); + readonly documentName: string | ((apiItem: ApiItem) => string); } // @public @@ -422,7 +422,7 @@ export type FolderHierarchyOptions = DocumentationHierarchyConfigurationBase string | undefined); + readonly folderName: string | ((apiItem: ApiItem) => string); } // @public 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 506e471f5541..863d98ecb14a 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 @@ -321,8 +321,6 @@ export abstract class DocumentationParentNodeBase string[]; - readonly getDocumentNameForItem: (apiItem: ApiItem) => string; - readonly getFolderNameForItem: (apiItem: ApiItem) => string; readonly getHeadingTextForItem: (apiItem: ApiItem) => string; readonly getLinkTextForItem: (apiItem: ApiItem) => string; readonly getUriBaseOverrideForItem: (apiItem: ApiItem) => string | undefined; @@ -336,6 +334,8 @@ export interface DocumentationSuiteConfiguration { // @public export type DocumentationSuiteOptions = Omit, "hierarchy"> & { readonly hierarchy?: HierarchyOptions; + readonly getDocumentNameForItem?: (apiItem: ApiItem) => string; + readonly getFolderNameForItem?: (apiItem: ApiItem) => string; }; // @public @@ -346,7 +346,7 @@ export type DocumentHierarchyOptions = DocumentationHierarchyConfigurationBase string | undefined); + readonly documentName: string | ((apiItem: ApiItem) => string); } // @public @@ -422,7 +422,7 @@ export type FolderHierarchyOptions = DocumentationHierarchyConfigurationBase string | undefined); + readonly folderName: string | ((apiItem: ApiItem) => string); } // @public 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 a33435cee31e..496768583e16 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 @@ -321,8 +321,6 @@ export abstract class DocumentationParentNodeBase string[]; - readonly getDocumentNameForItem: (apiItem: ApiItem) => string; - readonly getFolderNameForItem: (apiItem: ApiItem) => string; readonly getHeadingTextForItem: (apiItem: ApiItem) => string; readonly getLinkTextForItem: (apiItem: ApiItem) => string; readonly getUriBaseOverrideForItem: (apiItem: ApiItem) => string | undefined; @@ -336,6 +334,8 @@ export interface DocumentationSuiteConfiguration { // @public export type DocumentationSuiteOptions = Omit, "hierarchy"> & { readonly hierarchy?: HierarchyOptions; + readonly getDocumentNameForItem?: (apiItem: ApiItem) => string; + readonly getFolderNameForItem?: (apiItem: ApiItem) => string; }; // @public @@ -346,7 +346,7 @@ export type DocumentHierarchyOptions = DocumentationHierarchyConfigurationBase string | undefined); + readonly documentName: string | ((apiItem: ApiItem) => string); } // @public @@ -422,7 +422,7 @@ export type FolderHierarchyOptions = DocumentationHierarchyConfigurationBase string | undefined); + readonly folderName: string | ((apiItem: ApiItem) => string); } // @public 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 39114def93da..5f718f7a0b1c 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts @@ -84,7 +84,7 @@ function getLinkUrlForApiItem( config: ApiItemTransformationConfiguration, ): string { const uriBase = config.getUriBaseOverrideForItem(apiItem) ?? config.uriRoot; - let documentPath = getDocumentPathForApiItem(apiItem, config); + let documentPath = getDocumentPathForApiItem(apiItem, config.hierarchy); // Omit "index" file name from path generated in links. // This can be considered an optimization in most cases, but some documentation systems also special-case @@ -173,14 +173,14 @@ function getFirstAncestorWithOwnDocument( * The generated path is relative to {@link ApiItemTransformationConfiguration.uriRoot}. * * @param apiItem - The API item for which we are generating a file path. - * @param config - See {@link ApiItemTransformationConfiguration} + * @param hierarchyConfig - See {@link HierarchyConfiguration} */ export function getDocumentPathForApiItem( apiItem: ApiItem, - config: DocumentationSuiteConfiguration, + hierarchyConfig: HierarchyConfiguration, ): string { - const targetDocument = getFirstAncestorWithOwnDocument(apiItem, config.hierarchy); - const targetDocumentName = getDocumentNameForItem(targetDocument, config); + const targetDocument = getFirstAncestorWithOwnDocument(apiItem, hierarchyConfig); + const targetDocumentName = getDocumentNameForItem(targetDocument); const pathSegments: string[] = []; @@ -190,10 +190,10 @@ export function getDocumentPathForApiItem( targetDocument.hierarchy.kind === HierarchyKind.Folder && targetDocument.hierarchy.documentPlacement === FolderDocumentPlacement.Inside ) { - const folderName = getFolderNameForItem( - { apiItem: targetDocument.apiItem, hierarchy: targetDocument.hierarchy }, - config, - ); + const folderName = getFolderNameForItem({ + apiItem: targetDocument.apiItem, + hierarchy: targetDocument.hierarchy, + }); pathSegments.push(`${folderName}/${targetDocumentName}`); } else { pathSegments.push(targetDocumentName); @@ -202,13 +202,13 @@ export function getDocumentPathForApiItem( let currentItem: ApiItem | undefined = getFilteredParent(targetDocument.apiItem); while (currentItem !== undefined) { const currentItemKind = getApiItemKind(currentItem); - const currentItemHierarchy = config.hierarchy[currentItemKind]; + const currentItemHierarchy = hierarchyConfig[currentItemKind]; // Push path segments for all folders in the hierarchy if (currentItemHierarchy.kind === HierarchyKind.Folder) { - const folderName = getFolderNameForItem( - { apiItem: currentItem, hierarchy: currentItemHierarchy }, - config, - ); + const folderName = getFolderNameForItem({ + apiItem: currentItem, + hierarchy: currentItemHierarchy, + }); pathSegments.push(folderName); } currentItem = getFilteredParent(currentItem); @@ -222,40 +222,12 @@ export function getDocumentPathForApiItem( function getDocumentNameForItem( item: ApiItemWithHierarchy, - config: DocumentationSuiteConfiguration, ): string { - // If the hierarchy config specifies a document name, use that. Otherwise, fall back to the suite configuration. - if (item.hierarchy.documentName !== undefined) { - const documentName = getValueOrDerived( - item.hierarchy.documentName, - item.apiItem, - config.hierarchy, - ); - if (documentName !== undefined) { - return documentName; - } - } - - return config.getDocumentNameForItem(item.apiItem); + return getValueOrDerived(item.hierarchy.documentName, item.apiItem); } -function getFolderNameForItem( - item: ApiItemWithHierarchy, - config: DocumentationSuiteConfiguration, -): string { - // If the hierarchy config specifies a document name, use that. Otherwise, fall back to the suite configuration. - if (item.hierarchy.folderName !== undefined) { - const folderName = getValueOrDerived( - item.hierarchy.folderName, - item.apiItem, - config.hierarchy, - ); - if (folderName !== undefined) { - return folderName; - } - } - - return config.getFolderNameForItem(item.apiItem); +function getFolderNameForItem(item: ApiItemWithHierarchy): string { + return getValueOrDerived(item.hierarchy.folderName, item.apiItem); } /** diff --git a/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts b/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts index f52dbe8a1aec..c455eecc7aae 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts @@ -43,7 +43,7 @@ export function createDocument( return new DocumentNode({ apiItem: documentItem, children: contents, - documentPath: getDocumentPathForApiItem(documentItem, config), + documentPath: getDocumentPathForApiItem(documentItem, config.hierarchy), }); } 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 7a8c14deafdd..396d3cd4f6b6 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 @@ -60,28 +60,6 @@ export interface DocumentationSuiteConfiguration { */ readonly hierarchy: HierarchyConfiguration; - /** - * Generate the desired document name for the provided `ApiItem`. - * - * @remarks Will be invoked for any item configured to generate document or folder level hierarchy via {@link DocumentationSuiteConfiguration.hierarchy}. - * - * Can be further overridden on a per-item-kind basis via {@link DocumentationSuiteConfiguration.hierarchy}. - * - * @param apiItem - The API item in question. - */ - readonly getDocumentNameForItem: (apiItem: ApiItem) => string; - - /** - * Generate the desired folder name for the provided `ApiItem`. - * - * @remarks Will be invoked for any item configured to generate document or folder level hierarchy via {@link DocumentationSuiteConfiguration.hierarchy}. - * - * Can be further overridden on a per-item-kind basis via {@link DocumentationSuiteConfiguration.hierarchy}. - * - * @param apiItem - The API item in question. - */ - readonly getFolderNameForItem: (apiItem: ApiItem) => string; - /** * Optionally provide an override for the URI base used in links generated for the provided `ApiItem`. * @@ -181,6 +159,33 @@ export type DocumentationSuiteOptions = Omit< * {@inheritDoc DocumentationSuiteConfiguration.hierarchy} */ readonly hierarchy?: HierarchyOptions; + + // TODO: rename these + /** + * Generate the desired document name for the provided `ApiItem`. + * + * @remarks Will be invoked for any item configured to generate document or folder level hierarchy via {@link DocumentationSuiteConfiguration.hierarchy}. + * + * Can be further overridden on a per-item-kind basis via {@link DocumentationSuiteConfiguration.hierarchy}. + * + * @param apiItem - The API item in question. + * + * @defaultValue {@link DefaultDocumentationSuiteConfiguration.defaultGetDocumentNameForItem} + */ + readonly getDocumentNameForItem?: (apiItem: ApiItem) => string; + + /** + * Generate the desired folder name for the provided `ApiItem`. + * + * @remarks Will be invoked for any item configured to generate document or folder level hierarchy via {@link DocumentationSuiteConfiguration.hierarchy}. + * + * Can be further overridden on a per-item-kind basis via {@link DocumentationSuiteConfiguration.hierarchy}. + * + * @param apiItem - The API item in question. + * + * @defaultValue {@link DefaultDocumentationSuiteConfiguration.defaultGetFolderNameForItem} + */ + readonly getFolderNameForItem?: (apiItem: ApiItem) => string; }; /** @@ -191,7 +196,7 @@ export type DocumentationSuiteOptions = Omit< // eslint-disable-next-line @typescript-eslint/no-namespace export namespace DefaultDocumentationSuiteConfiguration { /** - * Default {@link DocumentationSuiteConfiguration.getDocumentNameForItem}. + * Default {@link DocumentationSuiteOptions.getDocumentNameForItem}. * * @remarks * Uses the item's scoped and qualified API name, but is handled differently for the following items: @@ -219,7 +224,7 @@ export namespace DefaultDocumentationSuiteConfiguration { } /** - * Default {@link DocumentationSuiteConfiguration.getFolderNameForItem}. + * Default {@link DocumentationSuiteOptions.getFolderNameForItem}. * * @remarks * Uses the item's scoped and qualified API name, but is handled differently for the following items: @@ -350,12 +355,7 @@ export namespace DefaultDocumentationSuiteConfiguration { export function getDocumentationSuiteConfigurationWithDefaults( options: DocumentationSuiteOptions, ): DocumentationSuiteConfiguration { - const hierarchy: HierarchyConfiguration = getHierarchyOptionsWithDefaults(options.hierarchy); - - const config: Mutable< - Omit - > = { - hierarchy, + const config: Omit = { includeTopLevelDocumentHeading: options.includeTopLevelDocumentHeading ?? true, includeBreadcrumb: options.includeBreadcrumb ?? true, getUriBaseOverrideForItem: @@ -375,15 +375,14 @@ export function getDocumentationSuiteConfigurationWithDefaults( minimumReleaseLevel: options.minimumReleaseLevel ?? ReleaseTag.Internal, }; - (config as Mutable).getDocumentNameForItem = + const defaultDocumentName = options.getDocumentNameForItem ?? ((apiItem) => DefaultDocumentationSuiteConfiguration.defaultGetDocumentNameForItem( apiItem, config as DocumentationSuiteConfiguration, )); - - (config as Mutable).getFolderNameForItem = + const defaultFolderName = options.getFolderNameForItem ?? ((apiItem) => DefaultDocumentationSuiteConfiguration.defaultGetFolderNameForItem( @@ -391,5 +390,13 @@ export function getDocumentationSuiteConfigurationWithDefaults( config as DocumentationSuiteConfiguration, )); + const hierarchy: HierarchyConfiguration = getHierarchyOptionsWithDefaults( + options.hierarchy, + defaultDocumentName, + defaultFolderName, + ); + + (config as Mutable).hierarchy = hierarchy; + return config as DocumentationSuiteConfiguration; } diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts index a7be78206744..817654048b13 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts @@ -5,7 +5,7 @@ import { type ApiItem, ApiItemKind } from "@microsoft/api-extractor-model"; -import type { ValidApiItemKind, Mutable } from "../../utilities/index.js"; +import type { ValidApiItemKind } from "../../utilities/index.js"; /** * Kind of documentation suite hierarchy. @@ -70,12 +70,9 @@ export interface DocumentHierarchyProperties { /** * Document name to use for the API item. * - * @defaultValue {@link DocumentationSuiteConfiguration.getFolderNameForItem} + * @defaultValue {@link DocumentationSuiteOptions.getDocumentNameForItem} */ - readonly documentName: - | string - | undefined - | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string | undefined); + readonly documentName: string | ((apiItem: ApiItem) => string); } /** @@ -129,12 +126,9 @@ export interface FolderHierarchyProperties extends DocumentHierarchyProperties { /** * Folder name to use for the API item. * - * @defaultValue {@link DocumentationSuiteConfiguration.getFolderNameForItem} + * @defaultValue {@link DocumentationSuiteOptions.getFolderNameForItem} */ - readonly folderName: - | string - | undefined - | ((apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration) => string | undefined); + readonly folderName: string | ((apiItem: ApiItem) => string); } /** @@ -180,27 +174,25 @@ export type DocumentationHierarchyOptions = /** * Default {@link SectionHierarchyConfiguration} used by the system. */ -export const defaultSectionHierarchyConfig: SectionHierarchyConfiguration = { +const defaultSectionHierarchyOptions = { kind: HierarchyKind.Section, -}; +} satisfies SectionHierarchyOptions; /** * Default {@link DocumentHierarchyConfiguration} used by the system. */ -export const defaultDocumentHierarchyConfig: DocumentHierarchyConfiguration = { +const defaultDocumentHierarchyOptions = { kind: HierarchyKind.Document, - documentName: undefined, // Use suite configuration default. -}; +} satisfies DocumentHierarchyOptions; /** * Default {@link FolderHierarchyConfiguration} used by the system. */ -export const defaultFolderHierarchyConfig: FolderHierarchyConfiguration = { +const defaultFolderHierarchyOptions = { kind: HierarchyKind.Folder, - documentName: undefined, // Use suite configuration default. - documentPlacement: FolderDocumentPlacement.Outside, // TODO - folderName: undefined, // Use suite configuration default. -}; + documentName: undefined, // TODO: "index" + documentPlacement: FolderDocumentPlacement.Outside, // TODO: inside +} satisfies FolderHierarchyOptions; /** * Complete hierarchy configuration by API item kind. @@ -312,64 +304,82 @@ export type HierarchyOptions = { /** * Default {@link HierarchyConfiguration}. */ -const defaultHierarchyConfiguration: HierarchyConfiguration = { +const defaultHierarchyOptions = { [ApiItemKind.Model]: { kind: HierarchyKind.Document, documentName: "index", }, // Items that introduce folder hierarchy: - [ApiItemKind.Namespace]: defaultFolderHierarchyConfig, - [ApiItemKind.Package]: defaultFolderHierarchyConfig, + [ApiItemKind.Namespace]: HierarchyKind.Folder, + [ApiItemKind.Package]: HierarchyKind.Folder, // Items that get their own document, but do not introduce folder hierarchy: - [ApiItemKind.Class]: defaultDocumentHierarchyConfig, - [ApiItemKind.Enum]: defaultSectionHierarchyConfig, // TODO: DocumentHierarchyConfig - [ApiItemKind.EntryPoint]: defaultDocumentHierarchyConfig, - [ApiItemKind.Interface]: defaultDocumentHierarchyConfig, - [ApiItemKind.TypeAlias]: defaultSectionHierarchyConfig, // TODO: DocumentHierarchyConfig + [ApiItemKind.Class]: HierarchyKind.Document, + [ApiItemKind.Enum]: HierarchyKind.Section, // TODO: Document + [ApiItemKind.EntryPoint]: HierarchyKind.Document, + [ApiItemKind.Interface]: HierarchyKind.Document, + [ApiItemKind.TypeAlias]: HierarchyKind.Section, // TODO: Document // Items that get a section under the document representing an ancestor of the API item: - [ApiItemKind.CallSignature]: defaultSectionHierarchyConfig, - [ApiItemKind.Constructor]: defaultSectionHierarchyConfig, - [ApiItemKind.ConstructSignature]: defaultSectionHierarchyConfig, - [ApiItemKind.EnumMember]: defaultSectionHierarchyConfig, - [ApiItemKind.Function]: defaultSectionHierarchyConfig, - [ApiItemKind.IndexSignature]: defaultSectionHierarchyConfig, - [ApiItemKind.Method]: defaultSectionHierarchyConfig, - [ApiItemKind.MethodSignature]: defaultSectionHierarchyConfig, - [ApiItemKind.Property]: defaultSectionHierarchyConfig, - [ApiItemKind.PropertySignature]: defaultSectionHierarchyConfig, - [ApiItemKind.Variable]: defaultSectionHierarchyConfig, -}; + [ApiItemKind.CallSignature]: HierarchyKind.Section, + [ApiItemKind.Constructor]: HierarchyKind.Section, + [ApiItemKind.ConstructSignature]: HierarchyKind.Section, + [ApiItemKind.EnumMember]: HierarchyKind.Section, + [ApiItemKind.Function]: HierarchyKind.Section, + [ApiItemKind.IndexSignature]: HierarchyKind.Section, + [ApiItemKind.Method]: HierarchyKind.Section, + [ApiItemKind.MethodSignature]: HierarchyKind.Section, + [ApiItemKind.Property]: HierarchyKind.Section, + [ApiItemKind.PropertySignature]: HierarchyKind.Section, + [ApiItemKind.Variable]: HierarchyKind.Section, +} as const; /** * Maps an input option to a complete {@link DocumentationHierarchyConfiguration}. */ function mapHierarchyOption( option: HierarchyKind | DocumentationHierarchyOptions, + defaultDocumentName: string | ((apiItem: ApiItem) => string), + defaultFolderName: string | ((apiItem: ApiItem) => string), ): DocumentationHierarchyConfiguration { switch (option) { case HierarchyKind.Section: { - return defaultSectionHierarchyConfig; + return defaultSectionHierarchyOptions; } case HierarchyKind.Document: { - return defaultDocumentHierarchyConfig; + return { + ...defaultDocumentHierarchyOptions, + documentName: defaultDocumentName, + }; } case HierarchyKind.Folder: { - return defaultFolderHierarchyConfig; + return { + ...defaultFolderHierarchyOptions, + documentName: defaultDocumentName, + folderName: defaultFolderName, + }; } default: { const kind = option.kind; switch (kind) { case HierarchyKind.Section: { - return { ...defaultSectionHierarchyConfig, ...option }; + return { ...defaultSectionHierarchyOptions, ...option }; } case HierarchyKind.Document: { - return { ...defaultDocumentHierarchyConfig, ...option }; + return { + ...defaultDocumentHierarchyOptions, + documentName: defaultDocumentName, + ...option, + }; } case HierarchyKind.Folder: { - return { ...defaultFolderHierarchyConfig, ...option }; + return { + ...defaultFolderHierarchyOptions, + documentName: defaultDocumentName, + folderName: defaultFolderName, + ...option, + }; } default: { throw new Error(`Invalid hierarchy configuration kind: ${kind}`); @@ -384,17 +394,19 @@ function mapHierarchyOption( * in the remainder with defaults. */ export function getHierarchyOptionsWithDefaults( - options?: HierarchyOptions, + hierarchyOptions: HierarchyOptions | undefined, + defaultDocumentName: string | ((apiItem: ApiItem) => string), + defaultFolderName: string | ((apiItem: ApiItem) => string), ): HierarchyConfiguration { - if (options === undefined) { - return defaultHierarchyConfiguration; - } - - const result: Mutable = { ...defaultHierarchyConfiguration }; - for (const [key, maybeValue] of Object.entries(options)) { - if (maybeValue !== undefined) { - result[key] = mapHierarchyOption(maybeValue); - } - } - return result; + const options: HierarchyOptions = { + ...defaultHierarchyOptions, + ...hierarchyOptions, + }; + + return Object.fromEntries( + Object.entries(options).map(([key, option]) => [ + key, + mapHierarchyOption(option, defaultDocumentName, defaultFolderName), + ]), + ) as HierarchyConfiguration; } From 181c0c872c70f90b65b8201d1ea3fffa99c52f8e Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Tue, 7 Jan 2025 01:39:23 +0000 Subject: [PATCH 35/54] refactor: Rename properties --- .../api-markdown-documenter.alpha.api.md | 8 +++--- .../api-markdown-documenter.beta.api.md | 8 +++--- .../api-markdown-documenter.public.api.md | 8 +++--- .../configuration/DocumentationSuite.ts | 28 +++++++++---------- .../configuration/Hierarchy.ts | 13 ++++----- 5 files changed, 31 insertions(+), 34 deletions(-) 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 f4009b53e9d7..e39e9580f4ba 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 @@ -217,12 +217,12 @@ export const defaultConsoleLogger: Logger; // @public export namespace DefaultDocumentationSuiteConfiguration { export function defaultGetAlertsForItem(apiItem: ApiItem): string[]; - export function defaultGetDocumentNameForItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; - export function defaultGetFolderNameForItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; export function defaultGetHeadingTextForItem(apiItem: ApiItem): string; export function defaultGetLinkTextForItem(apiItem: ApiItem): string; export function defaultGetUriBaseOverrideForItem(): string | undefined; export function defaultSkipPackage(): boolean; + export function getDocumentName(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; + export function getFolderName(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; } // @public @sealed @@ -334,8 +334,8 @@ export interface DocumentationSuiteConfiguration { // @public export type DocumentationSuiteOptions = Omit, "hierarchy"> & { readonly hierarchy?: HierarchyOptions; - readonly getDocumentNameForItem?: (apiItem: ApiItem) => string; - readonly getFolderNameForItem?: (apiItem: ApiItem) => string; + readonly documentName?: (apiItem: ApiItem) => string; + readonly folderName?: (apiItem: ApiItem) => string; }; // @public 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 863d98ecb14a..c49977e0e0c2 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 @@ -217,12 +217,12 @@ export const defaultConsoleLogger: Logger; // @public export namespace DefaultDocumentationSuiteConfiguration { export function defaultGetAlertsForItem(apiItem: ApiItem): string[]; - export function defaultGetDocumentNameForItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; - export function defaultGetFolderNameForItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; export function defaultGetHeadingTextForItem(apiItem: ApiItem): string; export function defaultGetLinkTextForItem(apiItem: ApiItem): string; export function defaultGetUriBaseOverrideForItem(): string | undefined; export function defaultSkipPackage(): boolean; + export function getDocumentName(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; + export function getFolderName(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; } // @public @sealed @@ -334,8 +334,8 @@ export interface DocumentationSuiteConfiguration { // @public export type DocumentationSuiteOptions = Omit, "hierarchy"> & { readonly hierarchy?: HierarchyOptions; - readonly getDocumentNameForItem?: (apiItem: ApiItem) => string; - readonly getFolderNameForItem?: (apiItem: ApiItem) => string; + readonly documentName?: (apiItem: ApiItem) => string; + readonly folderName?: (apiItem: ApiItem) => string; }; // @public 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 496768583e16..097a00c19706 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 @@ -217,12 +217,12 @@ export const defaultConsoleLogger: Logger; // @public export namespace DefaultDocumentationSuiteConfiguration { export function defaultGetAlertsForItem(apiItem: ApiItem): string[]; - export function defaultGetDocumentNameForItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; - export function defaultGetFolderNameForItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; export function defaultGetHeadingTextForItem(apiItem: ApiItem): string; export function defaultGetLinkTextForItem(apiItem: ApiItem): string; export function defaultGetUriBaseOverrideForItem(): string | undefined; export function defaultSkipPackage(): boolean; + export function getDocumentName(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; + export function getFolderName(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; } // @public @sealed @@ -334,8 +334,8 @@ export interface DocumentationSuiteConfiguration { // @public export type DocumentationSuiteOptions = Omit, "hierarchy"> & { readonly hierarchy?: HierarchyOptions; - readonly getDocumentNameForItem?: (apiItem: ApiItem) => string; - readonly getFolderNameForItem?: (apiItem: ApiItem) => string; + readonly documentName?: (apiItem: ApiItem) => string; + readonly folderName?: (apiItem: ApiItem) => string; }; // @public 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 396d3cd4f6b6..e3dadecbcd71 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 @@ -24,7 +24,7 @@ import { import { createQualifiedDocumentNameForApiItem } from "../ApiItemTransformUtilities.js"; import { - getHierarchyOptionsWithDefaults, + getHierarchyConfigurationWithDefaults, type HierarchyConfiguration, type HierarchyOptions, } from "./Hierarchy.js"; @@ -170,9 +170,9 @@ export type DocumentationSuiteOptions = Omit< * * @param apiItem - The API item in question. * - * @defaultValue {@link DefaultDocumentationSuiteConfiguration.defaultGetDocumentNameForItem} + * @defaultValue {@link DefaultDocumentationSuiteConfiguration.getDocumentName} */ - readonly getDocumentNameForItem?: (apiItem: ApiItem) => string; + readonly documentName?: (apiItem: ApiItem) => string; /** * Generate the desired folder name for the provided `ApiItem`. @@ -183,9 +183,9 @@ export type DocumentationSuiteOptions = Omit< * * @param apiItem - The API item in question. * - * @defaultValue {@link DefaultDocumentationSuiteConfiguration.defaultGetFolderNameForItem} + * @defaultValue {@link DefaultDocumentationSuiteConfiguration.getFolderName} */ - readonly getFolderNameForItem?: (apiItem: ApiItem) => string; + readonly folderName?: (apiItem: ApiItem) => string; }; /** @@ -196,7 +196,7 @@ export type DocumentationSuiteOptions = Omit< // eslint-disable-next-line @typescript-eslint/no-namespace export namespace DefaultDocumentationSuiteConfiguration { /** - * Default {@link DocumentationSuiteOptions.getDocumentNameForItem}. + * Default {@link DocumentationSuiteOptions.documentName}. * * @remarks * Uses the item's scoped and qualified API name, but is handled differently for the following items: @@ -205,7 +205,7 @@ export namespace DefaultDocumentationSuiteConfiguration { * * - Package: Use the unscoped package name. */ - export function defaultGetDocumentNameForItem( + export function getDocumentName( apiItem: ApiItem, config: DocumentationSuiteConfiguration, ): string { @@ -224,14 +224,14 @@ export namespace DefaultDocumentationSuiteConfiguration { } /** - * Default {@link DocumentationSuiteOptions.getFolderNameForItem}. + * Default {@link DocumentationSuiteOptions.folderName}. * * @remarks * Uses the item's scoped and qualified API name, but is handled differently for the following items: * * - Package: Use the unscoped package name. */ - export function defaultGetFolderNameForItem( + export function getFolderName( apiItem: ApiItem, config: DocumentationSuiteConfiguration, ): string { @@ -376,21 +376,21 @@ export function getDocumentationSuiteConfigurationWithDefaults( }; const defaultDocumentName = - options.getDocumentNameForItem ?? + options.documentName ?? ((apiItem) => - DefaultDocumentationSuiteConfiguration.defaultGetDocumentNameForItem( + DefaultDocumentationSuiteConfiguration.getDocumentName( apiItem, config as DocumentationSuiteConfiguration, )); const defaultFolderName = - options.getFolderNameForItem ?? + options.folderName ?? ((apiItem) => - DefaultDocumentationSuiteConfiguration.defaultGetFolderNameForItem( + DefaultDocumentationSuiteConfiguration.getFolderName( apiItem, config as DocumentationSuiteConfiguration, )); - const hierarchy: HierarchyConfiguration = getHierarchyOptionsWithDefaults( + const hierarchy: HierarchyConfiguration = getHierarchyConfigurationWithDefaults( options.hierarchy, defaultDocumentName, defaultFolderName, diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts index 817654048b13..9f72e2858e6f 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts @@ -70,7 +70,7 @@ export interface DocumentHierarchyProperties { /** * Document name to use for the API item. * - * @defaultValue {@link DocumentationSuiteOptions.getDocumentNameForItem} + * @defaultValue {@link DocumentationSuiteOptions.documentName} */ readonly documentName: string | ((apiItem: ApiItem) => string); } @@ -126,7 +126,7 @@ export interface FolderHierarchyProperties extends DocumentHierarchyProperties { /** * Folder name to use for the API item. * - * @defaultValue {@link DocumentationSuiteOptions.getFolderNameForItem} + * @defaultValue {@link DocumentationSuiteOptions.folderName} */ readonly folderName: string | ((apiItem: ApiItem) => string); } @@ -302,13 +302,10 @@ export type HierarchyOptions = { }; /** - * Default {@link HierarchyConfiguration}. + * Default {@link HierarchyOptions}. */ const defaultHierarchyOptions = { - [ApiItemKind.Model]: { - kind: HierarchyKind.Document, - documentName: "index", - }, + [ApiItemKind.Model]: HierarchyKind.Document, // Items that introduce folder hierarchy: [ApiItemKind.Namespace]: HierarchyKind.Folder, @@ -393,7 +390,7 @@ function mapHierarchyOption( * Gets a complete {@link HierarchyConfiguration} using the provided partial configuration, and filling * in the remainder with defaults. */ -export function getHierarchyOptionsWithDefaults( +export function getHierarchyConfigurationWithDefaults( hierarchyOptions: HierarchyOptions | undefined, defaultDocumentName: string | ((apiItem: ApiItem) => string), defaultFolderName: string | ((apiItem: ApiItem) => string), From 9771f7177364e3e5044b41c7ef49b241c975e6d7 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Tue, 7 Jan 2025 01:40:36 +0000 Subject: [PATCH 36/54] test: Add unit tests --- .../configuration/test/Hierarchy.test.ts | 104 ++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 tools/api-markdown-documenter/src/api-item-transforms/configuration/test/Hierarchy.test.ts diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/test/Hierarchy.test.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/test/Hierarchy.test.ts new file mode 100644 index 000000000000..04d10923589b --- /dev/null +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/test/Hierarchy.test.ts @@ -0,0 +1,104 @@ +import { ApiItemKind } from "@microsoft/api-extractor-model"; +import { expect } from "chai"; + +import { + FolderDocumentPlacement, + getHierarchyConfigurationWithDefaults, + HierarchyKind, + type DocumentHierarchyConfiguration, + type FolderHierarchyConfiguration, + type HierarchyConfiguration, + type HierarchyOptions, + type SectionHierarchyConfiguration, +} from "../Hierarchy.js"; + +describe("Hierarchy configuration unit tests", () => { + describe("getHierarchyConfigurationWithDefaults", () => { + const defaultDocumentName = "foo"; + const defaultFolderName = "bar"; + + const expectedDefaultSectionConfig: SectionHierarchyConfiguration = { + kind: HierarchyKind.Section, + }; + + const expectedDefaultDocumentConfig: DocumentHierarchyConfiguration = { + kind: HierarchyKind.Document, + documentName: defaultDocumentName, + }; + + const expectedDefaultFolderConfig: FolderHierarchyConfiguration = { + kind: HierarchyKind.Folder, + documentName: defaultDocumentName, + documentPlacement: FolderDocumentPlacement.Outside, + folderName: defaultFolderName, + }; + + const expectedDefaultHierarchyConfig: HierarchyConfiguration = { + // Items that introduce folder hierarchy: + [ApiItemKind.Namespace]: expectedDefaultFolderConfig, + [ApiItemKind.Package]: expectedDefaultFolderConfig, + + // Items that get their own document, but do not introduce folder hierarchy: + [ApiItemKind.Class]: expectedDefaultDocumentConfig, + [ApiItemKind.Enum]: expectedDefaultSectionConfig, // TODO: Document + [ApiItemKind.EntryPoint]: expectedDefaultDocumentConfig, + [ApiItemKind.Interface]: expectedDefaultDocumentConfig, + [ApiItemKind.Model]: expectedDefaultDocumentConfig, + [ApiItemKind.TypeAlias]: expectedDefaultSectionConfig, // TODO: Document + + // Items that get a section under the document representing an ancestor of the API item: + [ApiItemKind.CallSignature]: expectedDefaultSectionConfig, + [ApiItemKind.Constructor]: expectedDefaultSectionConfig, + [ApiItemKind.ConstructSignature]: expectedDefaultSectionConfig, + [ApiItemKind.EnumMember]: expectedDefaultSectionConfig, + [ApiItemKind.Function]: expectedDefaultSectionConfig, + [ApiItemKind.IndexSignature]: expectedDefaultSectionConfig, + [ApiItemKind.Method]: expectedDefaultSectionConfig, + [ApiItemKind.MethodSignature]: expectedDefaultSectionConfig, + [ApiItemKind.Property]: expectedDefaultSectionConfig, + [ApiItemKind.PropertySignature]: expectedDefaultSectionConfig, + [ApiItemKind.Variable]: expectedDefaultSectionConfig, + }; + + it("Empty input", () => { + const result = getHierarchyConfigurationWithDefaults( + undefined, + defaultDocumentName, + defaultFolderName, + ); + + expect(result).to.deep.equal(expectedDefaultHierarchyConfig); + }); + + it("Input contains overrides", () => { + const input: HierarchyOptions = { + [ApiItemKind.Class]: HierarchyKind.Section, + [ApiItemKind.Interface]: { + kind: HierarchyKind.Folder, + folderName: "baz", + }, + }; + + const result = getHierarchyConfigurationWithDefaults( + input, + defaultDocumentName, + defaultFolderName, + ); + + const expected: HierarchyConfiguration = { + ...expectedDefaultHierarchyConfig, + [ApiItemKind.Class]: { + kind: HierarchyKind.Section, + }, + [ApiItemKind.Interface]: { + kind: HierarchyKind.Folder, + documentName: defaultDocumentName, + documentPlacement: FolderDocumentPlacement.Outside, + folderName: "baz", + }, + }; + + expect(result).to.deep.equal(expected); + }); + }); +}); From e6b39dcdbd4c7eef93f757d79baac20332e1bc02 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Tue, 7 Jan 2025 01:47:27 +0000 Subject: [PATCH 37/54] refactor: Make input options optional --- .../configuration/DocumentationSuite.ts | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) 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 e3dadecbcd71..d2577fa1baf2 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 @@ -353,37 +353,37 @@ export namespace DefaultDocumentationSuiteConfiguration { * in the remainder with the documented defaults. */ export function getDocumentationSuiteConfigurationWithDefaults( - options: DocumentationSuiteOptions, + options?: DocumentationSuiteOptions, ): DocumentationSuiteConfiguration { const config: Omit = { - includeTopLevelDocumentHeading: options.includeTopLevelDocumentHeading ?? true, - includeBreadcrumb: options.includeBreadcrumb ?? true, + includeTopLevelDocumentHeading: options?.includeTopLevelDocumentHeading ?? true, + includeBreadcrumb: options?.includeBreadcrumb ?? true, getUriBaseOverrideForItem: - options.getUriBaseOverrideForItem ?? + options?.getUriBaseOverrideForItem ?? DefaultDocumentationSuiteConfiguration.defaultGetUriBaseOverrideForItem, getHeadingTextForItem: - options.getHeadingTextForItem ?? + options?.getHeadingTextForItem ?? DefaultDocumentationSuiteConfiguration.defaultGetHeadingTextForItem, getLinkTextForItem: - options.getLinkTextForItem ?? + options?.getLinkTextForItem ?? DefaultDocumentationSuiteConfiguration.defaultGetLinkTextForItem, getAlertsForItem: - options.getAlertsForItem ?? + options?.getAlertsForItem ?? DefaultDocumentationSuiteConfiguration.defaultGetAlertsForItem, skipPackage: - options.skipPackage ?? DefaultDocumentationSuiteConfiguration.defaultSkipPackage, - minimumReleaseLevel: options.minimumReleaseLevel ?? ReleaseTag.Internal, + options?.skipPackage ?? DefaultDocumentationSuiteConfiguration.defaultSkipPackage, + minimumReleaseLevel: options?.minimumReleaseLevel ?? ReleaseTag.Internal, }; const defaultDocumentName = - options.documentName ?? + options?.documentName ?? ((apiItem) => DefaultDocumentationSuiteConfiguration.getDocumentName( apiItem, config as DocumentationSuiteConfiguration, )); const defaultFolderName = - options.folderName ?? + options?.folderName ?? ((apiItem) => DefaultDocumentationSuiteConfiguration.getFolderName( apiItem, @@ -391,7 +391,7 @@ export function getDocumentationSuiteConfigurationWithDefaults( )); const hierarchy: HierarchyConfiguration = getHierarchyConfigurationWithDefaults( - options.hierarchy, + options?.hierarchy, defaultDocumentName, defaultFolderName, ); From 1db03994557e5e71cc0fa32d6e22e6c27c907bdd Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Tue, 7 Jan 2025 19:12:24 +0000 Subject: [PATCH 38/54] refactor: Variable renames and comment --- .../configuration/DocumentationSuite.ts | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) 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 d2577fa1baf2..a1d366d20384 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 @@ -218,6 +218,7 @@ export namespace DefaultDocumentationSuiteConfiguration { return getFileSafeNameForApiItemName(getUnscopedPackageName(apiItem as ApiPackage)); } default: { + // Let the system generate a unique name that accounts for folder hierarchy. return createQualifiedDocumentNameForApiItem(apiItem, config); } } @@ -375,14 +376,14 @@ export function getDocumentationSuiteConfigurationWithDefaults( minimumReleaseLevel: options?.minimumReleaseLevel ?? ReleaseTag.Internal, }; - const defaultDocumentName = + const documentName = options?.documentName ?? ((apiItem) => DefaultDocumentationSuiteConfiguration.getDocumentName( apiItem, config as DocumentationSuiteConfiguration, )); - const defaultFolderName = + const folderName = options?.folderName ?? ((apiItem) => DefaultDocumentationSuiteConfiguration.getFolderName( @@ -392,8 +393,8 @@ export function getDocumentationSuiteConfigurationWithDefaults( const hierarchy: HierarchyConfiguration = getHierarchyConfigurationWithDefaults( options?.hierarchy, - defaultDocumentName, - defaultFolderName, + documentName, + folderName, ); (config as Mutable).hierarchy = hierarchy; From 8119e7f015d47f9711d07bd78bf3e8c3db1fdf02 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Tue, 7 Jan 2025 19:12:33 +0000 Subject: [PATCH 39/54] docs: Add missing copyright notice --- .../api-item-transforms/configuration/test/Hierarchy.test.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/test/Hierarchy.test.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/test/Hierarchy.test.ts index 04d10923589b..8b87f6ad0235 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/test/Hierarchy.test.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/test/Hierarchy.test.ts @@ -1,3 +1,8 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + import { ApiItemKind } from "@microsoft/api-extractor-model"; import { expect } from "chai"; From ff8de155a53dc22be2fe7059e1db817145ffdc37 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Tue, 7 Jan 2025 19:12:49 +0000 Subject: [PATCH 40/54] test: Add unit test --- .../test/DocumentationSuite.test.ts | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 tools/api-markdown-documenter/src/api-item-transforms/configuration/test/DocumentationSuite.test.ts diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/test/DocumentationSuite.test.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/test/DocumentationSuite.test.ts new file mode 100644 index 000000000000..fda3b20fcf15 --- /dev/null +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/test/DocumentationSuite.test.ts @@ -0,0 +1,73 @@ +/*! + * Copyright (c) Microsoft Corporation and contributors. All rights reserved. + * Licensed under the MIT License. + */ + +import { ApiItemKind, type ApiItem } from "@microsoft/api-extractor-model"; +import { assert, expect } from "chai"; + +import { getValueOrDerived } from "../../../utilities/index.js"; +import { + getDocumentationSuiteConfigurationWithDefaults, + type DocumentationSuiteOptions, +} from "../DocumentationSuite.js"; +import { HierarchyKind } from "../Hierarchy.js"; + +describe("Documentation Suite configuration unit tests", () => { + describe("getDocumentationSuiteConfigurationWithDefaults", () => { + it("Hierarchy settings are applied correctly", () => { + const input: DocumentationSuiteOptions = { + hierarchy: { + [ApiItemKind.Variable]: HierarchyKind.Section, + [ApiItemKind.TypeAlias]: HierarchyKind.Document, + [ApiItemKind.Class]: { + kind: HierarchyKind.Document, + documentName: "foo", + }, + [ApiItemKind.Interface]: { + kind: HierarchyKind.Folder, + documentName: (apiItem) => `${apiItem.displayName}!`, + }, + }, + documentName: (apiItem) => `d_${apiItem.displayName}`, + folderName: (apiItem) => `f_${apiItem.displayName}`, + }; + + const config = getDocumentationSuiteConfigurationWithDefaults(input); + + const variableHierarchy = config.hierarchy[ApiItemKind.Variable]; + assert(variableHierarchy.kind === HierarchyKind.Section); + + const typeAliasItem = { + kind: ApiItemKind.TypeAlias, + displayName: "type-alias", + } as unknown as ApiItem; + const typeAliasHierarchy = config.hierarchy[ApiItemKind.TypeAlias]; + assert(typeAliasHierarchy.kind === HierarchyKind.Document); + expect(getValueOrDerived(typeAliasHierarchy.documentName, typeAliasItem)).to.equal( + "d_type-alias", + ); + + const classItem = { + kind: ApiItemKind.Class, + displayName: "class", + } as unknown as ApiItem; + const classHierarchy = config.hierarchy[ApiItemKind.Class]; + assert(classHierarchy.kind === HierarchyKind.Document); + expect(getValueOrDerived(classHierarchy.documentName, classItem)).to.equal("foo"); + + const interfaceItem = { + kind: ApiItemKind.Interface, + displayName: "interface", + } as unknown as ApiItem; + const interfaceHierarchy = config.hierarchy[ApiItemKind.Interface]; + assert(interfaceHierarchy.kind === HierarchyKind.Folder); + expect(getValueOrDerived(interfaceHierarchy.documentName, interfaceItem)).to.equal( + "interface!", + ); + expect(getValueOrDerived(interfaceHierarchy.folderName, interfaceItem)).to.equal( + "f_interface", + ); + }); + }); +}); From 46364b1250be7f97c18e4dd00b73f4c950056c94 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Tue, 7 Jan 2025 20:13:26 +0000 Subject: [PATCH 41/54] docs: Update comments --- .../api-item-transforms/configuration/DocumentationSuite.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 a1d366d20384..f58d0dda084f 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 @@ -168,7 +168,7 @@ export type DocumentationSuiteOptions = Omit< * * Can be further overridden on a per-item-kind basis via {@link DocumentationSuiteConfiguration.hierarchy}. * - * @param apiItem - The API item in question. + * @param apiItem - The API item for which the document name is being generated. * * @defaultValue {@link DefaultDocumentationSuiteConfiguration.getDocumentName} */ @@ -181,7 +181,7 @@ export type DocumentationSuiteOptions = Omit< * * Can be further overridden on a per-item-kind basis via {@link DocumentationSuiteConfiguration.hierarchy}. * - * @param apiItem - The API item in question. + * @param apiItem - The API item for which the folder name is being generated. * * @defaultValue {@link DefaultDocumentationSuiteConfiguration.getFolderName} */ From 0b316fb7105e1a5d5fbd4f8bce78edba6a9582f0 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Tue, 7 Jan 2025 21:14:10 +0000 Subject: [PATCH 42/54] docs: Remove stale TODO --- .../src/api-item-transforms/configuration/DocumentationSuite.ts | 1 - 1 file changed, 1 deletion(-) 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 f58d0dda084f..0ce67a8947f2 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 @@ -160,7 +160,6 @@ export type DocumentationSuiteOptions = Omit< */ readonly hierarchy?: HierarchyOptions; - // TODO: rename these /** * Generate the desired document name for the provided `ApiItem`. * From 05e70b60aaa629c18fcb35d9b24d8cb4907cee15 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 8 Jan 2025 01:25:45 +0000 Subject: [PATCH 43/54] refactor: Further simplify hierarchy setup --- .../api-markdown-documenter.alpha.api.md | 57 ++-- .../api-markdown-documenter.beta.api.md | 57 ++-- .../api-markdown-documenter.public.api.md | 57 ++-- .../ApiItemTransformUtilities.ts | 33 +-- .../configuration/DocumentationSuite.ts | 115 +------- .../configuration/Hierarchy.ts | 274 +++++++++--------- .../configuration/index.ts | 6 - .../test/DocumentationSuite.test.ts | 73 ----- .../configuration/test/Hierarchy.test.ts | 109 ------- .../src/api-item-transforms/index.ts | 6 - tools/api-markdown-documenter/src/index.ts | 6 - .../src/test/EndToEndTestUtilities.ts | 26 +- 12 files changed, 227 insertions(+), 592 deletions(-) delete mode 100644 tools/api-markdown-documenter/src/api-item-transforms/configuration/test/DocumentationSuite.test.ts delete mode 100644 tools/api-markdown-documenter/src/api-item-transforms/configuration/test/Hierarchy.test.ts 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 e39e9580f4ba..50b6389fb250 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 @@ -188,7 +188,7 @@ function createExamplesSection(apiItem: ApiItem, config: ApiItemTransformationCo function createParametersSection(apiFunctionLike: ApiFunctionLike, config: ApiItemTransformationConfiguration): SectionNode | undefined; // @public -function createQualifiedDocumentNameForApiItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; +function createQualifiedDocumentNameForApiItem(apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration): string; // @public function createRemarksSection(apiItem: ApiItem, config: ApiItemTransformationConfiguration): SectionNode | undefined; @@ -221,21 +221,16 @@ export namespace DefaultDocumentationSuiteConfiguration { export function defaultGetLinkTextForItem(apiItem: ApiItem): string; export function defaultGetUriBaseOverrideForItem(): string | undefined; export function defaultSkipPackage(): boolean; - export function getDocumentName(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; - export function getFolderName(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; } // @public @sealed export type DocumentationHierarchyConfiguration = SectionHierarchyConfiguration | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; -// @public +// @public @sealed export interface DocumentationHierarchyConfigurationBase { readonly kind: THierarchyKind; } -// @public @sealed -export type DocumentationHierarchyOptions = SectionHierarchyOptions | DocumentHierarchyOptions | FolderHierarchyOptions; - // @public export interface DocumentationLiteralNode extends Literal, DocumentationNode { readonly isLiteral: true; @@ -334,20 +329,10 @@ export interface DocumentationSuiteConfiguration { // @public export type DocumentationSuiteOptions = Omit, "hierarchy"> & { readonly hierarchy?: HierarchyOptions; - readonly documentName?: (apiItem: ApiItem) => string; - readonly folderName?: (apiItem: ApiItem) => string; }; -// @public -export type DocumentHierarchyConfiguration = DocumentationHierarchyConfigurationBase & DocumentHierarchyProperties; - -// @public -export type DocumentHierarchyOptions = DocumentationHierarchyConfigurationBase & Partial; - -// @public -export interface DocumentHierarchyProperties { - readonly documentName: string | ((apiItem: ApiItem) => string); -} +// @public @sealed +export type DocumentHierarchyConfiguration = DocumentationHierarchyConfigurationBase; // @public export class DocumentNode implements Parent, DocumentNodeProps { @@ -414,16 +399,9 @@ export enum FolderDocumentPlacement { } // @public @sealed -export type FolderHierarchyConfiguration = DocumentationHierarchyConfigurationBase & FolderHierarchyProperties; - -// @public @sealed -export type FolderHierarchyOptions = DocumentationHierarchyConfigurationBase & Partial; - -// @public @sealed -export interface FolderHierarchyProperties extends DocumentHierarchyProperties { +export type FolderHierarchyConfiguration = DocumentationHierarchyConfigurationBase & { readonly documentPlacement: FolderDocumentPlacement; - readonly folderName: string | ((apiItem: ApiItem) => string); -} +}; // @public export function getApiItemTransformationConfigurationWithDefaults(options: ApiItemTransformationOptions): ApiItemTransformationConfiguration; @@ -500,22 +478,26 @@ export type HierarchyConfiguration = { [ApiItemKind.Model]: DocumentHierarchyConfiguration; [ApiItemKind.Package]: DocumentHierarchyConfiguration | FolderHierarchyConfiguration; [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; + readonly getDocumentName: (apiItem: ApiItem, config: HierarchyConfiguration) => string; + readonly getFolderName: (apiItem: ApiItem, config: HierarchyConfiguration) => string; }; // @public export enum HierarchyKind { - Document = "document", - Folder = "folder", - Section = "section" + Document = "Document", + Folder = "Folder", + Section = "Section" } // @public export type HierarchyOptions = { - [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyOptions; + [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyConfiguration; } & { - [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyOptions; - [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyOptions | FolderHierarchyOptions; - [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyOptions; + [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; + [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + readonly getDocumentName?: (apiItem: ApiItem, config: HierarchyConfiguration) => string; + readonly getFolderName?: (apiItem: ApiItem, config: HierarchyConfiguration) => string; }; // @public @@ -766,12 +748,9 @@ function renderNode(node: DocumentationNode, writer: DocumentWriter, context: Ma // @public function renderNodes(children: DocumentationNode[], writer: DocumentWriter, childContext: MarkdownRenderContext): void; -// @public +// @public @sealed export type SectionHierarchyConfiguration = DocumentationHierarchyConfigurationBase; -// @public -export type SectionHierarchyOptions = DocumentationHierarchyConfigurationBase; - // @public export class SectionNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { constructor(children: DocumentationNode[], heading?: HeadingNode); 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 c49977e0e0c2..011160c4bacb 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 @@ -188,7 +188,7 @@ function createExamplesSection(apiItem: ApiItem, config: ApiItemTransformationCo function createParametersSection(apiFunctionLike: ApiFunctionLike, config: ApiItemTransformationConfiguration): SectionNode | undefined; // @public -function createQualifiedDocumentNameForApiItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; +function createQualifiedDocumentNameForApiItem(apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration): string; // @public function createRemarksSection(apiItem: ApiItem, config: ApiItemTransformationConfiguration): SectionNode | undefined; @@ -221,21 +221,16 @@ export namespace DefaultDocumentationSuiteConfiguration { export function defaultGetLinkTextForItem(apiItem: ApiItem): string; export function defaultGetUriBaseOverrideForItem(): string | undefined; export function defaultSkipPackage(): boolean; - export function getDocumentName(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; - export function getFolderName(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; } // @public @sealed export type DocumentationHierarchyConfiguration = SectionHierarchyConfiguration | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; -// @public +// @public @sealed export interface DocumentationHierarchyConfigurationBase { readonly kind: THierarchyKind; } -// @public @sealed -export type DocumentationHierarchyOptions = SectionHierarchyOptions | DocumentHierarchyOptions | FolderHierarchyOptions; - // @public export interface DocumentationLiteralNode extends Literal, DocumentationNode { readonly isLiteral: true; @@ -334,20 +329,10 @@ export interface DocumentationSuiteConfiguration { // @public export type DocumentationSuiteOptions = Omit, "hierarchy"> & { readonly hierarchy?: HierarchyOptions; - readonly documentName?: (apiItem: ApiItem) => string; - readonly folderName?: (apiItem: ApiItem) => string; }; -// @public -export type DocumentHierarchyConfiguration = DocumentationHierarchyConfigurationBase & DocumentHierarchyProperties; - -// @public -export type DocumentHierarchyOptions = DocumentationHierarchyConfigurationBase & Partial; - -// @public -export interface DocumentHierarchyProperties { - readonly documentName: string | ((apiItem: ApiItem) => string); -} +// @public @sealed +export type DocumentHierarchyConfiguration = DocumentationHierarchyConfigurationBase; // @public export class DocumentNode implements Parent, DocumentNodeProps { @@ -414,16 +399,9 @@ export enum FolderDocumentPlacement { } // @public @sealed -export type FolderHierarchyConfiguration = DocumentationHierarchyConfigurationBase & FolderHierarchyProperties; - -// @public @sealed -export type FolderHierarchyOptions = DocumentationHierarchyConfigurationBase & Partial; - -// @public @sealed -export interface FolderHierarchyProperties extends DocumentHierarchyProperties { +export type FolderHierarchyConfiguration = DocumentationHierarchyConfigurationBase & { readonly documentPlacement: FolderDocumentPlacement; - readonly folderName: string | ((apiItem: ApiItem) => string); -} +}; // @public export function getApiItemTransformationConfigurationWithDefaults(options: ApiItemTransformationOptions): ApiItemTransformationConfiguration; @@ -500,22 +478,26 @@ export type HierarchyConfiguration = { [ApiItemKind.Model]: DocumentHierarchyConfiguration; [ApiItemKind.Package]: DocumentHierarchyConfiguration | FolderHierarchyConfiguration; [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; + readonly getDocumentName: (apiItem: ApiItem, config: HierarchyConfiguration) => string; + readonly getFolderName: (apiItem: ApiItem, config: HierarchyConfiguration) => string; }; // @public export enum HierarchyKind { - Document = "document", - Folder = "folder", - Section = "section" + Document = "Document", + Folder = "Folder", + Section = "Section" } // @public export type HierarchyOptions = { - [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyOptions; + [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyConfiguration; } & { - [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyOptions; - [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyOptions | FolderHierarchyOptions; - [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyOptions; + [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; + [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + readonly getDocumentName?: (apiItem: ApiItem, config: HierarchyConfiguration) => string; + readonly getFolderName?: (apiItem: ApiItem, config: HierarchyConfiguration) => string; }; // @public @@ -752,12 +734,9 @@ function renderNode(node: DocumentationNode, writer: DocumentWriter, context: Ma // @public function renderNodes(children: DocumentationNode[], writer: DocumentWriter, childContext: MarkdownRenderContext): void; -// @public +// @public @sealed export type SectionHierarchyConfiguration = DocumentationHierarchyConfigurationBase; -// @public -export type SectionHierarchyOptions = DocumentationHierarchyConfigurationBase; - // @public export class SectionNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { constructor(children: DocumentationNode[], heading?: HeadingNode); 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 097a00c19706..e7cc51a1d0bc 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 @@ -188,7 +188,7 @@ function createExamplesSection(apiItem: ApiItem, config: ApiItemTransformationCo function createParametersSection(apiFunctionLike: ApiFunctionLike, config: ApiItemTransformationConfiguration): SectionNode | undefined; // @public -function createQualifiedDocumentNameForApiItem(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; +function createQualifiedDocumentNameForApiItem(apiItem: ApiItem, hierarchyConfig: HierarchyConfiguration): string; // @public function createRemarksSection(apiItem: ApiItem, config: ApiItemTransformationConfiguration): SectionNode | undefined; @@ -221,21 +221,16 @@ export namespace DefaultDocumentationSuiteConfiguration { export function defaultGetLinkTextForItem(apiItem: ApiItem): string; export function defaultGetUriBaseOverrideForItem(): string | undefined; export function defaultSkipPackage(): boolean; - export function getDocumentName(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; - export function getFolderName(apiItem: ApiItem, config: DocumentationSuiteConfiguration): string; } // @public @sealed export type DocumentationHierarchyConfiguration = SectionHierarchyConfiguration | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; -// @public +// @public @sealed export interface DocumentationHierarchyConfigurationBase { readonly kind: THierarchyKind; } -// @public @sealed -export type DocumentationHierarchyOptions = SectionHierarchyOptions | DocumentHierarchyOptions | FolderHierarchyOptions; - // @public export interface DocumentationLiteralNode extends Literal, DocumentationNode { readonly isLiteral: true; @@ -334,20 +329,10 @@ export interface DocumentationSuiteConfiguration { // @public export type DocumentationSuiteOptions = Omit, "hierarchy"> & { readonly hierarchy?: HierarchyOptions; - readonly documentName?: (apiItem: ApiItem) => string; - readonly folderName?: (apiItem: ApiItem) => string; }; -// @public -export type DocumentHierarchyConfiguration = DocumentationHierarchyConfigurationBase & DocumentHierarchyProperties; - -// @public -export type DocumentHierarchyOptions = DocumentationHierarchyConfigurationBase & Partial; - -// @public -export interface DocumentHierarchyProperties { - readonly documentName: string | ((apiItem: ApiItem) => string); -} +// @public @sealed +export type DocumentHierarchyConfiguration = DocumentationHierarchyConfigurationBase; // @public export class DocumentNode implements Parent, DocumentNodeProps { @@ -414,16 +399,9 @@ export enum FolderDocumentPlacement { } // @public @sealed -export type FolderHierarchyConfiguration = DocumentationHierarchyConfigurationBase & FolderHierarchyProperties; - -// @public @sealed -export type FolderHierarchyOptions = DocumentationHierarchyConfigurationBase & Partial; - -// @public @sealed -export interface FolderHierarchyProperties extends DocumentHierarchyProperties { +export type FolderHierarchyConfiguration = DocumentationHierarchyConfigurationBase & { readonly documentPlacement: FolderDocumentPlacement; - readonly folderName: string | ((apiItem: ApiItem) => string); -} +}; // @public export function getApiItemTransformationConfigurationWithDefaults(options: ApiItemTransformationOptions): ApiItemTransformationConfiguration; @@ -500,22 +478,26 @@ export type HierarchyConfiguration = { [ApiItemKind.Model]: DocumentHierarchyConfiguration; [ApiItemKind.Package]: DocumentHierarchyConfiguration | FolderHierarchyConfiguration; [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; + readonly getDocumentName: (apiItem: ApiItem, config: HierarchyConfiguration) => string; + readonly getFolderName: (apiItem: ApiItem, config: HierarchyConfiguration) => string; }; // @public export enum HierarchyKind { - Document = "document", - Folder = "folder", - Section = "section" + Document = "Document", + Folder = "Folder", + Section = "Section" } // @public export type HierarchyOptions = { - [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyOptions; + [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyConfiguration; } & { - [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyOptions; - [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyOptions | FolderHierarchyOptions; - [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyOptions; + [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; + [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + readonly getDocumentName?: (apiItem: ApiItem, config: HierarchyConfiguration) => string; + readonly getFolderName?: (apiItem: ApiItem, config: HierarchyConfiguration) => string; }; // @public @@ -730,12 +712,9 @@ function renderNode(node: DocumentationNode, writer: DocumentWriter, context: Ma // @public function renderNodes(children: DocumentationNode[], writer: DocumentWriter, childContext: MarkdownRenderContext): void; -// @public +// @public @sealed export type SectionHierarchyConfiguration = DocumentationHierarchyConfigurationBase; -// @public -export type SectionHierarchyOptions = DocumentationHierarchyConfigurationBase; - // @public export class SectionNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { constructor(children: DocumentationNode[], heading?: HeadingNode); 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 5f718f7a0b1c..d78ec257c746 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts @@ -15,7 +15,6 @@ import { getFileSafeNameForApiItem, getReleaseTag, type ValidApiItemKind, - getValueOrDerived, } from "../utilities/index.js"; import { @@ -26,7 +25,6 @@ import { type FolderHierarchyConfiguration, type DocumentationHierarchyConfiguration, type HierarchyConfiguration, - type DocumentationSuiteConfiguration, } from "./configuration/index.js"; /** @@ -180,7 +178,10 @@ export function getDocumentPathForApiItem( hierarchyConfig: HierarchyConfiguration, ): string { const targetDocument = getFirstAncestorWithOwnDocument(apiItem, hierarchyConfig); - const targetDocumentName = getDocumentNameForItem(targetDocument); + const targetDocumentName = hierarchyConfig.getDocumentName( + targetDocument.apiItem, + hierarchyConfig, + ); const pathSegments: string[] = []; @@ -190,10 +191,7 @@ export function getDocumentPathForApiItem( targetDocument.hierarchy.kind === HierarchyKind.Folder && targetDocument.hierarchy.documentPlacement === FolderDocumentPlacement.Inside ) { - const folderName = getFolderNameForItem({ - apiItem: targetDocument.apiItem, - hierarchy: targetDocument.hierarchy, - }); + const folderName = hierarchyConfig.getFolderName(targetDocument.apiItem, hierarchyConfig); pathSegments.push(`${folderName}/${targetDocumentName}`); } else { pathSegments.push(targetDocumentName); @@ -205,10 +203,7 @@ export function getDocumentPathForApiItem( const currentItemHierarchy = hierarchyConfig[currentItemKind]; // Push path segments for all folders in the hierarchy if (currentItemHierarchy.kind === HierarchyKind.Folder) { - const folderName = getFolderNameForItem({ - apiItem: currentItem, - hierarchy: currentItemHierarchy, - }); + const folderName = hierarchyConfig.getFolderName(currentItem, hierarchyConfig); pathSegments.push(folderName); } currentItem = getFilteredParent(currentItem); @@ -220,27 +215,17 @@ export function getDocumentPathForApiItem( return pathSegments.join("/"); } -function getDocumentNameForItem( - item: ApiItemWithHierarchy, -): string { - return getValueOrDerived(item.hierarchy.documentName, item.apiItem); -} - -function getFolderNameForItem(item: ApiItemWithHierarchy): string { - return getValueOrDerived(item.hierarchy.folderName, item.apiItem); -} - /** * Generates a qualified document name for the specified API item aimed at preventing name collisions, accounting for folder hierarchy. * * @param apiItem - The API item for which we are generating a qualified name - * @param config - See {@link DocumentationSuiteConfiguration} + * @param hierarchyConfig - See {@link HierarchyConfiguration} * * @public */ export function createQualifiedDocumentNameForApiItem( apiItem: ApiItem, - config: DocumentationSuiteConfiguration, + hierarchyConfig: HierarchyConfiguration, ): string { const apiItemKind = getApiItemKind(apiItem); let documentName = getFileSafeNameForApiItem(apiItem); @@ -260,7 +245,7 @@ export function createQualifiedDocumentNameForApiItem( while ( currentItem !== undefined && currentItem.kind !== "Model" && - config.hierarchy[getApiItemKind(currentItem)].kind !== HierarchyKind.Folder + hierarchyConfig[getApiItemKind(currentItem)].kind !== HierarchyKind.Folder ) { documentName = `${getFileSafeNameForApiItem(currentItem)}-${documentName}`; currentItem = getFilteredParent(currentItem); 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 0ce67a8947f2..9393f59165c5 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 @@ -14,14 +14,10 @@ import { import { getApiItemKind, getConciseSignature, - getFileSafeNameForApiItemName, getReleaseTag, getSingleLineExcerptText, - getUnscopedPackageName, isDeprecated, - type Mutable, } from "../../utilities/index.js"; -import { createQualifiedDocumentNameForApiItem } from "../ApiItemTransformUtilities.js"; import { getHierarchyConfigurationWithDefaults, @@ -159,32 +155,6 @@ export type DocumentationSuiteOptions = Omit< * {@inheritDoc DocumentationSuiteConfiguration.hierarchy} */ readonly hierarchy?: HierarchyOptions; - - /** - * Generate the desired document name for the provided `ApiItem`. - * - * @remarks Will be invoked for any item configured to generate document or folder level hierarchy via {@link DocumentationSuiteConfiguration.hierarchy}. - * - * Can be further overridden on a per-item-kind basis via {@link DocumentationSuiteConfiguration.hierarchy}. - * - * @param apiItem - The API item for which the document name is being generated. - * - * @defaultValue {@link DefaultDocumentationSuiteConfiguration.getDocumentName} - */ - readonly documentName?: (apiItem: ApiItem) => string; - - /** - * Generate the desired folder name for the provided `ApiItem`. - * - * @remarks Will be invoked for any item configured to generate document or folder level hierarchy via {@link DocumentationSuiteConfiguration.hierarchy}. - * - * Can be further overridden on a per-item-kind basis via {@link DocumentationSuiteConfiguration.hierarchy}. - * - * @param apiItem - The API item for which the folder name is being generated. - * - * @defaultValue {@link DefaultDocumentationSuiteConfiguration.getFolderName} - */ - readonly folderName?: (apiItem: ApiItem) => string; }; /** @@ -194,59 +164,6 @@ export type DocumentationSuiteOptions = Omit< */ // eslint-disable-next-line @typescript-eslint/no-namespace export namespace DefaultDocumentationSuiteConfiguration { - /** - * Default {@link DocumentationSuiteOptions.documentName}. - * - * @remarks - * Uses the item's scoped and qualified API name, but is handled differently for the following items: - * - * - Model: "index" - * - * - Package: Use the unscoped package name. - */ - export function getDocumentName( - apiItem: ApiItem, - config: DocumentationSuiteConfiguration, - ): string { - const kind = getApiItemKind(apiItem); - switch (kind) { - case ApiItemKind.Model: { - return "index"; - } - case ApiItemKind.Package: { - return getFileSafeNameForApiItemName(getUnscopedPackageName(apiItem as ApiPackage)); - } - default: { - // Let the system generate a unique name that accounts for folder hierarchy. - return createQualifiedDocumentNameForApiItem(apiItem, config); - } - } - } - - /** - * Default {@link DocumentationSuiteOptions.folderName}. - * - * @remarks - * Uses the item's scoped and qualified API name, but is handled differently for the following items: - * - * - Package: Use the unscoped package name. - */ - export function getFolderName( - apiItem: ApiItem, - config: DocumentationSuiteConfiguration, - ): string { - const kind = getApiItemKind(apiItem); - switch (kind) { - case ApiItemKind.Package: { - return getFileSafeNameForApiItemName(getUnscopedPackageName(apiItem as ApiPackage)); - } - default: { - // Let the system generate a unique name that accounts for folder hierarchy. - return createQualifiedDocumentNameForApiItem(apiItem, config); - } - } - } - /** * Default {@link DocumentationSuiteConfiguration.getUriBaseOverrideForItem}. * @@ -355,7 +272,12 @@ export namespace DefaultDocumentationSuiteConfiguration { export function getDocumentationSuiteConfigurationWithDefaults( options?: DocumentationSuiteOptions, ): DocumentationSuiteConfiguration { - const config: Omit = { + const hierarchy: HierarchyConfiguration = getHierarchyConfigurationWithDefaults( + options?.hierarchy, + ); + + return { + hierarchy, includeTopLevelDocumentHeading: options?.includeTopLevelDocumentHeading ?? true, includeBreadcrumb: options?.includeBreadcrumb ?? true, getUriBaseOverrideForItem: @@ -374,29 +296,4 @@ export function getDocumentationSuiteConfigurationWithDefaults( options?.skipPackage ?? DefaultDocumentationSuiteConfiguration.defaultSkipPackage, minimumReleaseLevel: options?.minimumReleaseLevel ?? ReleaseTag.Internal, }; - - const documentName = - options?.documentName ?? - ((apiItem) => - DefaultDocumentationSuiteConfiguration.getDocumentName( - apiItem, - config as DocumentationSuiteConfiguration, - )); - const folderName = - options?.folderName ?? - ((apiItem) => - DefaultDocumentationSuiteConfiguration.getFolderName( - apiItem, - config as DocumentationSuiteConfiguration, - )); - - const hierarchy: HierarchyConfiguration = getHierarchyConfigurationWithDefaults( - options?.hierarchy, - documentName, - folderName, - ); - - (config as Mutable).hierarchy = hierarchy; - - return config as DocumentationSuiteConfiguration; } diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts index 9f72e2858e6f..1592ca2c6a23 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts @@ -3,9 +3,14 @@ * Licensed under the MIT License. */ -import { type ApiItem, ApiItemKind } from "@microsoft/api-extractor-model"; +import { type ApiItem, ApiItemKind, type ApiPackage } from "@microsoft/api-extractor-model"; -import type { ValidApiItemKind } from "../../utilities/index.js"; +import { + getApiItemKind, + getUnscopedPackageName, + type ValidApiItemKind, +} from "../../utilities/index.js"; +import { createQualifiedDocumentNameForApiItem } from "../ApiItemTransformUtilities.js"; /** * Kind of documentation suite hierarchy. @@ -16,17 +21,17 @@ export enum HierarchyKind { /** * The API item gets a section under the document representing an ancestor of the API item. */ - Section = "section", + Section = "Section", /** * The API item gets its own document, in the folder for an ancestor of the API item. */ - Document = "document", + Document = "Document", /** * The API item gets its own document, and generates folder hierarchy for all descendent API items. */ - Folder = "folder", + Folder = "Folder", } /** @@ -36,6 +41,7 @@ export enum HierarchyKind { * Not intended for external use. * Only exists to share common properties between hierarchy configuration types. * + * @sealed * @public */ export interface DocumentationHierarchyConfigurationBase { @@ -48,55 +54,24 @@ export interface DocumentationHierarchyConfigurationBase; -/** - * {@inheritDoc SectionHierarchyConfiguration} - * - * @public - */ -export type SectionHierarchyOptions = - DocumentationHierarchyConfigurationBase; - -/** - * {@link HierarchyKind.Document} hierarchy configuration properties. - * - * @public - */ -export interface DocumentHierarchyProperties { - /** - * Document name to use for the API item. - * - * @defaultValue {@link DocumentationSuiteOptions.documentName} - */ - readonly documentName: string | ((apiItem: ApiItem) => string); -} - /** * The corresponding API item will get its own document, in the folder for an ancestor of the API item. * + * @sealed * @public */ export type DocumentHierarchyConfiguration = - DocumentationHierarchyConfigurationBase & DocumentHierarchyProperties; - -/** - * {@inheritDoc DocumentHierarchyConfiguration} - * - * @public - */ -export type DocumentHierarchyOptions = - DocumentationHierarchyConfigurationBase & - Partial; + DocumentationHierarchyConfigurationBase; /** * Placement of the API item's document relative to its generated folder. * - * @remarks Used by {@link FolderHierarchyProperties}. - * * @public */ export enum FolderDocumentPlacement { @@ -111,26 +86,6 @@ export enum FolderDocumentPlacement { Outside = "outside", } -/** - * {@link HierarchyKind.Folder} hierarchy configuration properties. - * - * @sealed - * @public - */ -export interface FolderHierarchyProperties extends DocumentHierarchyProperties { - /** - * Placement of the API item's document relative to its generated folder. - */ - readonly documentPlacement: FolderDocumentPlacement; - - /** - * Folder name to use for the API item. - * - * @defaultValue {@link DocumentationSuiteOptions.folderName} - */ - readonly folderName: string | ((apiItem: ApiItem) => string); -} - /** * The corresponding API item will get its own document, in the folder for an ancestor of the API item. * @@ -138,16 +93,15 @@ export interface FolderHierarchyProperties extends DocumentHierarchyProperties { * @public */ export type FolderHierarchyConfiguration = - DocumentationHierarchyConfigurationBase & FolderHierarchyProperties; - -/** - * {@inheritDoc FolderHierarchyConfiguration} - * - * @sealed - * @public - */ -export type FolderHierarchyOptions = DocumentationHierarchyConfigurationBase & - Partial; + DocumentationHierarchyConfigurationBase & { + /** + * Placement of the API item's document relative to its generated folder. + * + * @defaultValue {@link FolderDocumentPlacement.Outside} + * @privateRemarks TODO: change default to `inside` + */ + readonly documentPlacement: FolderDocumentPlacement; + }; /** * API item hierarchy configuration. @@ -160,39 +114,27 @@ export type DocumentationHierarchyConfiguration = | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; -/** - * API item hierarchy configuration. - * - * @sealed - * @public - */ -export type DocumentationHierarchyOptions = - | SectionHierarchyOptions - | DocumentHierarchyOptions - | FolderHierarchyOptions; - /** * Default {@link SectionHierarchyConfiguration} used by the system. */ const defaultSectionHierarchyOptions = { kind: HierarchyKind.Section, -} satisfies SectionHierarchyOptions; +} satisfies SectionHierarchyConfiguration; /** * Default {@link DocumentHierarchyConfiguration} used by the system. */ const defaultDocumentHierarchyOptions = { kind: HierarchyKind.Document, -} satisfies DocumentHierarchyOptions; +} satisfies DocumentHierarchyConfiguration; /** * Default {@link FolderHierarchyConfiguration} used by the system. */ const defaultFolderHierarchyOptions = { kind: HierarchyKind.Folder, - documentName: undefined, // TODO: "index" documentPlacement: FolderDocumentPlacement.Outside, // TODO: inside -} satisfies FolderHierarchyOptions; +} satisfies FolderHierarchyConfiguration; /** * Complete hierarchy configuration by API item kind. @@ -240,6 +182,16 @@ export type HierarchyConfiguration = { * There isn't a real reason to restrict this, except the way the code is currently structured. */ [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; + + /** + * {@inheritDoc HierarchyOptions.getDocumentName} + */ + readonly getDocumentName: (apiItem: ApiItem, config: HierarchyConfiguration) => string; + + /** + * {@inheritDoc HierarchyOptions.getFolderName} + */ + readonly getFolderName: (apiItem: ApiItem, config: HierarchyConfiguration) => string; }; /** @@ -261,7 +213,7 @@ export type HierarchyOptions = { [Kind in Exclude< ValidApiItemKind, ApiItemKind.Model | ApiItemKind.EntryPoint | ApiItemKind.Package - >]?: HierarchyKind | DocumentationHierarchyOptions; + >]?: HierarchyKind | DocumentationHierarchyConfiguration; } & { /** * Hierarchy configuration for the `Model` API item kind. @@ -270,7 +222,7 @@ export type HierarchyOptions = { * Always its own document. Never introduces folder hierarchy. * This is an important invariant, as it ensures that there is always at least one document in the output. */ - [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyOptions; + [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; /** * Hierarchy configuration for the `Package` API item kind. @@ -284,8 +236,8 @@ export type HierarchyOptions = { [ApiItemKind.Package]?: | HierarchyKind.Document | HierarchyKind.Folder - | DocumentHierarchyOptions - | FolderHierarchyOptions; + | DocumentHierarchyConfiguration + | FolderHierarchyConfiguration; /** * Hierarchy configuration for the `EntryPoint` API item kind. @@ -298,9 +250,84 @@ export type HierarchyOptions = { * TODO: Allow all hierarchy configurations for packages. * There isn't a real reason to restrict this, except the way the code is currently structured. */ - [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyOptions; + [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + + /** + * Generate the desired document name for the provided `ApiItem`. + * + * @remarks + * Default document name for any item configured to generate document or folder level hierarchy. + * If not specified, a system default will be used. + * + * @param apiItem - The API item for which the document name is being generated. + */ + readonly getDocumentName?: (apiItem: ApiItem, config: HierarchyConfiguration) => string; + + /** + * Generate the desired folder name for the provided `ApiItem`. + * + * @remarks + * Default folder name for any item configured to generate folder level hierarchy. + * If not specified, a system default will be used. + * + * @param apiItem - The API item for which the folder name is being generated. + */ + readonly getFolderName?: (apiItem: ApiItem, config: HierarchyConfiguration) => string; }; +/** + * Contains a list of default {@link DocumentationSuiteConfiguration} functions. + */ +// eslint-disable-next-line @typescript-eslint/no-namespace +export namespace DefaultHierarchyConfigurations { + /** + * Default {@link HierarchyConfiguration.getDocumentName}. + * + * @remarks + * Uses the item's scoped and qualified API name, but is handled differently for the following items: + * + * - Model: "index" + * + * - Package: Use the unscoped package name. + */ + export function getDocumentName(apiItem: ApiItem, config: HierarchyConfiguration): string { + const kind = getApiItemKind(apiItem); + switch (kind) { + case ApiItemKind.Model: { + return "index"; + } + case ApiItemKind.Package: { + return getUnscopedPackageName(apiItem as ApiPackage); + } + default: { + // Let the system generate a unique name that accounts for folder hierarchy. + return createQualifiedDocumentNameForApiItem(apiItem, config); + } + } + } + + /** + * Default {@link HierarchyConfiguration.getFolderName}. + * + * @remarks + * Uses the item's scoped and qualified API name, but is handled differently for the following items: + * + * - Package: Use the unscoped package name. + */ + export function getFolderName(apiItem: ApiItem, config: HierarchyConfiguration): string { + const kind = getApiItemKind(apiItem); + switch (kind) { + case ApiItemKind.Package: { + return getUnscopedPackageName(apiItem as ApiPackage); + } + default: { + // Let the system generate a unique name that accounts for folder hierarchy. + return createQualifiedDocumentNameForApiItem(apiItem, config); + } + } + } +} + /** * Default {@link HierarchyOptions}. */ @@ -313,10 +340,10 @@ const defaultHierarchyOptions = { // Items that get their own document, but do not introduce folder hierarchy: [ApiItemKind.Class]: HierarchyKind.Document, - [ApiItemKind.Enum]: HierarchyKind.Section, // TODO: Document + [ApiItemKind.Enum]: HierarchyKind.Section, // TODO: HierarchyKind.Document [ApiItemKind.EntryPoint]: HierarchyKind.Document, [ApiItemKind.Interface]: HierarchyKind.Document, - [ApiItemKind.TypeAlias]: HierarchyKind.Section, // TODO: Document + [ApiItemKind.TypeAlias]: HierarchyKind.Section, // TODO: HierarchyKind.Document // Items that get a section under the document representing an ancestor of the API item: [ApiItemKind.CallSignature]: HierarchyKind.Section, @@ -336,52 +363,20 @@ const defaultHierarchyOptions = { * Maps an input option to a complete {@link DocumentationHierarchyConfiguration}. */ function mapHierarchyOption( - option: HierarchyKind | DocumentationHierarchyOptions, - defaultDocumentName: string | ((apiItem: ApiItem) => string), - defaultFolderName: string | ((apiItem: ApiItem) => string), + option: HierarchyKind | DocumentationHierarchyConfiguration, ): DocumentationHierarchyConfiguration { switch (option) { case HierarchyKind.Section: { return defaultSectionHierarchyOptions; } case HierarchyKind.Document: { - return { - ...defaultDocumentHierarchyOptions, - documentName: defaultDocumentName, - }; + return defaultDocumentHierarchyOptions; } case HierarchyKind.Folder: { - return { - ...defaultFolderHierarchyOptions, - documentName: defaultDocumentName, - folderName: defaultFolderName, - }; + return defaultFolderHierarchyOptions; } default: { - const kind = option.kind; - switch (kind) { - case HierarchyKind.Section: { - return { ...defaultSectionHierarchyOptions, ...option }; - } - case HierarchyKind.Document: { - return { - ...defaultDocumentHierarchyOptions, - documentName: defaultDocumentName, - ...option, - }; - } - case HierarchyKind.Folder: { - return { - ...defaultFolderHierarchyOptions, - documentName: defaultDocumentName, - folderName: defaultFolderName, - ...option, - }; - } - default: { - throw new Error(`Invalid hierarchy configuration kind: ${kind}`); - } - } + return option; } } } @@ -391,19 +386,22 @@ function mapHierarchyOption( * in the remainder with defaults. */ export function getHierarchyConfigurationWithDefaults( - hierarchyOptions: HierarchyOptions | undefined, - defaultDocumentName: string | ((apiItem: ApiItem) => string), - defaultFolderName: string | ((apiItem: ApiItem) => string), + options?: HierarchyOptions | undefined, ): HierarchyConfiguration { - const options: HierarchyOptions = { + const { getDocumentName, getFolderName, ...hierarchyByItem } = options ?? {}; + + const hierarchyOptions = { ...defaultHierarchyOptions, - ...hierarchyOptions, + ...hierarchyByItem, }; - return Object.fromEntries( - Object.entries(options).map(([key, option]) => [ - key, - mapHierarchyOption(option, defaultDocumentName, defaultFolderName), - ]), - ) as HierarchyConfiguration; + const hierarchyConfigurations = Object.fromEntries( + Object.entries(hierarchyOptions).map(([key, value]) => [key, mapHierarchyOption(value)]), + ) as Omit; + + return { + getDocumentName: getDocumentName ?? DefaultHierarchyConfigurations.getDocumentName, + getFolderName: getFolderName ?? DefaultHierarchyConfigurations.getFolderName, + ...hierarchyConfigurations, + }; } diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts index 7e9a37182f51..e6c2f209abed 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts @@ -18,19 +18,13 @@ export { export { type DocumentationHierarchyConfiguration, type DocumentationHierarchyConfigurationBase, - type DocumentationHierarchyOptions, type DocumentHierarchyConfiguration, - type DocumentHierarchyOptions, - type DocumentHierarchyProperties, FolderDocumentPlacement, type FolderHierarchyConfiguration, - type FolderHierarchyOptions, - type FolderHierarchyProperties, type HierarchyConfiguration, type HierarchyOptions, HierarchyKind, type SectionHierarchyConfiguration, - type SectionHierarchyOptions, } from "./Hierarchy.js"; export { type ApiItemTransformations, diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/test/DocumentationSuite.test.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/test/DocumentationSuite.test.ts deleted file mode 100644 index fda3b20fcf15..000000000000 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/test/DocumentationSuite.test.ts +++ /dev/null @@ -1,73 +0,0 @@ -/*! - * Copyright (c) Microsoft Corporation and contributors. All rights reserved. - * Licensed under the MIT License. - */ - -import { ApiItemKind, type ApiItem } from "@microsoft/api-extractor-model"; -import { assert, expect } from "chai"; - -import { getValueOrDerived } from "../../../utilities/index.js"; -import { - getDocumentationSuiteConfigurationWithDefaults, - type DocumentationSuiteOptions, -} from "../DocumentationSuite.js"; -import { HierarchyKind } from "../Hierarchy.js"; - -describe("Documentation Suite configuration unit tests", () => { - describe("getDocumentationSuiteConfigurationWithDefaults", () => { - it("Hierarchy settings are applied correctly", () => { - const input: DocumentationSuiteOptions = { - hierarchy: { - [ApiItemKind.Variable]: HierarchyKind.Section, - [ApiItemKind.TypeAlias]: HierarchyKind.Document, - [ApiItemKind.Class]: { - kind: HierarchyKind.Document, - documentName: "foo", - }, - [ApiItemKind.Interface]: { - kind: HierarchyKind.Folder, - documentName: (apiItem) => `${apiItem.displayName}!`, - }, - }, - documentName: (apiItem) => `d_${apiItem.displayName}`, - folderName: (apiItem) => `f_${apiItem.displayName}`, - }; - - const config = getDocumentationSuiteConfigurationWithDefaults(input); - - const variableHierarchy = config.hierarchy[ApiItemKind.Variable]; - assert(variableHierarchy.kind === HierarchyKind.Section); - - const typeAliasItem = { - kind: ApiItemKind.TypeAlias, - displayName: "type-alias", - } as unknown as ApiItem; - const typeAliasHierarchy = config.hierarchy[ApiItemKind.TypeAlias]; - assert(typeAliasHierarchy.kind === HierarchyKind.Document); - expect(getValueOrDerived(typeAliasHierarchy.documentName, typeAliasItem)).to.equal( - "d_type-alias", - ); - - const classItem = { - kind: ApiItemKind.Class, - displayName: "class", - } as unknown as ApiItem; - const classHierarchy = config.hierarchy[ApiItemKind.Class]; - assert(classHierarchy.kind === HierarchyKind.Document); - expect(getValueOrDerived(classHierarchy.documentName, classItem)).to.equal("foo"); - - const interfaceItem = { - kind: ApiItemKind.Interface, - displayName: "interface", - } as unknown as ApiItem; - const interfaceHierarchy = config.hierarchy[ApiItemKind.Interface]; - assert(interfaceHierarchy.kind === HierarchyKind.Folder); - expect(getValueOrDerived(interfaceHierarchy.documentName, interfaceItem)).to.equal( - "interface!", - ); - expect(getValueOrDerived(interfaceHierarchy.folderName, interfaceItem)).to.equal( - "f_interface", - ); - }); - }); -}); diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/test/Hierarchy.test.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/test/Hierarchy.test.ts deleted file mode 100644 index 8b87f6ad0235..000000000000 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/test/Hierarchy.test.ts +++ /dev/null @@ -1,109 +0,0 @@ -/*! - * Copyright (c) Microsoft Corporation and contributors. All rights reserved. - * Licensed under the MIT License. - */ - -import { ApiItemKind } from "@microsoft/api-extractor-model"; -import { expect } from "chai"; - -import { - FolderDocumentPlacement, - getHierarchyConfigurationWithDefaults, - HierarchyKind, - type DocumentHierarchyConfiguration, - type FolderHierarchyConfiguration, - type HierarchyConfiguration, - type HierarchyOptions, - type SectionHierarchyConfiguration, -} from "../Hierarchy.js"; - -describe("Hierarchy configuration unit tests", () => { - describe("getHierarchyConfigurationWithDefaults", () => { - const defaultDocumentName = "foo"; - const defaultFolderName = "bar"; - - const expectedDefaultSectionConfig: SectionHierarchyConfiguration = { - kind: HierarchyKind.Section, - }; - - const expectedDefaultDocumentConfig: DocumentHierarchyConfiguration = { - kind: HierarchyKind.Document, - documentName: defaultDocumentName, - }; - - const expectedDefaultFolderConfig: FolderHierarchyConfiguration = { - kind: HierarchyKind.Folder, - documentName: defaultDocumentName, - documentPlacement: FolderDocumentPlacement.Outside, - folderName: defaultFolderName, - }; - - const expectedDefaultHierarchyConfig: HierarchyConfiguration = { - // Items that introduce folder hierarchy: - [ApiItemKind.Namespace]: expectedDefaultFolderConfig, - [ApiItemKind.Package]: expectedDefaultFolderConfig, - - // Items that get their own document, but do not introduce folder hierarchy: - [ApiItemKind.Class]: expectedDefaultDocumentConfig, - [ApiItemKind.Enum]: expectedDefaultSectionConfig, // TODO: Document - [ApiItemKind.EntryPoint]: expectedDefaultDocumentConfig, - [ApiItemKind.Interface]: expectedDefaultDocumentConfig, - [ApiItemKind.Model]: expectedDefaultDocumentConfig, - [ApiItemKind.TypeAlias]: expectedDefaultSectionConfig, // TODO: Document - - // Items that get a section under the document representing an ancestor of the API item: - [ApiItemKind.CallSignature]: expectedDefaultSectionConfig, - [ApiItemKind.Constructor]: expectedDefaultSectionConfig, - [ApiItemKind.ConstructSignature]: expectedDefaultSectionConfig, - [ApiItemKind.EnumMember]: expectedDefaultSectionConfig, - [ApiItemKind.Function]: expectedDefaultSectionConfig, - [ApiItemKind.IndexSignature]: expectedDefaultSectionConfig, - [ApiItemKind.Method]: expectedDefaultSectionConfig, - [ApiItemKind.MethodSignature]: expectedDefaultSectionConfig, - [ApiItemKind.Property]: expectedDefaultSectionConfig, - [ApiItemKind.PropertySignature]: expectedDefaultSectionConfig, - [ApiItemKind.Variable]: expectedDefaultSectionConfig, - }; - - it("Empty input", () => { - const result = getHierarchyConfigurationWithDefaults( - undefined, - defaultDocumentName, - defaultFolderName, - ); - - expect(result).to.deep.equal(expectedDefaultHierarchyConfig); - }); - - it("Input contains overrides", () => { - const input: HierarchyOptions = { - [ApiItemKind.Class]: HierarchyKind.Section, - [ApiItemKind.Interface]: { - kind: HierarchyKind.Folder, - folderName: "baz", - }, - }; - - const result = getHierarchyConfigurationWithDefaults( - input, - defaultDocumentName, - defaultFolderName, - ); - - const expected: HierarchyConfiguration = { - ...expectedDefaultHierarchyConfig, - [ApiItemKind.Class]: { - kind: HierarchyKind.Section, - }, - [ApiItemKind.Interface]: { - kind: HierarchyKind.Folder, - documentName: defaultDocumentName, - documentPlacement: FolderDocumentPlacement.Outside, - folderName: "baz", - }, - }; - - expect(result).to.deep.equal(expected); - }); - }); -}); diff --git a/tools/api-markdown-documenter/src/api-item-transforms/index.ts b/tools/api-markdown-documenter/src/api-item-transforms/index.ts index 4fdba01eb0a2..f2e9589db7e8 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/index.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/index.ts @@ -23,23 +23,17 @@ export { type ApiItemTransformations, type DefaultDocumentationSuiteConfiguration, type DocumentHierarchyConfiguration, - type DocumentHierarchyOptions, - type DocumentHierarchyProperties, type DocumentationSuiteConfiguration, type DocumentationSuiteOptions, FolderDocumentPlacement, type FolderHierarchyConfiguration, - type FolderHierarchyOptions, - type FolderHierarchyProperties, getApiItemTransformationConfigurationWithDefaults, type DocumentationHierarchyConfiguration, type DocumentationHierarchyConfigurationBase, - type DocumentationHierarchyOptions, HierarchyKind, type HierarchyConfiguration, type HierarchyOptions, type SectionHierarchyConfiguration, - type SectionHierarchyOptions, type TransformApiItemWithChildren, type TransformApiItemWithoutChildren, } from "./configuration/index.js"; diff --git a/tools/api-markdown-documenter/src/index.ts b/tools/api-markdown-documenter/src/index.ts index 5d9c9107f74e..18ff012f5d9b 100644 --- a/tools/api-markdown-documenter/src/index.ts +++ b/tools/api-markdown-documenter/src/index.ts @@ -21,23 +21,17 @@ export { type DefaultDocumentationSuiteConfiguration, type DocumentationHierarchyConfiguration, type DocumentationHierarchyConfigurationBase, - type DocumentationHierarchyOptions, type DocumentationSuiteConfiguration, type DocumentationSuiteOptions, type DocumentHierarchyConfiguration, - type DocumentHierarchyOptions, - type DocumentHierarchyProperties, FolderDocumentPlacement, type FolderHierarchyConfiguration, - type FolderHierarchyOptions, - type FolderHierarchyProperties, // TODO: remove this once utility APIs can be called with partial configs. getApiItemTransformationConfigurationWithDefaults, HierarchyKind, type HierarchyConfiguration, type HierarchyOptions, type SectionHierarchyConfiguration, - type SectionHierarchyOptions, type TransformApiItemWithChildren, type TransformApiItemWithoutChildren, transformApiModel, diff --git a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts index cab4da356672..1c0850a99d91 100644 --- a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts +++ b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts @@ -12,9 +12,10 @@ import { expect } from "chai"; import { compare } from "dir-compare"; import { + ApiItemUtilities, FolderDocumentPlacement, HierarchyKind, - type FolderHierarchyOptions, + type FolderHierarchyConfiguration, type HierarchyOptions, } from "../index.js"; @@ -44,15 +45,14 @@ export const testDataDirectoryPath = Path.resolve(dirname, "..", "..", "src", "t */ // eslint-disable-next-line @typescript-eslint/no-namespace export namespace HierarchyConfigurations { - const outsideFolderConfig: FolderHierarchyOptions = { + const outsideFolderConfig: FolderHierarchyConfiguration = { kind: HierarchyKind.Folder, documentPlacement: FolderDocumentPlacement.Outside, }; - const insideFolderOptions: FolderHierarchyOptions = { + const insideFolderOptions: FolderHierarchyConfiguration = { kind: HierarchyKind.Folder, documentPlacement: FolderDocumentPlacement.Inside, - documentName: "index", }; /** @@ -130,6 +130,24 @@ export namespace HierarchyConfigurations { [ApiItemKind.Property]: HierarchyKind.Document, [ApiItemKind.PropertySignature]: HierarchyKind.Document, [ApiItemKind.Variable]: HierarchyKind.Document, + + getDocumentName: (apiItem, config): string => { + switch (apiItem.kind) { + case ApiItemKind.Model: + case ApiItemKind.Package: + case ApiItemKind.Namespace: + case ApiItemKind.Class: + case ApiItemKind.Enum: + case ApiItemKind.Interface: + case ApiItemKind.TypeAlias: { + return "index"; + } + default: { + // Let the system generate a unique name that accounts for folder hierarchy. + return ApiItemUtilities.createQualifiedDocumentNameForApiItem(apiItem, config); + } + } + }, }; } From 1088e92ced9259176e2584d209c24ccc9128463d Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 8 Jan 2025 01:42:13 +0000 Subject: [PATCH 44/54] test: Remove new test case for now --- .../src/test/EndToEndTestUtilities.ts | 89 +++---- .../simple-suite-test/deep-config/index.html | 32 --- .../deep-config/test-suite-a/index.html | 222 ------------------ .../_constructor_-constructor.html | 44 ---- .../abstractpropertygetter-property.html | 21 -- .../testabstractclass-class/index.html | 97 -------- .../protectedproperty-property.html | 21 -- .../publicabstractmethod-method.html | 20 -- .../sealedmethod-method.html | 25 -- .../virtualmethod-method.html | 25 -- .../_constructor_-constructor.html | 61 ----- .../abstractpropertygetter-property.html | 21 -- .../test-suite-a/testclass-class/index.html | 196 ---------------- .../publicabstractmethod-method.html | 20 -- .../testclasseventproperty-property.html | 25 -- .../testclassgetterproperty-property.html | 25 -- .../testclassmethod-method.html | 52 ---- .../testclassproperty-property.html | 25 -- .../testclassstaticmethod-method.html | 44 ---- .../testclassstaticproperty-property.html | 21 -- .../testclass-class/virtualmethod-method.html | 24 -- .../test-suite-a/testconst-variable.html | 25 -- ...onstwithemptydeprecatedblock-variable.html | 24 -- .../testemptyinterface-interface/index.html | 20 -- .../test-suite-a/testenum-enum/index.html | 96 -------- .../testenumvalue1-enummember.html | 24 -- .../testenumvalue2-enummember.html | 24 -- .../testenumvalue3-enummember.html | 24 -- .../test-suite-a/testfunction-function.html | 84 ------- ...tfunctionreturninginlinetype-function.html | 25 -- ...ionreturningintersectiontype-function.html | 28 --- ...stfunctionreturninguniontype-function.html | 25 -- .../_call_-callsignature.html | 24 -- .../_call__1-callsignature.html | 24 -- .../_new_-constructsignature.html | 24 -- .../getterproperty-property.html | 21 -- .../testinterface-interface/index.html | 162 ------------- ...badinheritdoctarget-propertysignature.html | 21 -- .../setterproperty-property.html | 21 -- ...tclasseventproperty-propertysignature.html | 25 -- .../testinterfacemethod-methodsignature.html | 24 -- ...stinterfaceproperty-propertysignature.html | 25 -- ...alinterfaceproperty-propertysignature.html | 21 -- .../index.html | 52 ---- .../testmethod-methodsignature.html | 48 ---- .../_indexer_-indexsignature.html | 20 -- .../index.html | 37 --- .../index.html | 62 ----- .../testproperty-propertysignature.html | 25 -- .../testmappedtype-typealias/index.html | 24 -- .../testmodule-namespace/foo-variable.html | 20 -- .../testmodule-namespace/index.html | 35 --- .../testnamespace-namespace/index.html | 168 ------------- .../_constructor_-constructor.html | 39 --- .../testclass-class/index.html | 77 ------ .../testclassmethod-method.html | 52 ---- .../testclassproperty-property.html | 21 -- .../testconst-variable.html | 21 -- .../testenum-enum/index.html | 55 ----- .../testenumvalue1-enummember.html | 20 -- .../testenumvalue2-enummember.html | 20 -- .../testfunction-function.html | 48 ---- .../testinterface-interface/index.html | 64 ----- .../testinterfacemethod-methodsignature.html | 21 -- ...stinterfaceproperty-propertysignature.html | 22 -- .../testsubnamespace-namespace/index.html | 20 -- .../testtypealias-typealias/index.html | 20 -- .../typealias-typealias/index.html | 24 -- .../foo-interface/bar-propertysignature.html | 25 -- .../test-suite-b/foo-interface/index.html | 39 --- .../deep-config/test-suite-b/index.html | 31 --- .../simple-suite-test/deep-config/index.md | 8 - .../deep-config/test-suite-a/index.md | 92 -------- .../_constructor_-constructor.md | 18 -- .../abstractpropertygetter-property.md | 13 - .../testabstractclass-class/index.md | 32 --- .../protectedproperty-property.md | 13 - .../publicabstractmethod-method.md | 11 - .../sealedmethod-method.md | 18 -- .../virtualmethod-method.md | 18 -- .../_constructor_-constructor.md | 24 -- .../abstractpropertygetter-property.md | 13 - .../test-suite-a/testclass-class/index.md | 68 ------ .../publicabstractmethod-method.md | 11 - .../testclasseventproperty-property.md | 17 -- .../testclassgetterproperty-property.md | 19 -- .../testclass-class/testclassmethod-method.md | 32 --- .../testclassproperty-property.md | 17 -- .../testclassstaticmethod-method.md | 23 -- .../testclassstaticproperty-property.md | 13 - .../testclass-class/virtualmethod-method.md | 16 -- .../test-suite-a/testconst-variable.md | 17 -- ...tconstwithemptydeprecatedblock-variable.md | 15 -- .../testemptyinterface-interface/index.md | 11 - .../test-suite-a/testenum-enum/index.md | 77 ------ .../testenumvalue1-enummember.md | 15 -- .../testenumvalue2-enummember.md | 15 -- .../testenumvalue3-enummember.md | 15 -- .../test-suite-a/testfunction-function.md | 40 ---- ...estfunctionreturninginlinetype-function.md | 20 -- ...ctionreturningintersectiontype-function.md | 21 -- ...testfunctionreturninguniontype-function.md | 17 -- .../_call_-callsignature.md | 15 -- .../_call__1-callsignature.md | 15 -- .../_new_-constructsignature.md | 15 -- .../getterproperty-property.md | 13 - .../testinterface-interface/index.md | 60 ----- ...thbadinheritdoctarget-propertysignature.md | 11 - .../setterproperty-property.md | 14 -- ...estclasseventproperty-propertysignature.md | 17 -- .../testinterfacemethod-methodsignature.md | 15 -- ...testinterfaceproperty-propertysignature.md | 17 -- ...onalinterfaceproperty-propertysignature.md | 13 - .../index.md | 31 --- .../testmethod-methodsignature.md | 27 --- .../_indexer_-indexsignature.md | 13 - .../index.md | 17 -- .../index.md | 27 --- .../testproperty-propertysignature.md | 17 -- .../testmappedtype-typealias/index.md | 17 -- .../testmodule-namespace/foo-variable.md | 11 - .../testmodule-namespace/index.md | 9 - .../testnamespace-namespace/index.md | 77 ------ .../_constructor_-constructor.md | 17 -- .../testclass-class/index.md | 29 --- .../testclass-class/testclassmethod-method.md | 31 --- .../testclassproperty-property.md | 13 - .../testconst-variable.md | 13 - .../testenum-enum/index.md | 34 --- .../testenumvalue1-enummember.md | 11 - .../testenumvalue2-enummember.md | 11 - .../testfunction-function.md | 27 --- .../testinterface-interface/index.md | 27 --- .../testinterfacemethod-methodsignature.md | 13 - ...testinterfaceproperty-propertysignature.md | 15 -- .../testsubnamespace-namespace/index.md | 11 - .../testtypealias-typealias/index.md | 11 - .../test-suite-a/typealias-typealias/index.md | 15 -- .../foo-interface/bar-propertysignature.md | 17 -- .../test-suite-b/foo-interface/index.md | 17 -- .../deep-config/test-suite-b/index.md | 9 - 141 files changed, 45 insertions(+), 4477 deletions(-) delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/_constructor_-constructor.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/abstractpropertygetter-property.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/protectedproperty-property.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/publicabstractmethod-method.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/sealedmethod-method.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/virtualmethod-method.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/_constructor_-constructor.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/abstractpropertygetter-property.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/publicabstractmethod-method.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclasseventproperty-property.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassgetterproperty-property.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassmethod-method.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassproperty-property.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticmethod-method.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticproperty-property.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/virtualmethod-method.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testconst-variable.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testconstwithemptydeprecatedblock-variable.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testemptyinterface-interface/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue1-enummember.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue2-enummember.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue3-enummember.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunction-function.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturninginlinetype-function.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturningintersectiontype-function.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturninguniontype-function.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call_-callsignature.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call__1-callsignature.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_new_-constructsignature.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/getterproperty-property.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/setterproperty-property.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testclasseventproperty-propertysignature.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfacemethod-methodsignature.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmappedtype-typealias/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/foo-variable.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testconst-variable.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testfunction-function.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testsubnamespace-namespace/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testtypealias-typealias/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/typealias-typealias/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/foo-interface/bar-propertysignature.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/foo-interface/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/index.html delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/_constructor_-constructor.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/abstractpropertygetter-property.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/protectedproperty-property.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/publicabstractmethod-method.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/sealedmethod-method.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/virtualmethod-method.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/_constructor_-constructor.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/abstractpropertygetter-property.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/publicabstractmethod-method.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclasseventproperty-property.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassgetterproperty-property.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassmethod-method.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassproperty-property.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticmethod-method.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticproperty-property.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/virtualmethod-method.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testconst-variable.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testconstwithemptydeprecatedblock-variable.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testemptyinterface-interface/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue1-enummember.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue2-enummember.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue3-enummember.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunction-function.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturninginlinetype-function.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturningintersectiontype-function.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturninguniontype-function.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call_-callsignature.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call__1-callsignature.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_new_-constructsignature.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/getterproperty-property.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/setterproperty-property.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testclasseventproperty-propertysignature.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfacemethod-methodsignature.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmappedtype-typealias/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/foo-variable.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testconst-variable.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testfunction-function.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testsubnamespace-namespace/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testtypealias-typealias/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/typealias-typealias/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/foo-interface/bar-propertysignature.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/foo-interface/index.md delete mode 100644 tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/index.md diff --git a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts index 1c0850a99d91..3c3612da52df 100644 --- a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts +++ b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts @@ -105,50 +105,51 @@ export namespace HierarchyConfigurations { [ApiItemKind.Variable]: HierarchyKind.Document, }; - /** - * "Deep" hierarchy: All "parent" API items generate hierarchy. All other items are rendered as documents under their parent hierarchy. - * @remarks Leads to many documents, but each document is likely to be relatively small. - */ - export const deep: HierarchyOptions = { - // Items that introduce folder hierarchy: - [ApiItemKind.Namespace]: insideFolderOptions, - [ApiItemKind.Package]: insideFolderOptions, - [ApiItemKind.Class]: insideFolderOptions, - [ApiItemKind.Enum]: insideFolderOptions, - [ApiItemKind.Interface]: insideFolderOptions, - [ApiItemKind.TypeAlias]: insideFolderOptions, - - // Items that get their own document, but do not introduce folder hierarchy: - [ApiItemKind.CallSignature]: HierarchyKind.Document, - [ApiItemKind.Constructor]: HierarchyKind.Document, - [ApiItemKind.ConstructSignature]: HierarchyKind.Document, - [ApiItemKind.EnumMember]: HierarchyKind.Document, - [ApiItemKind.Function]: HierarchyKind.Document, - [ApiItemKind.IndexSignature]: HierarchyKind.Document, - [ApiItemKind.Method]: HierarchyKind.Document, - [ApiItemKind.MethodSignature]: HierarchyKind.Document, - [ApiItemKind.Property]: HierarchyKind.Document, - [ApiItemKind.PropertySignature]: HierarchyKind.Document, - [ApiItemKind.Variable]: HierarchyKind.Document, - - getDocumentName: (apiItem, config): string => { - switch (apiItem.kind) { - case ApiItemKind.Model: - case ApiItemKind.Package: - case ApiItemKind.Namespace: - case ApiItemKind.Class: - case ApiItemKind.Enum: - case ApiItemKind.Interface: - case ApiItemKind.TypeAlias: { - return "index"; - } - default: { - // Let the system generate a unique name that accounts for folder hierarchy. - return ApiItemUtilities.createQualifiedDocumentNameForApiItem(apiItem, config); - } - } - }, - }; + // TODO + // /** + // * "Deep" hierarchy: All "parent" API items generate hierarchy. All other items are rendered as documents under their parent hierarchy. + // * @remarks Leads to many documents, but each document is likely to be relatively small. + // */ + // export const deep: HierarchyOptions = { + // // Items that introduce folder hierarchy: + // [ApiItemKind.Namespace]: insideFolderOptions, + // [ApiItemKind.Package]: insideFolderOptions, + // [ApiItemKind.Class]: insideFolderOptions, + // [ApiItemKind.Enum]: insideFolderOptions, + // [ApiItemKind.Interface]: insideFolderOptions, + // [ApiItemKind.TypeAlias]: insideFolderOptions, + + // // Items that get their own document, but do not introduce folder hierarchy: + // [ApiItemKind.CallSignature]: HierarchyKind.Document, + // [ApiItemKind.Constructor]: HierarchyKind.Document, + // [ApiItemKind.ConstructSignature]: HierarchyKind.Document, + // [ApiItemKind.EnumMember]: HierarchyKind.Document, + // [ApiItemKind.Function]: HierarchyKind.Document, + // [ApiItemKind.IndexSignature]: HierarchyKind.Document, + // [ApiItemKind.Method]: HierarchyKind.Document, + // [ApiItemKind.MethodSignature]: HierarchyKind.Document, + // [ApiItemKind.Property]: HierarchyKind.Document, + // [ApiItemKind.PropertySignature]: HierarchyKind.Document, + // [ApiItemKind.Variable]: HierarchyKind.Document, + + // getDocumentName: (apiItem, config): string => { + // switch (apiItem.kind) { + // case ApiItemKind.Model: + // case ApiItemKind.Package: + // case ApiItemKind.Namespace: + // case ApiItemKind.Class: + // case ApiItemKind.Enum: + // case ApiItemKind.Interface: + // case ApiItemKind.TypeAlias: { + // return "index"; + // } + // default: { + // // Let the system generate a unique name that accounts for folder hierarchy. + // return ApiItemUtilities.createQualifiedDocumentNameForApiItem(apiItem, config); + // } + // } + // }, + // }; } /** diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/index.html deleted file mode 100644 index e6bc549b6dba..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/index.html +++ /dev/null @@ -1,32 +0,0 @@ - - - - - - -
-

API Overview

-
-

Packages

- - - - - - - - - - - - - - - - - -
PackageDescription
test-suite-aTest package
test-suite-b
-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/index.html deleted file mode 100644 index 69b329f3c37e..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/index.html +++ /dev/null @@ -1,222 +0,0 @@ - - - - - - -
-

test-suite-a

-
-

Packages > test-suite-a

-
-
-

Test package

-
-
-

Remarks

-

-

This remarks block includes a bulleted list!

-

- Bullet 1

-

- Bullet 2

-

And an ordered list for good measure!

-

1. List item 1

-

2. List item 2

-

3. List item 3

-

Also, here is a link test, including a bad link, because we should have some reasonable support if this happens:

-

- Good link (no alias): TestClass

-

- Good link (with alias): function alias text

-

- Bad link (no alias): InvalidItem

-

- Bad link (with alias): even though I link to an invalid item, I would still like this text to be rendered

-

-
-
-

Example

-

-

A test example

const foo = bar; -

-
-
-

Interfaces

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
InterfaceDescription
TestEmptyInterfaceAn empty interface
TestInterfaceTest interface
TestInterfaceExtendingOtherInterfacesTest interface that extends other interfaces
TestInterfaceWithIndexSignatureAn interface with an index signature.
TestInterfaceWithTypeParameterTest interface with generic type parameter
-
-
-

Classes

- - - - - - - - - - - - - - - - - -
ClassDescription
TestAbstractClassA test abstract class.
TestClassTest class
-
-
-

Enumerations

- - - - - - - - - - - - - -
EnumDescription
TestEnumTest Enum
-
-
-

Types

- - - - - - - - - - - - - - - - - -
TypeAliasDescription
TestMappedTypeTest Mapped Type, using TestEnum
TypeAliasTest Type-Alias
-
-
-

Functions

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FunctionAlertsReturn TypeDescription
testFunction(testParameter, testOptionalParameter)AlphaTTypeParameterTest function
testFunctionReturningInlineType(){ foo: number; bar: TestEnum; }Test function that returns an inline type
testFunctionReturningIntersectionType()DeprecatedTestEmptyInterface & TestInterfaceWithTypeParameter<number>Test function that returns an inline type
testFunctionReturningUnionType()string | TestInterfaceTest function that returns an inline type
-
-
-

Variables

- - - - - - - - - - - - - - - - - - - - - - - - - - -
VariableAlertsModifiersTypeDescription
testConstBetareadonlyTest Constant
testConstWithEmptyDeprecatedBlockDeprecatedreadonlystringI have a @deprecated tag with an empty comment block.
-
-
-

Namespaces

- - - - - - - - - - - - - - - - - -
NamespaceDescription
TestModule
TestNamespaceTest Namespace
-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/_constructor_-constructor.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/_constructor_-constructor.html deleted file mode 100644 index 01f49f0eac47..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/_constructor_-constructor.html +++ /dev/null @@ -1,44 +0,0 @@ - - - - - - -
-

(constructor)

-
-

Packages > test-suite-a > TestAbstractClass > (constructor)(privateProperty, protectedProperty)

-
-
-

This is a {@customTag constructor}.

-
-
-

Signature

protected constructor(privateProperty: number, protectedProperty: TestEnum); -
-
-

Parameters

- - - - - - - - - - - - - - - - - - - - -
ParameterTypeDescription
privatePropertynumber
protectedPropertyTestEnum
-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/abstractpropertygetter-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/abstractpropertygetter-property.html deleted file mode 100644 index 78a68165c32c..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/abstractpropertygetter-property.html +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - -
-

abstractPropertyGetter

-
-

Packages > test-suite-a > TestAbstractClass > abstractPropertyGetter

-
-
-

A test abstract getter property.

-
-
-

Signature

abstract get abstractPropertyGetter(): TestMappedType; -

Type: TestMappedType

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/index.html deleted file mode 100644 index 2d2fba82118e..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/index.html +++ /dev/null @@ -1,97 +0,0 @@ - - - - - - -
-

TestAbstractClass

-
-

Packages > test-suite-a > TestAbstractClass

-
-
-

A test abstract class.

-
-
-

Signature

export declare abstract class TestAbstractClass -
-
-

Constructors

- - - - - - - - - - - - - -
ConstructorDescription
(constructor)(privateProperty, protectedProperty)This is a {@customTag constructor}.
-
-
-

Properties

- - - - - - - - - - - - - - - - - - - - - - - -
PropertyModifiersTypeDescription
abstractPropertyGetterreadonlyTestMappedTypeA test abstract getter property.
protectedPropertyreadonlyTestEnumA test protected property.
-
-
-

Methods

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MethodModifiersReturn TypeDescription
publicAbstractMethod()voidA test public abstract method.
sealedMethod()sealedstringA test @sealed method.
virtualMethod()virtualnumberA test @virtual method.
-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/protectedproperty-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/protectedproperty-property.html deleted file mode 100644 index 8d4557344f00..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/protectedproperty-property.html +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - -
-

protectedProperty

-
-

Packages > test-suite-a > TestAbstractClass > protectedProperty

-
-
-

A test protected property.

-
-
-

Signature

protected readonly protectedProperty: TestEnum; -

Type: TestEnum

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/publicabstractmethod-method.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/publicabstractmethod-method.html deleted file mode 100644 index a592fd8afe94..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/publicabstractmethod-method.html +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - -
-

publicAbstractMethod

-
-

Packages > test-suite-a > TestAbstractClass > publicAbstractMethod()

-
-
-

A test public abstract method.

-
-
-

Signature

abstract publicAbstractMethod(): void; -
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/sealedmethod-method.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/sealedmethod-method.html deleted file mode 100644 index 3e07abc323ba..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/sealedmethod-method.html +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - -
-

sealedMethod

-
-

Packages > test-suite-a > TestAbstractClass > sealedMethod()

-
-
-

A test @sealed method.

-
-
-

Signature

/** @sealed */
protected sealedMethod(): string; -
-
-

Returns

-

A string!

-

Return type: string

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/virtualmethod-method.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/virtualmethod-method.html deleted file mode 100644 index 0a0ad7de3210..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/virtualmethod-method.html +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - -
-

virtualMethod

-
-

Packages > test-suite-a > TestAbstractClass > virtualMethod()

-
-
-

A test @virtual method.

-
-
-

Signature

/** @virtual */
protected virtualMethod(): number; -
-
-

Returns

-

A number!

-

Return type: number

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/_constructor_-constructor.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/_constructor_-constructor.html deleted file mode 100644 index c1f361e3cbc9..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/_constructor_-constructor.html +++ /dev/null @@ -1,61 +0,0 @@ - - - - - - -
-

(constructor)

-
-

Packages > test-suite-a > TestClass > (constructor)(privateProperty, protectedProperty, testClassProperty, testClassEventProperty)

-
-
-

Test class constructor

-
-
-

Signature

constructor(privateProperty: number, protectedProperty: TestEnum, testClassProperty: TTypeParameterB, testClassEventProperty: () => void); -
-
-

Remarks

-

Here are some remarks about the constructor

-
-
-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterTypeDescription
privatePropertynumberSee TestAbstractClass's constructor.
protectedPropertyTestEnum -

Some notes about the parameter.

-

See protectedProperty.

-
testClassPropertyTTypeParameterBSee testClassProperty.
testClassEventProperty() => voidSee testClassEventProperty.
-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/abstractpropertygetter-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/abstractpropertygetter-property.html deleted file mode 100644 index bb178bcc3ba0..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/abstractpropertygetter-property.html +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - -
-

abstractPropertyGetter

-
-

Packages > test-suite-a > TestClass > abstractPropertyGetter

-
-
-

A test abstract getter property.

-
-
-

Signature

get abstractPropertyGetter(): TestMappedType; -

Type: TestMappedType

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/index.html deleted file mode 100644 index 917df3feb68c..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/index.html +++ /dev/null @@ -1,196 +0,0 @@ - - - - - - -
-

TestClass

-
-

Packages > test-suite-a > TestClass

-
-
-

Test class

-
-
-

Signature

export declare class TestClass<TTypeParameterA, TTypeParameterB> extends TestAbstractClass -

-

Extends: TestAbstractClass

-

-

-

Type Parameters

- - - - - - - - - - - - - - - - - -
ParameterDescription
TTypeParameterAA type parameter
TTypeParameterBAnother type parameter
-
-

-

-
-
-

Remarks

-

Here are some remarks about the class

-
-
-

Constructors

- - - - - - - - - - - - - -
ConstructorDescription
(constructor)(privateProperty, protectedProperty, testClassProperty, testClassEventProperty)Test class constructor
-
-
-

Static Properties

- - - - - - - - - - - - - - - -
PropertyTypeDescription
testClassStaticProperty(foo: number) => stringTest static class property
-
-
-

Static Methods

- - - - - - - - - - - - - - - -
MethodReturn TypeDescription
testClassStaticMethod(foo)stringTest class static method
-
-
-

Events

- - - - - - - - - - - - - - - - - -
PropertyModifiersTypeDescription
testClassEventPropertyreadonly() => voidTest class event property
-
-
-

Properties

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PropertyModifiersTypeDescription
abstractPropertyGetterreadonlyTestMappedTypeA test abstract getter property.
testClassGetterPropertyvirtualnumberTest class property with both a getter and a setter.
testClassPropertyreadonlyTTypeParameterBTest class property
-
-
-

Methods

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MethodModifiersReturn TypeDescription
publicAbstractMethod()voidA test public abstract method.
testClassMethod(input)sealedTTypeParameterATest class method
virtualMethod()numberOverrides virtualMethod().
-
-
-

See Also

-

TestAbstractClass

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/publicabstractmethod-method.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/publicabstractmethod-method.html deleted file mode 100644 index f6b972c7f55e..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/publicabstractmethod-method.html +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - -
-

publicAbstractMethod

-
-

Packages > test-suite-a > TestClass > publicAbstractMethod()

-
-
-

A test public abstract method.

-
-
-

Signature

publicAbstractMethod(): void; -
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclasseventproperty-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclasseventproperty-property.html deleted file mode 100644 index c9481deb7915..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclasseventproperty-property.html +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - -
-

testClassEventProperty

-
-

Packages > test-suite-a > TestClass > testClassEventProperty

-
-
-

Test class event property

-
-
-

Signature

readonly testClassEventProperty: () => void; -

Type: () => void

-
-
-

Remarks

-

Here are some remarks about the property

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassgetterproperty-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassgetterproperty-property.html deleted file mode 100644 index 931105145467..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassgetterproperty-property.html +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - -
-

testClassGetterProperty

-
-

Packages > test-suite-a > TestClass > testClassGetterProperty

-
-
-

Test class property with both a getter and a setter.

-
-
-

Signature

/** @virtual */
get testClassGetterProperty(): number;


set testClassGetterProperty(newValue: number); -

Type: number

-
-
-

Remarks

-

Here are some remarks about the getter-only property

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassmethod-method.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassmethod-method.html deleted file mode 100644 index 061dfeb57cfd..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassmethod-method.html +++ /dev/null @@ -1,52 +0,0 @@ - - - - - - -
-

testClassMethod

-
-

Packages > test-suite-a > TestClass > testClassMethod(input)

-
-
-

Test class method

-
-
-

Signature

/** @sealed */
testClassMethod(input: TTypeParameterA): TTypeParameterA; -
-
-

Remarks

-

Here are some remarks about the method

-
-
-

Parameters

- - - - - - - - - - - - - - - -
ParameterTypeDescription
inputTTypeParameterA
-
-
-

Returns

-

Return type: TTypeParameterA

-
-
-

Throws

-

Some sort of error in 1 case.

-

Some other sort of error in another case. For example, a case where some thing happens.

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassproperty-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassproperty-property.html deleted file mode 100644 index dc1eeaf89412..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassproperty-property.html +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - -
-

testClassProperty

-
-

Packages > test-suite-a > TestClass > testClassProperty

-
-
-

Test class property

-
-
-

Signature

readonly testClassProperty: TTypeParameterB; -

Type: TTypeParameterB

-
-
-

Remarks

-

Here are some remarks about the property

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticmethod-method.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticmethod-method.html deleted file mode 100644 index be05c50d4e8e..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticmethod-method.html +++ /dev/null @@ -1,44 +0,0 @@ - - - - - - -
-

testClassStaticMethod

-
-

Packages > test-suite-a > TestClass > testClassStaticMethod(foo)

-
-
-

Test class static method

-
-
-

Signature

static testClassStaticMethod(foo: number): string; -
-
-

Parameters

- - - - - - - - - - - - - - - -
ParameterTypeDescription
foonumberSome number
-
-
-

Returns

-

- Some string

-

Return type: string

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticproperty-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticproperty-property.html deleted file mode 100644 index 460d23903051..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticproperty-property.html +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - -
-

testClassStaticProperty

-
-

Packages > test-suite-a > TestClass > testClassStaticProperty

-
-
-

Test static class property

-
-
-

Signature

static testClassStaticProperty: (foo: number) => string; -

Type: (foo: number) => string

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/virtualmethod-method.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/virtualmethod-method.html deleted file mode 100644 index cd2dc520c6b9..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testclass-class/virtualmethod-method.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - -
-

virtualMethod

-
-

Packages > test-suite-a > TestClass > virtualMethod()

-
-
-

Overrides virtualMethod().

-
-
-

Signature

/** @override */
protected virtualMethod(): number; -
-
-

Returns

-

Return type: number

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testconst-variable.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testconst-variable.html deleted file mode 100644 index 0ce147bd98c7..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testconst-variable.html +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - -
-

testConst

-
-

Packages > test-suite-a > testConst

-
-
-

Test Constant

-
-
WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.
-
-

Signature

testConst = 42 -
-
-

Remarks

-

Here are some remarks about the variable

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testconstwithemptydeprecatedblock-variable.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testconstwithemptydeprecatedblock-variable.html deleted file mode 100644 index abfdf1c3ba7e..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testconstwithemptydeprecatedblock-variable.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - -
-

testConstWithEmptyDeprecatedBlock

-
-

Packages > test-suite-a > testConstWithEmptyDeprecatedBlock

-
-
-

I have a @deprecated tag with an empty comment block.

-
-
-

WARNING: This API is deprecated and will be removed in a future release.

-
-
-

Signature

testConstWithEmptyDeprecatedBlock: string -

Type: string

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testemptyinterface-interface/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testemptyinterface-interface/index.html deleted file mode 100644 index f5552788ae85..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testemptyinterface-interface/index.html +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - -
-

TestEmptyInterface

-
-

Packages > test-suite-a > TestEmptyInterface

-
-
-

An empty interface

-
-
-

Signature

export interface TestEmptyInterface -
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/index.html deleted file mode 100644 index c5f9b097620b..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/index.html +++ /dev/null @@ -1,96 +0,0 @@ - - - - - - -
-

TestEnum

-
-

Packages > test-suite-a > TestEnum

-
-
-

Test Enum

-
-
-

Signature

export declare enum TestEnum -
-
-

Remarks

-

Here are some remarks about the enum

-
-
-

Examples

-
-

Example 1

-

-

Some example

const foo = TestEnum.TestEnumValue1 -

-
-
-

Example 2

-

-

Another example

const bar = TestEnum.TestEnumValue2 -

-
-
-
-

Flags

- - - - - - - - - - - - - - - - - - - - - -
FlagDescription
TestEnumValue1Test enum value 1 (string)
TestEnumValue2Test enum value 2 (number)
TestEnumValue3Test enum value 3 (default)
-
-
-
-

Test enum value 1 (string)

-
-
-

Signature

TestEnumValue1 = "test-enum-value-1" -
-
-

Remarks

-

Here are some remarks about the enum value

-
-
-

Test enum value 2 (number)

-
-
-

Signature

TestEnumValue2 = 3 -
-
-

Remarks

-

Here are some remarks about the enum value

-
-
-

Test enum value 3 (default)

-
-
-

Signature

TestEnumValue3 = 4 -
-
-

Remarks

-

Here are some remarks about the enum value

-
-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue1-enummember.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue1-enummember.html deleted file mode 100644 index 57399fb71808..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue1-enummember.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - -
-

TestEnumValue1

-
-

Packages > test-suite-a > TestEnum > TestEnumValue1

-
-
-

Test enum value 1 (string)

-
-
-

Signature

TestEnumValue1 = "test-enum-value-1" -
-
-

Remarks

-

Here are some remarks about the enum value

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue2-enummember.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue2-enummember.html deleted file mode 100644 index ab1e131365cc..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue2-enummember.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - -
-

TestEnumValue2

-
-

Packages > test-suite-a > TestEnum > TestEnumValue2

-
-
-

Test enum value 2 (number)

-
-
-

Signature

TestEnumValue2 = 3 -
-
-

Remarks

-

Here are some remarks about the enum value

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue3-enummember.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue3-enummember.html deleted file mode 100644 index 2fc410d631bd..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue3-enummember.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - -
-

TestEnumValue3

-
-

Packages > test-suite-a > TestEnum > TestEnumValue3

-
-
-

Test enum value 3 (default)

-
-
-

Signature

TestEnumValue3 = 4 -
-
-

Remarks

-

Here are some remarks about the enum value

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunction-function.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunction-function.html deleted file mode 100644 index 34889dcf7286..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunction-function.html +++ /dev/null @@ -1,84 +0,0 @@ - - - - - - -
-

testFunction

-
-

Packages > test-suite-a > testFunction(testParameter, testOptionalParameter)

-
-
-

Test function

-
-
WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.
-
-

Signature

export declare function testFunction<TTypeParameter extends TestInterface = TestInterface>(testParameter: TTypeParameter, testOptionalParameter?: TTypeParameter): TTypeParameter; -

-

-

Type Parameters

- - - - - - - - - - - - - - - - - -
ParameterConstraintDefaultDescription
TTypeParameterTestInterfaceTestInterfaceA test type parameter
-
-

-
-
-

Remarks

-

This is a test link to another API member

-
-
-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - -
ParameterModifiersTypeDescription
testParameterTTypeParameterA test parameter
testOptionalParameteroptionalTTypeParameter
-
-
-

Returns

-

The provided parameter

-

Return type: TTypeParameter

-
-
-

Throws

-

An Error when something bad happens.

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturninginlinetype-function.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturninginlinetype-function.html deleted file mode 100644 index 7e7062b3ec7a..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturninginlinetype-function.html +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - -
-

testFunctionReturningInlineType

-
-

Packages > test-suite-a > testFunctionReturningInlineType()

-
-
-

Test function that returns an inline type

-
-
-

Signature

export declare function testFunctionReturningInlineType(): {
foo: number;
bar: TestEnum;
}; -
-
-

Returns

-

An inline type

-

Return type: { foo: number; bar: TestEnum; }

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturningintersectiontype-function.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturningintersectiontype-function.html deleted file mode 100644 index 25f716239136..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturningintersectiontype-function.html +++ /dev/null @@ -1,28 +0,0 @@ - - - - - - -
-

testFunctionReturningIntersectionType

-
-

Packages > test-suite-a > testFunctionReturningIntersectionType()

-
-
-

Test function that returns an inline type

-
-
-

WARNING: This API is deprecated and will be removed in a future release.

This is a test deprecation notice. Here is a link to something else!

-
-
-

Signature

export declare function testFunctionReturningIntersectionType(): TestEmptyInterface & TestInterfaceWithTypeParameter<number>; -
-
-

Returns

-

an intersection type

-

Return type: TestEmptyInterface & TestInterfaceWithTypeParameter<number>

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturninguniontype-function.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturninguniontype-function.html deleted file mode 100644 index 5a5999633ab7..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testfunctionreturninguniontype-function.html +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - -
-

testFunctionReturningUnionType

-
-

Packages > test-suite-a > testFunctionReturningUnionType()

-
-
-

Test function that returns an inline type

-
-
-

Signature

export declare function testFunctionReturningUnionType(): string | TestInterface; -
-
-

Returns

-

A union type

-

Return type: string | TestInterface

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call_-callsignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call_-callsignature.html deleted file mode 100644 index 1bb3cec8d9c6..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call_-callsignature.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - -
-

(event: 'testCallSignature', listener: (input: unknown) => void): any

-
-

Packages > test-suite-a > TestInterface > (event: 'testCallSignature', listener: (input: unknown) => void): any

-
-
-

Test interface event call signature

-
-
-

Signature

(event: 'testCallSignature', listener: (input: unknown) => void): any; -
-
-

Remarks

-

Here are some remarks about the event call signature

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call__1-callsignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call__1-callsignature.html deleted file mode 100644 index 1ebbf183381e..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call__1-callsignature.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - -
-

(event: 'anotherTestCallSignature', listener: (input: number) => string): number

-
-

Packages > test-suite-a > TestInterface > (event: 'anotherTestCallSignature', listener: (input: number) => string): number

-
-
-

Another example call signature

-
-
-

Signature

(event: 'anotherTestCallSignature', listener: (input: number) => string): number; -
-
-

Remarks

-

Here are some remarks about the event call signature

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_new_-constructsignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_new_-constructsignature.html deleted file mode 100644 index cacb80c9c0d1..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_new_-constructsignature.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - -
-

new (): TestInterface

-
-

Packages > test-suite-a > TestInterface > new (): TestInterface

-
-
-

Test construct signature.

-
-
-

Signature

new (): TestInterface; -
-
-

Returns

-

Return type: TestInterface

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/getterproperty-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/getterproperty-property.html deleted file mode 100644 index c24cbf5dc74e..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/getterproperty-property.html +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - -
-

getterProperty

-
-

Packages > test-suite-a > TestInterface > getterProperty

-
-
-

A test getter-only interface property.

-
-
-

Signature

get getterProperty(): boolean; -

Type: boolean

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/index.html deleted file mode 100644 index cffec89b7906..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/index.html +++ /dev/null @@ -1,162 +0,0 @@ - - - - - - -
-

TestInterface

-
-

Packages > test-suite-a > TestInterface

-
-
-

Test interface

-
-
-

Signature

export interface TestInterface -
-
-

Remarks

-

Here are some remarks about the interface

-
-
-

Construct Signatures

- - - - - - - - - - - - - - - -
ConstructSignatureReturn TypeDescription
new (): TestInterfaceTestInterfaceTest construct signature.
-
-
-

Events

- - - - - - - - - - - - - - - - - -
PropertyModifiersTypeDescription
testClassEventPropertyreadonly() => voidTest interface event property
-
-
-

Properties

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PropertyModifiersDefault ValueTypeDescription
getterPropertyreadonlybooleanA test getter-only interface property.
propertyWithBadInheritDocTargetboolean
setterPropertybooleanA test property with a getter and a setter.
testInterfacePropertynumberTest interface property
testOptionalInterfacePropertyoptional0numberTest optional property
-
-
-

Methods

- - - - - - - - - - - - - - - -
MethodReturn TypeDescription
testInterfaceMethod()voidTest interface method
-
-
-

Call Signatures

- - - - - - - - - - - - - - - - - -
CallSignatureDescription
(event: 'testCallSignature', listener: (input: unknown) => void): anyTest interface event call signature
(event: 'anotherTestCallSignature', listener: (input: number) => string): numberAnother example call signature
-
-
-

See Also

-

testInterfaceMethod()

-

testInterfaceProperty

-

testOptionalInterfaceProperty

-

testClassEventProperty

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature.html deleted file mode 100644 index 4bacb75a530a..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature.html +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - -
-

propertyWithBadInheritDocTarget

-
-

Packages > test-suite-a > TestInterface > propertyWithBadInheritDocTarget

-
-
-

-
-
-

Signature

propertyWithBadInheritDocTarget: boolean; -

Type: boolean

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/setterproperty-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/setterproperty-property.html deleted file mode 100644 index 8a170ed0040e..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/setterproperty-property.html +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - -
-

setterProperty

-
-

Packages > test-suite-a > TestInterface > setterProperty

-
-
-

A test property with a getter and a setter.

-
-
-

Signature

get setterProperty(): boolean;


set setterProperty(newValue: boolean); -

Type: boolean

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testclasseventproperty-propertysignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testclasseventproperty-propertysignature.html deleted file mode 100644 index cc3e3982f7a2..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testclasseventproperty-propertysignature.html +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - -
-

testClassEventProperty

-
-

Packages > test-suite-a > TestInterface > testClassEventProperty

-
-
-

Test interface event property

-
-
-

Signature

readonly testClassEventProperty: () => void; -

Type: () => void

-
-
-

Remarks

-

Here are some remarks about the event property

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfacemethod-methodsignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfacemethod-methodsignature.html deleted file mode 100644 index 488753fe08a4..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfacemethod-methodsignature.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - -
-

testInterfaceMethod

-
-

Packages > test-suite-a > TestInterface > testInterfaceMethod()

-
-
-

Test interface method

-
-
-

Signature

testInterfaceMethod(): void; -
-
-

Remarks

-

Here are some remarks about the method

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature.html deleted file mode 100644 index 78743f3ec621..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature.html +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - -
-

testInterfaceProperty

-
-

Packages > test-suite-a > TestInterface > testInterfaceProperty

-
-
-

Test interface property

-
-
-

Signature

testInterfaceProperty: number; -

Type: number

-
-
-

Remarks

-

Here are some remarks about the property

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature.html deleted file mode 100644 index 38d4d1e34c97..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature.html +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - -
-

testOptionalInterfaceProperty

-
-

Packages > test-suite-a > TestInterface > testOptionalInterfaceProperty

-
-
-

Test optional property

-
-
-

Signature

testOptionalInterfaceProperty?: number; -

Type: number

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/index.html deleted file mode 100644 index 6d103c866d97..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/index.html +++ /dev/null @@ -1,52 +0,0 @@ - - - - - - -
-

TestInterfaceExtendingOtherInterfaces

-
-

Packages > test-suite-a > TestInterfaceExtendingOtherInterfaces

-
-
-

Test interface that extends other interfaces

-
-
-

Signature

export interface TestInterfaceExtendingOtherInterfaces extends TestInterface, TestMappedType, TestInterfaceWithTypeParameter<number> -

Extends: TestInterface, TestMappedType, TestInterfaceWithTypeParameter<number>

-
-
-

Remarks

-

Here are some remarks about the interface

-
-
-

Methods

- - - - - - - - - - - - - - - -
MethodReturn TypeDescription
testMethod(input)numberTest interface method accepting a string and returning a number.
-
-
-

See Also

-

-

- TestInterface

-

- TestInterfaceWithTypeParameter

-

- TestMappedType

-

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature.html deleted file mode 100644 index 255cc2a629fd..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature.html +++ /dev/null @@ -1,48 +0,0 @@ - - - - - - -
-

testMethod

-
-

Packages > test-suite-a > TestInterfaceExtendingOtherInterfaces > testMethod(input)

-
-
-

Test interface method accepting a string and returning a number.

-
-
-

Signature

testMethod(input: string): number; -
-
-

Remarks

-

Here are some remarks about the method

-
-
-

Parameters

- - - - - - - - - - - - - - - -
ParameterTypeDescription
inputstringA string
-
-
-

Returns

-

A number

-

Return type: number

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature.html deleted file mode 100644 index fdd8de4c6fe4..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature.html +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - -
-

[foo: number]: { bar: string; }

-
-

Packages > test-suite-a > TestInterfaceWithIndexSignature > [foo: number]: { bar: string; }

-
-
-

Test index signature.

-
-
-

Signature

[foo: number]: {
bar: string;
}; -
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/index.html deleted file mode 100644 index f4a88fee87e9..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/index.html +++ /dev/null @@ -1,37 +0,0 @@ - - - - - - -
-

TestInterfaceWithIndexSignature

-
-

Packages > test-suite-a > TestInterfaceWithIndexSignature

-
-
-

An interface with an index signature.

-
-
-

Signature

export interface TestInterfaceWithIndexSignature -
-
-

Index Signatures

- - - - - - - - - - - - - -
IndexSignatureDescription
[foo: number]: { bar: string; }Test index signature.
-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/index.html deleted file mode 100644 index 113f38820f3a..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/index.html +++ /dev/null @@ -1,62 +0,0 @@ - - - - - - -
-

TestInterfaceWithTypeParameter

-
-

Packages > test-suite-a > TestInterfaceWithTypeParameter

-
-
-

Test interface with generic type parameter

-
-
-

Signature

export interface TestInterfaceWithTypeParameter<T> -

-

-

Type Parameters

- - - - - - - - - - - - - -
ParameterDescription
TA type parameter
-
-

-
-
-

Remarks

-

Here are some remarks about the interface

-
-
-

Properties

- - - - - - - - - - - - - - - -
PropertyTypeDescription
testPropertyTA test interface property using generic type parameter
-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature.html deleted file mode 100644 index 639a4ff429b0..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature.html +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - -
-

testProperty

-
-

Packages > test-suite-a > TestInterfaceWithTypeParameter > testProperty

-
-
-

A test interface property using generic type parameter

-
-
-

Signature

testProperty: T; -

Type: T

-
-
-

Remarks

-

Here are some remarks about the property

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmappedtype-typealias/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmappedtype-typealias/index.html deleted file mode 100644 index 864c6083ff7b..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmappedtype-typealias/index.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - -
-

TestMappedType

-
-

Packages > test-suite-a > TestMappedType

-
-
-

Test Mapped Type, using TestEnum

-
-
-

Signature

export type TestMappedType = {
[K in TestEnum]: boolean;
}; -
-
-

Remarks

-

Here are some remarks about the mapped type

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/foo-variable.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/foo-variable.html deleted file mode 100644 index ca8b80f47e50..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/foo-variable.html +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - -
-

foo

-
-

Packages > test-suite-a > TestModule > foo

-
-
-

Test constant in module.

-
-
-

Signature

foo = 2 -
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/index.html deleted file mode 100644 index 96667a9e9517..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/index.html +++ /dev/null @@ -1,35 +0,0 @@ - - - - - - -
-

TestModule

-
-

Packages > test-suite-a > TestModule

-
-
-

Variables

- - - - - - - - - - - - - - - - - -
VariableModifiersTypeDescription
fooreadonlyTest constant in module.
-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/index.html deleted file mode 100644 index b58d65593523..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/index.html +++ /dev/null @@ -1,168 +0,0 @@ - - - - - - -
-

TestNamespace

-
-

Packages > test-suite-a > TestNamespace

-
-
-

Test Namespace

-
-
-

Signature

export declare namespace TestNamespace -
-
-

Remarks

-

Here are some remarks about the namespace

-
-
-

Examples

-
-

Example: TypeScript Example

-

-

const foo: Foo = {
bar: "Hello world!";
baz = 42;
}; -

-
-
-

Example: JavaScript Example

-

-

const foo = {
bar: "Hello world!";
baz = 42;
}; -

-
-
-
-

Interfaces

- - - - - - - - - - - - - - - -
InterfaceAlertsDescription
TestInterfaceAlphaTest interface
-
-
-

Classes

- - - - - - - - - - - - - -
ClassDescription
TestClassTest class
-
-
-

Enumerations

- - - - - - - - - - - - - -
EnumDescription
TestEnumTest Enum
-
-
-

Types

- - - - - - - - - - - - - -
TypeAliasDescription
TestTypeAliasTest Type-Alias
-
-
-

Functions

- - - - - - - - - - - - - - - -
FunctionReturn TypeDescription
testFunction(testParameter)numberTest function
-
-
-

Variables

- - - - - - - - - - - - - - - - - - - -
VariableAlertsModifiersTypeDescription
TestConstBetareadonlyTest Constant
-
-
-

Namespaces

- - - - - - - - - - - - - -
NamespaceDescription
TestSubNamespaceTest sub-namespace
-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor.html deleted file mode 100644 index 58e53c22695c..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor.html +++ /dev/null @@ -1,39 +0,0 @@ - - - - - - -
-

(constructor)

-
-

Packages > test-suite-a > TestNamespace > TestClass > (constructor)(testClassProperty)

-
-
-

Test class constructor

-
-
-

Signature

constructor(testClassProperty: string); -
-
-

Parameters

- - - - - - - - - - - - - - - -
ParameterTypeDescription
testClassPropertystringSee testClassProperty
-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/index.html deleted file mode 100644 index b488f1d60c02..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/index.html +++ /dev/null @@ -1,77 +0,0 @@ - - - - - - -
-

TestClass

-
-

Packages > test-suite-a > TestNamespace > TestClass

-
-
-

Test class

-
-
-

Signature

class TestClass -
-
-

Constructors

- - - - - - - - - - - - - -
ConstructorDescription
(constructor)(testClassProperty)Test class constructor
-
-
-

Properties

- - - - - - - - - - - - - - - - - -
PropertyModifiersTypeDescription
testClassPropertyreadonlystringTest interface property
-
-
-

Methods

- - - - - - - - - - - - - - - -
MethodReturn TypeDescription
testClassMethod(testParameter)Promise<string>Test class method
-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method.html deleted file mode 100644 index 4182400579e8..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method.html +++ /dev/null @@ -1,52 +0,0 @@ - - - - - - -
-

testClassMethod

-
-

Packages > test-suite-a > TestNamespace > TestClass > testClassMethod(testParameter)

-
-
-

Test class method

-
-
-

Signature

testClassMethod(testParameter: string): Promise<string>; -
-
-

Parameters

- - - - - - - - - - - - - - - -
ParameterTypeDescription
testParameterstringA string
-
-
-

Returns

-

A Promise

-

Return type: Promise<string>

-
-
-

Throws

-

An Error when something happens for which an error should be thrown. Except in the cases where another kind of error is thrown. We don't throw this error in those cases.

-

-

A different kind of error when a thing happens, but not when the first kind of error is thrown instead.

-

😁

-

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property.html deleted file mode 100644 index 601113c407fd..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property.html +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - -
-

testClassProperty

-
-

Packages > test-suite-a > TestNamespace > TestClass > testClassProperty

-
-
-

Test interface property

-
-
-

Signature

readonly testClassProperty: string; -

Type: string

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testconst-variable.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testconst-variable.html deleted file mode 100644 index 881248685062..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testconst-variable.html +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - -
-

TestConst

-
-

Packages > test-suite-a > TestNamespace > TestConst

-
-
-

Test Constant

-
-
WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.
-
-

Signature

TestConst = "Hello world!" -
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/index.html deleted file mode 100644 index aadd401dd9e2..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/index.html +++ /dev/null @@ -1,55 +0,0 @@ - - - - - - -
-

TestEnum

-
-

Packages > test-suite-a > TestNamespace > TestEnum

-
-
-

Test Enum

-
-
-

Signature

enum TestEnum -
-
-

Flags

- - - - - - - - - - - - - - - - - -
FlagDescription
TestEnumValue1Test enum value 1
TestEnumValue2Test enum value 2
-
-
-
-

Test enum value 1

-
-
-

Signature

TestEnumValue1 = 0 -
-
-

Test enum value 2

-
-
-

Signature

TestEnumValue2 = 1 -
-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember.html deleted file mode 100644 index fcda24ca526d..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember.html +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - -
-

TestEnumValue1

-
-

Packages > test-suite-a > TestNamespace > TestEnum > TestEnumValue1

-
-
-

Test enum value 1

-
-
-

Signature

TestEnumValue1 = 0 -
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember.html deleted file mode 100644 index f5a95a5acb7c..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember.html +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - -
-

TestEnumValue2

-
-

Packages > test-suite-a > TestNamespace > TestEnum > TestEnumValue2

-
-
-

Test enum value 2

-
-
-

Signature

TestEnumValue2 = 1 -
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testfunction-function.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testfunction-function.html deleted file mode 100644 index deb8e56b5aec..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testfunction-function.html +++ /dev/null @@ -1,48 +0,0 @@ - - - - - - -
-

testFunction

-
-

Packages > test-suite-a > TestNamespace > testFunction(testParameter)

-
-
-

Test function

-
-
-

Signature

function testFunction(testParameter: number): number; -
-
-

Parameters

- - - - - - - - - - - - - - - -
ParameterTypeDescription
testParameternumber
-
-
-

Returns

-

A number

-

Return type: number

-
-
-

Throws

-

An Error

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/index.html deleted file mode 100644 index c5d44d04aded..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/index.html +++ /dev/null @@ -1,64 +0,0 @@ - - - - - - -
-

TestInterface

-
-

Packages > test-suite-a > TestNamespace > TestInterface

-
-
-

Test interface

-
-
WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.
-
-

Signature

interface TestInterface extends TestInterfaceWithTypeParameter<TestEnum> -

Extends: TestInterfaceWithTypeParameter<TestEnum>

-
-
-

Properties

- - - - - - - - - - - - - - - - - -
PropertyAlertsTypeDescription
testInterfacePropertyAlphabooleanTest interface property
-
-
-

Methods

- - - - - - - - - - - - - - - - - -
MethodAlertsReturn TypeDescription
testInterfaceMethod()AlphavoidTest interface method
-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature.html deleted file mode 100644 index 3b489d5671ab..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature.html +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - -
-

testInterfaceMethod

-
-

Packages > test-suite-a > TestNamespace > TestInterface > testInterfaceMethod()

-
-
-

Test interface method

-
-
WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.
-
-

Signature

testInterfaceMethod(): void; -
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature.html deleted file mode 100644 index 86286ff0e9c3..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature.html +++ /dev/null @@ -1,22 +0,0 @@ - - - - - - -
-

testInterfaceProperty

-
-

Packages > test-suite-a > TestNamespace > TestInterface > testInterfaceProperty

-
-
-

Test interface property

-
-
WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.
-
-

Signature

testInterfaceProperty: boolean; -

Type: boolean

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testsubnamespace-namespace/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testsubnamespace-namespace/index.html deleted file mode 100644 index 48fc6ff9b0d4..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testsubnamespace-namespace/index.html +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - -
-

TestSubNamespace

-
-

Packages > test-suite-a > TestNamespace > TestSubNamespace

-
-
-

Test sub-namespace

-
-
-

Signature

namespace TestSubNamespace -
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testtypealias-typealias/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testtypealias-typealias/index.html deleted file mode 100644 index 89c03a3b2c02..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testtypealias-typealias/index.html +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - -
-

TestTypeAlias

-
-

Packages > test-suite-a > TestNamespace > TestTypeAlias

-
-
-

Test Type-Alias

-
-
-

Signature

type TestTypeAlias = boolean; -
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/typealias-typealias/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/typealias-typealias/index.html deleted file mode 100644 index 6b10e181bd48..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-a/typealias-typealias/index.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - -
-

TypeAlias

-
-

Packages > test-suite-a > TypeAlias

-
-
-

Test Type-Alias

-
-
-

Signature

export type TypeAlias = string; -
-
-

Remarks

-

Here are some remarks about the type alias

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/foo-interface/bar-propertysignature.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/foo-interface/bar-propertysignature.html deleted file mode 100644 index ba0cf8d6a230..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/foo-interface/bar-propertysignature.html +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - -
-

bar

-
-

Packages > test-suite-b > Foo > bar

-
-
-

Test Enum

-
-
-

Signature

bar: TestEnum; -

Type: TestEnum

-
-
-

Remarks

-

Here are some remarks about the enum

-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/foo-interface/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/foo-interface/index.html deleted file mode 100644 index 02971c93289e..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/foo-interface/index.html +++ /dev/null @@ -1,39 +0,0 @@ - - - - - - -
-

Foo

-
-

Packages > test-suite-b > Foo

-
-
-

Bar

-
-
-

Signature

export interface Foo -
-
-

Properties

- - - - - - - - - - - - - - - -
PropertyTypeDescription
barTestEnumTest Enum
-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/index.html deleted file mode 100644 index 37ab3d58ea5b..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/test-suite-b/index.html +++ /dev/null @@ -1,31 +0,0 @@ - - - - - - -
-

test-suite-b

-
-

Packages > test-suite-b

-
-
-

Interfaces

- - - - - - - - - - - - - -
InterfaceDescription
FooBar
-
-
- - diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/index.md deleted file mode 100644 index d8ae823a9570..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/index.md +++ /dev/null @@ -1,8 +0,0 @@ -# API Overview - -## Packages - -| Package | Description | -| --- | --- | -| [test-suite-a](./test-suite-a/) | Test package | -| [test-suite-b](./test-suite-b/) | | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/index.md deleted file mode 100644 index 39d59df9e9ed..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/index.md +++ /dev/null @@ -1,92 +0,0 @@ -# test-suite-a - -[Packages](./) > [test-suite-a](./test-suite-a/) - -Test package - -## Remarks {#test-suite-a-remarks} - -This remarks block includes a bulleted list! - -- Bullet 1 - -- Bullet 2 - -And an ordered list for good measure! - -1. List item 1 - -2. List item 2 - -3. List item 3 - -Also, here is a link test, including a bad link, because we should have some reasonable support if this happens: - -- Good link (no alias): [TestClass](./test-suite-a/testclass-class/) - -- Good link (with alias): [function alias text](./test-suite-a/testfunction-function) - -- Bad link (no alias): _InvalidItem_ - -- Bad link (with alias): _even though I link to an invalid item, I would still like this text to be rendered_ - -## Example {#test-suite-a-example} - -A test example - -```typescript -const foo = bar; -``` - -## Interfaces - -| Interface | Description | -| --- | --- | -| [TestEmptyInterface](./test-suite-a/testemptyinterface-interface/) | An empty interface | -| [TestInterface](./test-suite-a/testinterface-interface/) | Test interface | -| [TestInterfaceExtendingOtherInterfaces](./test-suite-a/testinterfaceextendingotherinterfaces-interface/) | Test interface that extends other interfaces | -| [TestInterfaceWithIndexSignature](./test-suite-a/testinterfacewithindexsignature-interface/) | An interface with an index signature. | -| [TestInterfaceWithTypeParameter](./test-suite-a/testinterfacewithtypeparameter-interface/) | Test interface with generic type parameter | - -## Classes - -| Class | Description | -| --- | --- | -| [TestAbstractClass](./test-suite-a/testabstractclass-class/) | A test abstract class. | -| [TestClass](./test-suite-a/testclass-class/) | Test class | - -## Enumerations - -| Enum | Description | -| --- | --- | -| [TestEnum](./test-suite-a/testenum-enum/) | Test Enum | - -## Types - -| TypeAlias | Description | -| --- | --- | -| [TestMappedType](./test-suite-a/testmappedtype-typealias/) | Test Mapped Type, using [TestEnum](./test-suite-a/testenum-enum/) | -| [TypeAlias](./test-suite-a/typealias-typealias/) | Test Type-Alias | - -## Functions - -| Function | Alerts | Return Type | Description | -| --- | --- | --- | --- | -| [testFunction(testParameter, testOptionalParameter)](./test-suite-a/testfunction-function) | `Alpha` | TTypeParameter | Test function | -| [testFunctionReturningInlineType()](./test-suite-a/testfunctionreturninginlinetype-function) | | { foo: number; bar: [TestEnum](./test-suite-a/testenum-enum/); } | Test function that returns an inline type | -| [testFunctionReturningIntersectionType()](./test-suite-a/testfunctionreturningintersectiontype-function) | `Deprecated` | [TestEmptyInterface](./test-suite-a/testemptyinterface-interface/) & [TestInterfaceWithTypeParameter](./test-suite-a/testinterfacewithtypeparameter-interface/)<number> | Test function that returns an inline type | -| [testFunctionReturningUnionType()](./test-suite-a/testfunctionreturninguniontype-function) | | string \| [TestInterface](./test-suite-a/testinterface-interface/) | Test function that returns an inline type | - -## Variables - -| Variable | Alerts | Modifiers | Type | Description | -| --- | --- | --- | --- | --- | -| [testConst](./test-suite-a/testconst-variable) | `Beta` | `readonly` | | Test Constant | -| [testConstWithEmptyDeprecatedBlock](./test-suite-a/testconstwithemptydeprecatedblock-variable) | `Deprecated` | `readonly` | string | I have a `@deprecated` tag with an empty comment block. | - -## Namespaces - -| Namespace | Description | -| --- | --- | -| [TestModule](./test-suite-a/testmodule-namespace/) | | -| [TestNamespace](./test-suite-a/testnamespace-namespace/) | Test Namespace | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/_constructor_-constructor.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/_constructor_-constructor.md deleted file mode 100644 index e841a169957e..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/_constructor_-constructor.md +++ /dev/null @@ -1,18 +0,0 @@ -# (constructor) - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestAbstractClass](./test-suite-a/testabstractclass-class/) > [(constructor)(privateProperty, protectedProperty)](./test-suite-a/testabstractclass-class/_constructor_-constructor) - -This is a _{@customTag constructor}_. - -## Signature {#\_constructor\_-signature} - -```typescript -protected constructor(privateProperty: number, protectedProperty: TestEnum); -``` - -## Parameters {#\_constructor\_-parameters} - -| Parameter | Type | Description | -| --- | --- | --- | -| privateProperty | number | | -| protectedProperty | [TestEnum](./test-suite-a/testenum-enum/) | | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/abstractpropertygetter-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/abstractpropertygetter-property.md deleted file mode 100644 index b80f6ae7e538..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/abstractpropertygetter-property.md +++ /dev/null @@ -1,13 +0,0 @@ -# abstractPropertyGetter - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestAbstractClass](./test-suite-a/testabstractclass-class/) > [abstractPropertyGetter](./test-suite-a/testabstractclass-class/abstractpropertygetter-property) - -A test abstract getter property. - -## Signature {#abstractpropertygetter-signature} - -```typescript -abstract get abstractPropertyGetter(): TestMappedType; -``` - -**Type:** [TestMappedType](./test-suite-a/testmappedtype-typealias/) diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/index.md deleted file mode 100644 index 355797f91c4e..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/index.md +++ /dev/null @@ -1,32 +0,0 @@ -# TestAbstractClass - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestAbstractClass](./test-suite-a/testabstractclass-class/) - -A test abstract class. - -## Signature {#testabstractclass-signature} - -```typescript -export declare abstract class TestAbstractClass -``` - -## Constructors - -| Constructor | Description | -| --- | --- | -| [(constructor)(privateProperty, protectedProperty)](./test-suite-a/testabstractclass-class/_constructor_-constructor) | This is a _{@customTag constructor}_. | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [abstractPropertyGetter](./test-suite-a/testabstractclass-class/abstractpropertygetter-property) | `readonly` | [TestMappedType](./test-suite-a/testmappedtype-typealias/) | A test abstract getter property. | -| [protectedProperty](./test-suite-a/testabstractclass-class/protectedproperty-property) | `readonly` | [TestEnum](./test-suite-a/testenum-enum/) | A test protected property. | - -## Methods - -| Method | Modifiers | Return Type | Description | -| --- | --- | --- | --- | -| [publicAbstractMethod()](./test-suite-a/testabstractclass-class/publicabstractmethod-method) | | void | A test public abstract method. | -| [sealedMethod()](./test-suite-a/testabstractclass-class/sealedmethod-method) | `sealed` | string | A test `@sealed` method. | -| [virtualMethod()](./test-suite-a/testabstractclass-class/virtualmethod-method) | `virtual` | number | A test `@virtual` method. | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/protectedproperty-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/protectedproperty-property.md deleted file mode 100644 index 29ad04377551..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/protectedproperty-property.md +++ /dev/null @@ -1,13 +0,0 @@ -# protectedProperty - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestAbstractClass](./test-suite-a/testabstractclass-class/) > [protectedProperty](./test-suite-a/testabstractclass-class/protectedproperty-property) - -A test protected property. - -## Signature {#protectedproperty-signature} - -```typescript -protected readonly protectedProperty: TestEnum; -``` - -**Type:** [TestEnum](./test-suite-a/testenum-enum/) diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/publicabstractmethod-method.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/publicabstractmethod-method.md deleted file mode 100644 index a4fa120e1ab6..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/publicabstractmethod-method.md +++ /dev/null @@ -1,11 +0,0 @@ -# publicAbstractMethod - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestAbstractClass](./test-suite-a/testabstractclass-class/) > [publicAbstractMethod()](./test-suite-a/testabstractclass-class/publicabstractmethod-method) - -A test public abstract method. - -## Signature {#publicabstractmethod-signature} - -```typescript -abstract publicAbstractMethod(): void; -``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/sealedmethod-method.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/sealedmethod-method.md deleted file mode 100644 index 12d56cb8db70..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/sealedmethod-method.md +++ /dev/null @@ -1,18 +0,0 @@ -# sealedMethod - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestAbstractClass](./test-suite-a/testabstractclass-class/) > [sealedMethod()](./test-suite-a/testabstractclass-class/sealedmethod-method) - -A test `@sealed` method. - -## Signature {#sealedmethod-signature} - -```typescript -/** @sealed */ -protected sealedMethod(): string; -``` - -## Returns {#sealedmethod-returns} - -A string! - -**Return type:** string diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/virtualmethod-method.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/virtualmethod-method.md deleted file mode 100644 index 09e47b29d7c9..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testabstractclass-class/virtualmethod-method.md +++ /dev/null @@ -1,18 +0,0 @@ -# virtualMethod - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestAbstractClass](./test-suite-a/testabstractclass-class/) > [virtualMethod()](./test-suite-a/testabstractclass-class/virtualmethod-method) - -A test `@virtual` method. - -## Signature {#virtualmethod-signature} - -```typescript -/** @virtual */ -protected virtualMethod(): number; -``` - -## Returns {#virtualmethod-returns} - -A number! - -**Return type:** number diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/_constructor_-constructor.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/_constructor_-constructor.md deleted file mode 100644 index 900d4e2a0c1e..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/_constructor_-constructor.md +++ /dev/null @@ -1,24 +0,0 @@ -# (constructor) - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [(constructor)(privateProperty, protectedProperty, testClassProperty, testClassEventProperty)](./test-suite-a/testclass-class/_constructor_-constructor) - -Test class constructor - -## Signature {#\_constructor\_-signature} - -```typescript -constructor(privateProperty: number, protectedProperty: TestEnum, testClassProperty: TTypeParameterB, testClassEventProperty: () => void); -``` - -## Remarks {#\_constructor\_-remarks} - -Here are some remarks about the constructor - -## Parameters {#\_constructor\_-parameters} - -| Parameter | Type | Description | -| --- | --- | --- | -| privateProperty | number | See [TestAbstractClass](./test-suite-a/testabstractclass-class/)'s constructor. | -| protectedProperty | [TestEnum](./test-suite-a/testenum-enum/) |

Some notes about the parameter.

See protectedProperty.

| -| testClassProperty | TTypeParameterB | See [testClassProperty](./test-suite-a/testclass-class/testclassproperty-property). | -| testClassEventProperty | () => void | See [testClassEventProperty](./test-suite-a/testclass-class/testclasseventproperty-property). | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/abstractpropertygetter-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/abstractpropertygetter-property.md deleted file mode 100644 index 7f04e03f8c49..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/abstractpropertygetter-property.md +++ /dev/null @@ -1,13 +0,0 @@ -# abstractPropertyGetter - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [abstractPropertyGetter](./test-suite-a/testclass-class/abstractpropertygetter-property) - -A test abstract getter property. - -## Signature {#abstractpropertygetter-signature} - -```typescript -get abstractPropertyGetter(): TestMappedType; -``` - -**Type:** [TestMappedType](./test-suite-a/testmappedtype-typealias/) diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/index.md deleted file mode 100644 index c37ae228439e..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/index.md +++ /dev/null @@ -1,68 +0,0 @@ -# TestClass - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) - -Test class - -## Signature {#testclass-signature} - -```typescript -export declare class TestClass extends TestAbstractClass -``` - -**Extends:** [TestAbstractClass](./test-suite-a/testabstractclass-class/) - -### Type Parameters - -| Parameter | Description | -| --- | --- | -| TTypeParameterA | A type parameter | -| TTypeParameterB | Another type parameter | - -## Remarks {#testclass-remarks} - -Here are some remarks about the class - -## Constructors - -| Constructor | Description | -| --- | --- | -| [(constructor)(privateProperty, protectedProperty, testClassProperty, testClassEventProperty)](./test-suite-a/testclass-class/_constructor_-constructor) | Test class constructor | - -## Static Properties - -| Property | Type | Description | -| --- | --- | --- | -| [testClassStaticProperty](./test-suite-a/testclass-class/testclassstaticproperty-property) | (foo: number) => string | Test static class property | - -## Static Methods - -| Method | Return Type | Description | -| --- | --- | --- | -| [testClassStaticMethod(foo)](./test-suite-a/testclass-class/testclassstaticmethod-method) | string | Test class static method | - -## Events - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [testClassEventProperty](./test-suite-a/testclass-class/testclasseventproperty-property) | `readonly` | () => void | Test class event property | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [abstractPropertyGetter](./test-suite-a/testclass-class/abstractpropertygetter-property) | `readonly` | [TestMappedType](./test-suite-a/testmappedtype-typealias/) | A test abstract getter property. | -| [testClassGetterProperty](./test-suite-a/testclass-class/testclassgetterproperty-property) | `virtual` | number | Test class property with both a getter and a setter. | -| [testClassProperty](./test-suite-a/testclass-class/testclassproperty-property) | `readonly` | TTypeParameterB | Test class property | - -## Methods - -| Method | Modifiers | Return Type | Description | -| --- | --- | --- | --- | -| [publicAbstractMethod()](./test-suite-a/testclass-class/publicabstractmethod-method) | | void | A test public abstract method. | -| [testClassMethod(input)](./test-suite-a/testclass-class/testclassmethod-method) | `sealed` | TTypeParameterA | Test class method | -| [virtualMethod()](./test-suite-a/testclass-class/virtualmethod-method) | | number | Overrides [virtualMethod()](./test-suite-a/testabstractclass-class/virtualmethod-method). | - -## See Also {#testclass-see-also} - -[TestAbstractClass](./test-suite-a/testabstractclass-class/) diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/publicabstractmethod-method.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/publicabstractmethod-method.md deleted file mode 100644 index 7f039a2242a7..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/publicabstractmethod-method.md +++ /dev/null @@ -1,11 +0,0 @@ -# publicAbstractMethod - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [publicAbstractMethod()](./test-suite-a/testclass-class/publicabstractmethod-method) - -A test public abstract method. - -## Signature {#publicabstractmethod-signature} - -```typescript -publicAbstractMethod(): void; -``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclasseventproperty-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclasseventproperty-property.md deleted file mode 100644 index 5309a5bebdc0..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclasseventproperty-property.md +++ /dev/null @@ -1,17 +0,0 @@ -# testClassEventProperty - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [testClassEventProperty](./test-suite-a/testclass-class/testclasseventproperty-property) - -Test class event property - -## Signature {#testclasseventproperty-signature} - -```typescript -readonly testClassEventProperty: () => void; -``` - -**Type:** () => void - -## Remarks {#testclasseventproperty-remarks} - -Here are some remarks about the property diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassgetterproperty-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassgetterproperty-property.md deleted file mode 100644 index 252f535f42c6..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassgetterproperty-property.md +++ /dev/null @@ -1,19 +0,0 @@ -# testClassGetterProperty - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [testClassGetterProperty](./test-suite-a/testclass-class/testclassgetterproperty-property) - -Test class property with both a getter and a setter. - -## Signature {#testclassgetterproperty-signature} - -```typescript -/** @virtual */ -get testClassGetterProperty(): number; -set testClassGetterProperty(newValue: number); -``` - -**Type:** number - -## Remarks {#testclassgetterproperty-remarks} - -Here are some remarks about the getter-only property diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassmethod-method.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassmethod-method.md deleted file mode 100644 index 19b30bd6dd25..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassmethod-method.md +++ /dev/null @@ -1,32 +0,0 @@ -# testClassMethod - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [testClassMethod(input)](./test-suite-a/testclass-class/testclassmethod-method) - -Test class method - -## Signature {#testclassmethod-signature} - -```typescript -/** @sealed */ -testClassMethod(input: TTypeParameterA): TTypeParameterA; -``` - -## Remarks {#testclassmethod-remarks} - -Here are some remarks about the method - -## Parameters {#testclassmethod-parameters} - -| Parameter | Type | Description | -| --- | --- | --- | -| input | TTypeParameterA | | - -## Returns {#testclassmethod-returns} - -**Return type:** TTypeParameterA - -## Throws {#testclassmethod-throws} - -Some sort of error in 1 case. - -Some other sort of error in another case. For example, a case where some thing happens. diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassproperty-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassproperty-property.md deleted file mode 100644 index 5ce1e6f7f288..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassproperty-property.md +++ /dev/null @@ -1,17 +0,0 @@ -# testClassProperty - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [testClassProperty](./test-suite-a/testclass-class/testclassproperty-property) - -Test class property - -## Signature {#testclassproperty-signature} - -```typescript -readonly testClassProperty: TTypeParameterB; -``` - -**Type:** TTypeParameterB - -## Remarks {#testclassproperty-remarks} - -Here are some remarks about the property diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticmethod-method.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticmethod-method.md deleted file mode 100644 index 25859dfec07b..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticmethod-method.md +++ /dev/null @@ -1,23 +0,0 @@ -# testClassStaticMethod - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [testClassStaticMethod(foo)](./test-suite-a/testclass-class/testclassstaticmethod-method) - -Test class static method - -## Signature {#testclassstaticmethod-signature} - -```typescript -static testClassStaticMethod(foo: number): string; -``` - -## Parameters {#testclassstaticmethod-parameters} - -| Parameter | Type | Description | -| --- | --- | --- | -| foo | number | Some number | - -## Returns {#testclassstaticmethod-returns} - -- Some string - -**Return type:** string diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticproperty-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticproperty-property.md deleted file mode 100644 index 6d6001f30f52..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/testclassstaticproperty-property.md +++ /dev/null @@ -1,13 +0,0 @@ -# testClassStaticProperty - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [testClassStaticProperty](./test-suite-a/testclass-class/testclassstaticproperty-property) - -Test static class property - -## Signature {#testclassstaticproperty-signature} - -```typescript -static testClassStaticProperty: (foo: number) => string; -``` - -**Type:** (foo: number) => string diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/virtualmethod-method.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/virtualmethod-method.md deleted file mode 100644 index 7c2df61225ed..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testclass-class/virtualmethod-method.md +++ /dev/null @@ -1,16 +0,0 @@ -# virtualMethod - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestClass](./test-suite-a/testclass-class/) > [virtualMethod()](./test-suite-a/testclass-class/virtualmethod-method) - -Overrides [virtualMethod()](./test-suite-a/testabstractclass-class/virtualmethod-method). - -## Signature {#virtualmethod-signature} - -```typescript -/** @override */ -protected virtualMethod(): number; -``` - -## Returns {#virtualmethod-returns} - -**Return type:** number diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testconst-variable.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testconst-variable.md deleted file mode 100644 index 660e92e199d6..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testconst-variable.md +++ /dev/null @@ -1,17 +0,0 @@ -# testConst - -[Packages](./) > [test-suite-a](./test-suite-a/) > [testConst](./test-suite-a/testconst-variable) - -Test Constant - -**WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.** - -## Signature {#testconst-signature} - -```typescript -testConst = 42 -``` - -## Remarks {#testconst-remarks} - -Here are some remarks about the variable diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testconstwithemptydeprecatedblock-variable.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testconstwithemptydeprecatedblock-variable.md deleted file mode 100644 index 720e219ac11c..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testconstwithemptydeprecatedblock-variable.md +++ /dev/null @@ -1,15 +0,0 @@ -# testConstWithEmptyDeprecatedBlock - -[Packages](./) > [test-suite-a](./test-suite-a/) > [testConstWithEmptyDeprecatedBlock](./test-suite-a/testconstwithemptydeprecatedblock-variable) - -I have a `@deprecated` tag with an empty comment block. - -**WARNING: This API is deprecated and will be removed in a future release.** - -## Signature {#testconstwithemptydeprecatedblock-signature} - -```typescript -testConstWithEmptyDeprecatedBlock: string -``` - -**Type:** string diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testemptyinterface-interface/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testemptyinterface-interface/index.md deleted file mode 100644 index d1f8b21536a5..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testemptyinterface-interface/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# TestEmptyInterface - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestEmptyInterface](./test-suite-a/testemptyinterface-interface/) - -An empty interface - -## Signature {#testemptyinterface-signature} - -```typescript -export interface TestEmptyInterface -``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/index.md deleted file mode 100644 index 97691f5456a2..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/index.md +++ /dev/null @@ -1,77 +0,0 @@ -# TestEnum - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestEnum](./test-suite-a/testenum-enum/) - -Test Enum - -## Signature {#testenum-signature} - -```typescript -export declare enum TestEnum -``` - -## Remarks {#testenum-remarks} - -Here are some remarks about the enum - -## Examples {#testenum-examples} - -### Example 1 {#testenum-example1} - -Some example - -```typescript -const foo = TestEnum.TestEnumValue1 -``` - -### Example 2 {#testenum-example2} - -Another example - -```ts -const bar = TestEnum.TestEnumValue2 -``` - -## Flags - -| Flag | Description | -| --- | --- | -| [TestEnumValue1](./test-suite-a/testenum-enum/testenumvalue1-enummember) | Test enum value 1 (string) | -| [TestEnumValue2](./test-suite-a/testenum-enum/testenumvalue2-enummember) | Test enum value 2 (number) | -| [TestEnumValue3](./test-suite-a/testenum-enum/testenumvalue3-enummember) | Test enum value 3 (default) | - -Test enum value 1 (string) - -### Signature {#testenumvalue1-signature} - -```typescript -TestEnumValue1 = "test-enum-value-1" -``` - -### Remarks {#testenumvalue1-remarks} - -Here are some remarks about the enum value - -Test enum value 2 (number) - -### Signature {#testenumvalue2-signature} - -```typescript -TestEnumValue2 = 3 -``` - -### Remarks {#testenumvalue2-remarks} - -Here are some remarks about the enum value - -Test enum value 3 (default) - -### Signature {#testenumvalue3-signature} - -```typescript -TestEnumValue3 = 4 -``` - -### Remarks {#testenumvalue3-remarks} - -Here are some remarks about the enum value diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue1-enummember.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue1-enummember.md deleted file mode 100644 index 28dc1db6fc13..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue1-enummember.md +++ /dev/null @@ -1,15 +0,0 @@ -# TestEnumValue1 - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestEnum](./test-suite-a/testenum-enum/) > [TestEnumValue1](./test-suite-a/testenum-enum/testenumvalue1-enummember) - -Test enum value 1 (string) - -## Signature {#testenumvalue1-signature} - -```typescript -TestEnumValue1 = "test-enum-value-1" -``` - -## Remarks {#testenumvalue1-remarks} - -Here are some remarks about the enum value diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue2-enummember.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue2-enummember.md deleted file mode 100644 index 058b0e361279..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue2-enummember.md +++ /dev/null @@ -1,15 +0,0 @@ -# TestEnumValue2 - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestEnum](./test-suite-a/testenum-enum/) > [TestEnumValue2](./test-suite-a/testenum-enum/testenumvalue2-enummember) - -Test enum value 2 (number) - -## Signature {#testenumvalue2-signature} - -```typescript -TestEnumValue2 = 3 -``` - -## Remarks {#testenumvalue2-remarks} - -Here are some remarks about the enum value diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue3-enummember.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue3-enummember.md deleted file mode 100644 index 38d5f92e2c0d..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testenum-enum/testenumvalue3-enummember.md +++ /dev/null @@ -1,15 +0,0 @@ -# TestEnumValue3 - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestEnum](./test-suite-a/testenum-enum/) > [TestEnumValue3](./test-suite-a/testenum-enum/testenumvalue3-enummember) - -Test enum value 3 (default) - -## Signature {#testenumvalue3-signature} - -```typescript -TestEnumValue3 = 4 -``` - -## Remarks {#testenumvalue3-remarks} - -Here are some remarks about the enum value diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunction-function.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunction-function.md deleted file mode 100644 index 5d6630bb2af4..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunction-function.md +++ /dev/null @@ -1,40 +0,0 @@ -# testFunction - -[Packages](./) > [test-suite-a](./test-suite-a/) > [testFunction(testParameter, testOptionalParameter)](./test-suite-a/testfunction-function) - -Test function - -**WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.** - -## Signature {#testfunction-signature} - -```typescript -export declare function testFunction(testParameter: TTypeParameter, testOptionalParameter?: TTypeParameter): TTypeParameter; -``` - -### Type Parameters - -| Parameter | Constraint | Default | Description | -| --- | --- | --- | --- | -| TTypeParameter | [TestInterface](./test-suite-a/testinterface-interface/) | [TestInterface](./test-suite-a/testinterface-interface/) | A test type parameter | - -## Remarks {#testfunction-remarks} - -This is a test [link](./test-suite-a/testinterface-interface/) to another API member - -## Parameters {#testfunction-parameters} - -| Parameter | Modifiers | Type | Description | -| --- | --- | --- | --- | -| testParameter | | TTypeParameter | A test parameter | -| testOptionalParameter | optional | TTypeParameter | | - -## Returns {#testfunction-returns} - -The provided parameter - -**Return type:** TTypeParameter - -## Throws {#testfunction-throws} - -An Error when something bad happens. diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturninginlinetype-function.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturninginlinetype-function.md deleted file mode 100644 index 9d6e2a5fb10c..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturninginlinetype-function.md +++ /dev/null @@ -1,20 +0,0 @@ -# testFunctionReturningInlineType - -[Packages](./) > [test-suite-a](./test-suite-a/) > [testFunctionReturningInlineType()](./test-suite-a/testfunctionreturninginlinetype-function) - -Test function that returns an inline type - -## Signature {#testfunctionreturninginlinetype-signature} - -```typescript -export declare function testFunctionReturningInlineType(): { - foo: number; - bar: TestEnum; -}; -``` - -## Returns {#testfunctionreturninginlinetype-returns} - -An inline type - -**Return type:** { foo: number; bar: [TestEnum](./test-suite-a/testenum-enum/); } diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturningintersectiontype-function.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturningintersectiontype-function.md deleted file mode 100644 index 5725f72cebf6..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturningintersectiontype-function.md +++ /dev/null @@ -1,21 +0,0 @@ -# testFunctionReturningIntersectionType - -[Packages](./) > [test-suite-a](./test-suite-a/) > [testFunctionReturningIntersectionType()](./test-suite-a/testfunctionreturningintersectiontype-function) - -Test function that returns an inline type - -**WARNING: This API is deprecated and will be removed in a future release.** - -_This is a test deprecation notice. Here is a_ [_link_](./test-suite-a/testfunctionreturninguniontype-function) _to something else!_ - -## Signature {#testfunctionreturningintersectiontype-signature} - -```typescript -export declare function testFunctionReturningIntersectionType(): TestEmptyInterface & TestInterfaceWithTypeParameter; -``` - -## Returns {#testfunctionreturningintersectiontype-returns} - -an intersection type - -**Return type:** [TestEmptyInterface](./test-suite-a/testemptyinterface-interface/) & [TestInterfaceWithTypeParameter](./test-suite-a/testinterfacewithtypeparameter-interface/)<number> diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturninguniontype-function.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturninguniontype-function.md deleted file mode 100644 index c5c7ef474ae1..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testfunctionreturninguniontype-function.md +++ /dev/null @@ -1,17 +0,0 @@ -# testFunctionReturningUnionType - -[Packages](./) > [test-suite-a](./test-suite-a/) > [testFunctionReturningUnionType()](./test-suite-a/testfunctionreturninguniontype-function) - -Test function that returns an inline type - -## Signature {#testfunctionreturninguniontype-signature} - -```typescript -export declare function testFunctionReturningUnionType(): string | TestInterface; -``` - -## Returns {#testfunctionreturninguniontype-returns} - -A union type - -**Return type:** string \| [TestInterface](./test-suite-a/testinterface-interface/) diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call_-callsignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call_-callsignature.md deleted file mode 100644 index 8ab0989a91c0..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call_-callsignature.md +++ /dev/null @@ -1,15 +0,0 @@ -# (event: 'testCallSignature', listener: (input: unknown) => void): any - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [(event: 'testCallSignature', listener: (input: unknown) => void): any](./test-suite-a/testinterface-interface/_call_-callsignature) - -Test interface event call signature - -## Signature {#\_call\_-signature} - -```typescript -(event: 'testCallSignature', listener: (input: unknown) => void): any; -``` - -## Remarks {#\_call\_-remarks} - -Here are some remarks about the event call signature diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call__1-callsignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call__1-callsignature.md deleted file mode 100644 index b3055d99c94c..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_call__1-callsignature.md +++ /dev/null @@ -1,15 +0,0 @@ -# (event: 'anotherTestCallSignature', listener: (input: number) => string): number - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [(event: 'anotherTestCallSignature', listener: (input: number) => string): number](./test-suite-a/testinterface-interface/_call__1-callsignature) - -Another example call signature - -## Signature {#\_call\_\_1-signature} - -```typescript -(event: 'anotherTestCallSignature', listener: (input: number) => string): number; -``` - -## Remarks {#\_call\_\_1-remarks} - -Here are some remarks about the event call signature diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_new_-constructsignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_new_-constructsignature.md deleted file mode 100644 index 5d07085f787a..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/_new_-constructsignature.md +++ /dev/null @@ -1,15 +0,0 @@ -# new (): TestInterface - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [new (): TestInterface](./test-suite-a/testinterface-interface/_new_-constructsignature) - -Test construct signature. - -## Signature {#\_new\_-signature} - -```typescript -new (): TestInterface; -``` - -## Returns {#\_new\_-returns} - -**Return type:** [TestInterface](./test-suite-a/testinterface-interface/) diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/getterproperty-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/getterproperty-property.md deleted file mode 100644 index 8ba7a2708f75..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/getterproperty-property.md +++ /dev/null @@ -1,13 +0,0 @@ -# getterProperty - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [getterProperty](./test-suite-a/testinterface-interface/getterproperty-property) - -A test getter-only interface property. - -## Signature {#getterproperty-signature} - -```typescript -get getterProperty(): boolean; -``` - -**Type:** boolean diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/index.md deleted file mode 100644 index 10a1e90a2f7d..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/index.md +++ /dev/null @@ -1,60 +0,0 @@ -# TestInterface - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) - -Test interface - -## Signature {#testinterface-signature} - -```typescript -export interface TestInterface -``` - -## Remarks {#testinterface-remarks} - -Here are some remarks about the interface - -## Construct Signatures - -| ConstructSignature | Return Type | Description | -| --- | --- | --- | -| [new (): TestInterface](./test-suite-a/testinterface-interface/_new_-constructsignature) | [TestInterface](./test-suite-a/testinterface-interface/) | Test construct signature. | - -## Events - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [testClassEventProperty](./test-suite-a/testinterface-interface/testclasseventproperty-propertysignature) | `readonly` | () => void | Test interface event property | - -## Properties - -| Property | Modifiers | Default Value | Type | Description | -| --- | --- | --- | --- | --- | -| [getterProperty](./test-suite-a/testinterface-interface/getterproperty-property) | `readonly` | | boolean | A test getter-only interface property. | -| [propertyWithBadInheritDocTarget](./test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature) | | | boolean | | -| [setterProperty](./test-suite-a/testinterface-interface/setterproperty-property) | | | boolean | A test property with a getter and a setter. | -| [testInterfaceProperty](./test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature) | | | number | Test interface property | -| [testOptionalInterfaceProperty](./test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature) | `optional` | 0 | number | Test optional property | - -## Methods - -| Method | Return Type | Description | -| --- | --- | --- | -| [testInterfaceMethod()](./test-suite-a/testinterface-interface/testinterfacemethod-methodsignature) | void | Test interface method | - -## Call Signatures - -| CallSignature | Description | -| --- | --- | -| [(event: 'testCallSignature', listener: (input: unknown) => void): any](./test-suite-a/testinterface-interface/_call_-callsignature) | Test interface event call signature | -| [(event: 'anotherTestCallSignature', listener: (input: number) => string): number](./test-suite-a/testinterface-interface/_call__1-callsignature) | Another example call signature | - -## See Also {#testinterface-see-also} - -[testInterfaceMethod()](./test-suite-a/testinterface-interface/testinterfacemethod-methodsignature) - -[testInterfaceProperty](./test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature) - -[testOptionalInterfaceProperty](./test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature) - -[testClassEventProperty](./test-suite-a/testinterface-interface/testclasseventproperty-propertysignature) diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature.md deleted file mode 100644 index e81429daac44..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature.md +++ /dev/null @@ -1,11 +0,0 @@ -# propertyWithBadInheritDocTarget - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [propertyWithBadInheritDocTarget](./test-suite-a/testinterface-interface/propertywithbadinheritdoctarget-propertysignature) - -## Signature {#propertywithbadinheritdoctarget-signature} - -```typescript -propertyWithBadInheritDocTarget: boolean; -``` - -**Type:** boolean diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/setterproperty-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/setterproperty-property.md deleted file mode 100644 index 00f56367f160..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/setterproperty-property.md +++ /dev/null @@ -1,14 +0,0 @@ -# setterProperty - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [setterProperty](./test-suite-a/testinterface-interface/setterproperty-property) - -A test property with a getter and a setter. - -## Signature {#setterproperty-signature} - -```typescript -get setterProperty(): boolean; -set setterProperty(newValue: boolean); -``` - -**Type:** boolean diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testclasseventproperty-propertysignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testclasseventproperty-propertysignature.md deleted file mode 100644 index 85d8d5b93b2f..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testclasseventproperty-propertysignature.md +++ /dev/null @@ -1,17 +0,0 @@ -# testClassEventProperty - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [testClassEventProperty](./test-suite-a/testinterface-interface/testclasseventproperty-propertysignature) - -Test interface event property - -## Signature {#testclasseventproperty-signature} - -```typescript -readonly testClassEventProperty: () => void; -``` - -**Type:** () => void - -## Remarks {#testclasseventproperty-remarks} - -Here are some remarks about the event property diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfacemethod-methodsignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfacemethod-methodsignature.md deleted file mode 100644 index 211fdfa3ddb2..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfacemethod-methodsignature.md +++ /dev/null @@ -1,15 +0,0 @@ -# testInterfaceMethod - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [testInterfaceMethod()](./test-suite-a/testinterface-interface/testinterfacemethod-methodsignature) - -Test interface method - -## Signature {#testinterfacemethod-signature} - -```typescript -testInterfaceMethod(): void; -``` - -## Remarks {#testinterfacemethod-remarks} - -Here are some remarks about the method diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature.md deleted file mode 100644 index e09fcb713294..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature.md +++ /dev/null @@ -1,17 +0,0 @@ -# testInterfaceProperty - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [testInterfaceProperty](./test-suite-a/testinterface-interface/testinterfaceproperty-propertysignature) - -Test interface property - -## Signature {#testinterfaceproperty-signature} - -```typescript -testInterfaceProperty: number; -``` - -**Type:** number - -## Remarks {#testinterfaceproperty-remarks} - -Here are some remarks about the property diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature.md deleted file mode 100644 index c037d5610e6a..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature.md +++ /dev/null @@ -1,13 +0,0 @@ -# testOptionalInterfaceProperty - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterface](./test-suite-a/testinterface-interface/) > [testOptionalInterfaceProperty](./test-suite-a/testinterface-interface/testoptionalinterfaceproperty-propertysignature) - -Test optional property - -## Signature {#testoptionalinterfaceproperty-signature} - -```typescript -testOptionalInterfaceProperty?: number; -``` - -**Type:** number diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/index.md deleted file mode 100644 index 704342163ce8..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/index.md +++ /dev/null @@ -1,31 +0,0 @@ -# TestInterfaceExtendingOtherInterfaces - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterfaceExtendingOtherInterfaces](./test-suite-a/testinterfaceextendingotherinterfaces-interface/) - -Test interface that extends other interfaces - -## Signature {#testinterfaceextendingotherinterfaces-signature} - -```typescript -export interface TestInterfaceExtendingOtherInterfaces extends TestInterface, TestMappedType, TestInterfaceWithTypeParameter -``` - -**Extends:** [TestInterface](./test-suite-a/testinterface-interface/), [TestMappedType](./test-suite-a/testmappedtype-typealias/), [TestInterfaceWithTypeParameter](./test-suite-a/testinterfacewithtypeparameter-interface/)<number> - -## Remarks {#testinterfaceextendingotherinterfaces-remarks} - -Here are some remarks about the interface - -## Methods - -| Method | Return Type | Description | -| --- | --- | --- | -| [testMethod(input)](./test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature) | number | Test interface method accepting a string and returning a number. | - -## See Also {#testinterfaceextendingotherinterfaces-see-also} - -- [TestInterface](./test-suite-a/testinterface-interface/) - -- [TestInterfaceWithTypeParameter](./test-suite-a/testinterfacewithtypeparameter-interface/) - -- [TestMappedType](./test-suite-a/testmappedtype-typealias/) diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature.md deleted file mode 100644 index 8c0dd32030f8..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature.md +++ /dev/null @@ -1,27 +0,0 @@ -# testMethod - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterfaceExtendingOtherInterfaces](./test-suite-a/testinterfaceextendingotherinterfaces-interface/) > [testMethod(input)](./test-suite-a/testinterfaceextendingotherinterfaces-interface/testmethod-methodsignature) - -Test interface method accepting a string and returning a number. - -## Signature {#testmethod-signature} - -```typescript -testMethod(input: string): number; -``` - -## Remarks {#testmethod-remarks} - -Here are some remarks about the method - -## Parameters {#testmethod-parameters} - -| Parameter | Type | Description | -| --- | --- | --- | -| input | string | A string | - -## Returns {#testmethod-returns} - -A number - -**Return type:** number diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature.md deleted file mode 100644 index dcfa5215c972..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature.md +++ /dev/null @@ -1,13 +0,0 @@ -# \[foo: number\]: { bar: string; } - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterfaceWithIndexSignature](./test-suite-a/testinterfacewithindexsignature-interface/) > [\[foo: number\]: { bar: string; }](./test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature) - -Test index signature. - -## Signature {#\_indexer\_-signature} - -```typescript -[foo: number]: { - bar: string; - }; -``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/index.md deleted file mode 100644 index a3bd5063e563..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithindexsignature-interface/index.md +++ /dev/null @@ -1,17 +0,0 @@ -# TestInterfaceWithIndexSignature - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterfaceWithIndexSignature](./test-suite-a/testinterfacewithindexsignature-interface/) - -An interface with an index signature. - -## Signature {#testinterfacewithindexsignature-signature} - -```typescript -export interface TestInterfaceWithIndexSignature -``` - -## Index Signatures - -| IndexSignature | Description | -| --- | --- | -| [\[foo: number\]: { bar: string; }](./test-suite-a/testinterfacewithindexsignature-interface/_indexer_-indexsignature) | Test index signature. | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/index.md deleted file mode 100644 index 63d540c7ea65..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/index.md +++ /dev/null @@ -1,27 +0,0 @@ -# TestInterfaceWithTypeParameter - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterfaceWithTypeParameter](./test-suite-a/testinterfacewithtypeparameter-interface/) - -Test interface with generic type parameter - -## Signature {#testinterfacewithtypeparameter-signature} - -```typescript -export interface TestInterfaceWithTypeParameter -``` - -### Type Parameters - -| Parameter | Description | -| --- | --- | -| T | A type parameter | - -## Remarks {#testinterfacewithtypeparameter-remarks} - -Here are some remarks about the interface - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [testProperty](./test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature) | T | A test interface property using generic type parameter | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature.md deleted file mode 100644 index 8879124e471a..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature.md +++ /dev/null @@ -1,17 +0,0 @@ -# testProperty - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestInterfaceWithTypeParameter](./test-suite-a/testinterfacewithtypeparameter-interface/) > [testProperty](./test-suite-a/testinterfacewithtypeparameter-interface/testproperty-propertysignature) - -A test interface property using generic type parameter - -## Signature {#testproperty-signature} - -```typescript -testProperty: T; -``` - -**Type:** T - -## Remarks {#testproperty-remarks} - -Here are some remarks about the property diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmappedtype-typealias/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmappedtype-typealias/index.md deleted file mode 100644 index 07b38df823d8..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmappedtype-typealias/index.md +++ /dev/null @@ -1,17 +0,0 @@ -# TestMappedType - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestMappedType](./test-suite-a/testmappedtype-typealias/) - -Test Mapped Type, using [TestEnum](./test-suite-a/testenum-enum/) - -## Signature {#testmappedtype-signature} - -```typescript -export type TestMappedType = { - [K in TestEnum]: boolean; -}; -``` - -## Remarks {#testmappedtype-remarks} - -Here are some remarks about the mapped type diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/foo-variable.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/foo-variable.md deleted file mode 100644 index 412aab1038d9..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/foo-variable.md +++ /dev/null @@ -1,11 +0,0 @@ -# foo - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestModule](./test-suite-a/testmodule-namespace/) > [foo](./test-suite-a/testmodule-namespace/foo-variable) - -Test constant in module. - -## Signature {#foo-signature} - -```typescript -foo = 2 -``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/index.md deleted file mode 100644 index 1d7718103821..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testmodule-namespace/index.md +++ /dev/null @@ -1,9 +0,0 @@ -# TestModule - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestModule](./test-suite-a/testmodule-namespace/) - -## Variables - -| Variable | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [foo](./test-suite-a/testmodule-namespace/foo-variable) | `readonly` | | Test constant in module. | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/index.md deleted file mode 100644 index 968d10a5bf40..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/index.md +++ /dev/null @@ -1,77 +0,0 @@ -# TestNamespace - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) - -Test Namespace - -## Signature {#testnamespace-signature} - -```typescript -export declare namespace TestNamespace -``` - -## Remarks {#testnamespace-remarks} - -Here are some remarks about the namespace - -## Examples {#testnamespace-examples} - -### Example: TypeScript Example {#testnamespace-example1} - -```typescript -const foo: Foo = { - bar: "Hello world!"; - baz = 42; -}; -``` - -### Example: JavaScript Example {#testnamespace-example2} - -```javascript -const foo = { - bar: "Hello world!"; - baz = 42; -}; -``` - -## Interfaces - -| Interface | Alerts | Description | -| --- | --- | --- | -| [TestInterface](./test-suite-a/testnamespace-namespace/testinterface-interface/) | `Alpha` | Test interface | - -## Classes - -| Class | Description | -| --- | --- | -| [TestClass](./test-suite-a/testnamespace-namespace/testclass-class/) | Test class | - -## Enumerations - -| Enum | Description | -| --- | --- | -| [TestEnum](./test-suite-a/testnamespace-namespace/testenum-enum/) | Test Enum | - -## Types - -| TypeAlias | Description | -| --- | --- | -| [TestTypeAlias](./test-suite-a/testnamespace-namespace/testtypealias-typealias/) | Test Type-Alias | - -## Functions - -| Function | Return Type | Description | -| --- | --- | --- | -| [testFunction(testParameter)](./test-suite-a/testnamespace-namespace/testfunction-function) | number | Test function | - -## Variables - -| Variable | Alerts | Modifiers | Type | Description | -| --- | --- | --- | --- | --- | -| [TestConst](./test-suite-a/testnamespace-namespace/testconst-variable) | `Beta` | `readonly` | | Test Constant | - -## Namespaces - -| Namespace | Description | -| --- | --- | -| [TestSubNamespace](./test-suite-a/testnamespace-namespace/testsubnamespace-namespace/) | Test sub-namespace | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor.md deleted file mode 100644 index f3db36a74d71..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor.md +++ /dev/null @@ -1,17 +0,0 @@ -# (constructor) - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestClass](./test-suite-a/testnamespace-namespace/testclass-class/) > [(constructor)(testClassProperty)](./test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor) - -Test class constructor - -## Signature {#\_constructor\_-signature} - -```typescript -constructor(testClassProperty: string); -``` - -## Parameters {#\_constructor\_-parameters} - -| Parameter | Type | Description | -| --- | --- | --- | -| testClassProperty | string | See [testClassProperty](./test-suite-a/testclass-class/testclassproperty-property) | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/index.md deleted file mode 100644 index a2a163202e9a..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/index.md +++ /dev/null @@ -1,29 +0,0 @@ -# TestClass - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestClass](./test-suite-a/testnamespace-namespace/testclass-class/) - -Test class - -## Signature {#testclass-signature} - -```typescript -class TestClass -``` - -## Constructors - -| Constructor | Description | -| --- | --- | -| [(constructor)(testClassProperty)](./test-suite-a/testnamespace-namespace/testclass-class/_constructor_-constructor) | Test class constructor | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [testClassProperty](./test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property) | `readonly` | string | Test interface property | - -## Methods - -| Method | Return Type | Description | -| --- | --- | --- | -| [testClassMethod(testParameter)](./test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method) | Promise<string> | Test class method | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method.md deleted file mode 100644 index 66a8a38f9e22..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method.md +++ /dev/null @@ -1,31 +0,0 @@ -# testClassMethod - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestClass](./test-suite-a/testnamespace-namespace/testclass-class/) > [testClassMethod(testParameter)](./test-suite-a/testnamespace-namespace/testclass-class/testclassmethod-method) - -Test class method - -## Signature {#testclassmethod-signature} - -```typescript -testClassMethod(testParameter: string): Promise; -``` - -## Parameters {#testclassmethod-parameters} - -| Parameter | Type | Description | -| --- | --- | --- | -| testParameter | string | A string | - -## Returns {#testclassmethod-returns} - -A Promise - -**Return type:** Promise<string> - -## Throws {#testclassmethod-throws} - -An Error when something happens for which an error should be thrown. Except in the cases where another kind of error is thrown. We don't throw this error in those cases. - -A different kind of error when a thing happens, but not when the first kind of error is thrown instead. - -😁 diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property.md deleted file mode 100644 index 9c993b1ff6d9..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property.md +++ /dev/null @@ -1,13 +0,0 @@ -# testClassProperty - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestClass](./test-suite-a/testnamespace-namespace/testclass-class/) > [testClassProperty](./test-suite-a/testnamespace-namespace/testclass-class/testclassproperty-property) - -Test interface property - -## Signature {#testclassproperty-signature} - -```typescript -readonly testClassProperty: string; -``` - -**Type:** string diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testconst-variable.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testconst-variable.md deleted file mode 100644 index 343608f24e1c..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testconst-variable.md +++ /dev/null @@ -1,13 +0,0 @@ -# TestConst - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestConst](./test-suite-a/testnamespace-namespace/testconst-variable) - -Test Constant - -**WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.** - -## Signature {#testconst-signature} - -```typescript -TestConst = "Hello world!" -``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/index.md deleted file mode 100644 index 18920c2edba3..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/index.md +++ /dev/null @@ -1,34 +0,0 @@ -# TestEnum - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestEnum](./test-suite-a/testnamespace-namespace/testenum-enum/) - -Test Enum - -## Signature {#testenum-signature} - -```typescript -enum TestEnum -``` - -## Flags - -| Flag | Description | -| --- | --- | -| [TestEnumValue1](./test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember) | Test enum value 1 | -| [TestEnumValue2](./test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember) | Test enum value 2 | - -Test enum value 1 - -### Signature {#testenumvalue1-signature} - -```typescript -TestEnumValue1 = 0 -``` - -Test enum value 2 - -### Signature {#testenumvalue2-signature} - -```typescript -TestEnumValue2 = 1 -``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember.md deleted file mode 100644 index 17fc20c60c5e..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember.md +++ /dev/null @@ -1,11 +0,0 @@ -# TestEnumValue1 - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestEnum](./test-suite-a/testnamespace-namespace/testenum-enum/) > [TestEnumValue1](./test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue1-enummember) - -Test enum value 1 - -## Signature {#testenumvalue1-signature} - -```typescript -TestEnumValue1 = 0 -``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember.md deleted file mode 100644 index cc0f1df5018d..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember.md +++ /dev/null @@ -1,11 +0,0 @@ -# TestEnumValue2 - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestEnum](./test-suite-a/testnamespace-namespace/testenum-enum/) > [TestEnumValue2](./test-suite-a/testnamespace-namespace/testenum-enum/testenumvalue2-enummember) - -Test enum value 2 - -## Signature {#testenumvalue2-signature} - -```typescript -TestEnumValue2 = 1 -``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testfunction-function.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testfunction-function.md deleted file mode 100644 index 29bb76f19c72..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testfunction-function.md +++ /dev/null @@ -1,27 +0,0 @@ -# testFunction - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [testFunction(testParameter)](./test-suite-a/testnamespace-namespace/testfunction-function) - -Test function - -## Signature {#testfunction-signature} - -```typescript -function testFunction(testParameter: number): number; -``` - -## Parameters {#testfunction-parameters} - -| Parameter | Type | Description | -| --- | --- | --- | -| testParameter | number | | - -## Returns {#testfunction-returns} - -A number - -**Return type:** number - -## Throws {#testfunction-throws} - -An Error diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/index.md deleted file mode 100644 index 33639ebe1a9a..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/index.md +++ /dev/null @@ -1,27 +0,0 @@ -# TestInterface - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestInterface](./test-suite-a/testnamespace-namespace/testinterface-interface/) - -Test interface - -**WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.** - -## Signature {#testinterface-signature} - -```typescript -interface TestInterface extends TestInterfaceWithTypeParameter -``` - -**Extends:** [TestInterfaceWithTypeParameter](./test-suite-a/testinterfacewithtypeparameter-interface/)<[TestEnum](./test-suite-a/testnamespace-namespace/testenum-enum/)> - -## Properties - -| Property | Alerts | Type | Description | -| --- | --- | --- | --- | -| [testInterfaceProperty](./test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature) | `Alpha` | boolean | Test interface property | - -## Methods - -| Method | Alerts | Return Type | Description | -| --- | --- | --- | --- | -| [testInterfaceMethod()](./test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature) | `Alpha` | void | Test interface method | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature.md deleted file mode 100644 index 430c8bcc5eb2..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature.md +++ /dev/null @@ -1,13 +0,0 @@ -# testInterfaceMethod - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestInterface](./test-suite-a/testnamespace-namespace/testinterface-interface/) > [testInterfaceMethod()](./test-suite-a/testnamespace-namespace/testinterface-interface/testinterfacemethod-methodsignature) - -Test interface method - -**WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.** - -## Signature {#testinterfacemethod-signature} - -```typescript -testInterfaceMethod(): void; -``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature.md deleted file mode 100644 index 0ed96d9bc24f..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature.md +++ /dev/null @@ -1,15 +0,0 @@ -# testInterfaceProperty - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestInterface](./test-suite-a/testnamespace-namespace/testinterface-interface/) > [testInterfaceProperty](./test-suite-a/testnamespace-namespace/testinterface-interface/testinterfaceproperty-propertysignature) - -Test interface property - -**WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.** - -## Signature {#testinterfaceproperty-signature} - -```typescript -testInterfaceProperty: boolean; -``` - -**Type:** boolean diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testsubnamespace-namespace/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testsubnamespace-namespace/index.md deleted file mode 100644 index 55e0cbb15b66..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testsubnamespace-namespace/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# TestSubNamespace - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestSubNamespace](./test-suite-a/testnamespace-namespace/testsubnamespace-namespace/) - -Test sub-namespace - -## Signature {#testsubnamespace-signature} - -```typescript -namespace TestSubNamespace -``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testtypealias-typealias/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testtypealias-typealias/index.md deleted file mode 100644 index 6040f34e8a83..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/testnamespace-namespace/testtypealias-typealias/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# TestTypeAlias - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TestNamespace](./test-suite-a/testnamespace-namespace/) > [TestTypeAlias](./test-suite-a/testnamespace-namespace/testtypealias-typealias/) - -Test Type-Alias - -## Signature {#testtypealias-signature} - -```typescript -type TestTypeAlias = boolean; -``` diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/typealias-typealias/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/typealias-typealias/index.md deleted file mode 100644 index f7d3a9bb916b..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-a/typealias-typealias/index.md +++ /dev/null @@ -1,15 +0,0 @@ -# TypeAlias - -[Packages](./) > [test-suite-a](./test-suite-a/) > [TypeAlias](./test-suite-a/typealias-typealias/) - -Test Type-Alias - -## Signature {#typealias-signature} - -```typescript -export type TypeAlias = string; -``` - -## Remarks {#typealias-remarks} - -Here are some remarks about the type alias diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/foo-interface/bar-propertysignature.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/foo-interface/bar-propertysignature.md deleted file mode 100644 index d5f9594c2ebe..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/foo-interface/bar-propertysignature.md +++ /dev/null @@ -1,17 +0,0 @@ -# bar - -[Packages](./) > [test-suite-b](./test-suite-b/) > [Foo](./test-suite-b/foo-interface/) > [bar](./test-suite-b/foo-interface/bar-propertysignature) - -Test Enum - -## Signature {#bar-signature} - -```typescript -bar: TestEnum; -``` - -**Type:** [TestEnum](./test-suite-a/testenum-enum/) - -## Remarks {#bar-remarks} - -Here are some remarks about the enum diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/foo-interface/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/foo-interface/index.md deleted file mode 100644 index 9f9671ba3479..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/foo-interface/index.md +++ /dev/null @@ -1,17 +0,0 @@ -# Foo - -[Packages](./) > [test-suite-b](./test-suite-b/) > [Foo](./test-suite-b/foo-interface/) - -Bar - -## Signature {#foo-signature} - -```typescript -export interface Foo -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [bar](./test-suite-b/foo-interface/bar-propertysignature) | [TestEnum](./test-suite-a/testenum-enum/) | Test Enum | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/index.md deleted file mode 100644 index ad85c0991f22..000000000000 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/deep-config/test-suite-b/index.md +++ /dev/null @@ -1,9 +0,0 @@ -# test-suite-b - -[Packages](./) > [test-suite-b](./test-suite-b/) - -## Interfaces - -| Interface | Description | -| --- | --- | -| [Foo](./test-suite-b/foo-interface/) | Bar | From 8f3396e9bab4b6c43e578beb3bf55905591af47f Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 8 Jan 2025 01:44:28 +0000 Subject: [PATCH 45/54] test: Fix tests --- .../src/test/EndToEndTestUtilities.ts | 10 ++++----- .../src/test/HtmlEndToEnd.test.ts | 21 ++++++++++--------- .../src/test/MarkdownEndToEnd.test.ts | 21 ++++++++++--------- 3 files changed, 26 insertions(+), 26 deletions(-) diff --git a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts index 3c3612da52df..521cd8635cf9 100644 --- a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts +++ b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts @@ -12,7 +12,6 @@ import { expect } from "chai"; import { compare } from "dir-compare"; import { - ApiItemUtilities, FolderDocumentPlacement, HierarchyKind, type FolderHierarchyConfiguration, @@ -50,11 +49,6 @@ export namespace HierarchyConfigurations { documentPlacement: FolderDocumentPlacement.Outside, }; - const insideFolderOptions: FolderHierarchyConfiguration = { - kind: HierarchyKind.Folder, - documentPlacement: FolderDocumentPlacement.Inside, - }; - /** * "Flat" hierarchy: Packages get their own documents, and all descendent API items are rendered as sections under that document. * @remarks Results in a small number of documents, but can lead to relatively large documents. @@ -106,6 +100,10 @@ export namespace HierarchyConfigurations { }; // TODO + // const insideFolderOptions: FolderHierarchyConfiguration = { + // kind: HierarchyKind.Folder, + // documentPlacement: FolderDocumentPlacement.Inside, + // }; // /** // * "Deep" hierarchy: All "parent" API items generate hierarchy. All other items are rendered as documents under their parent hierarchy. // * @remarks Leads to many documents, but each document is likely to be relatively small. diff --git a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts index 051304b9bbc5..91105e623114 100644 --- a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts @@ -67,16 +67,17 @@ const testConfigs = new Map< }, ], - // A sample "deep" configuration. - // All "parent" API items generate hierarchy. - // All other items are rendered as documents under their parent hierarchy. - [ - "deep-config", - { - uriRoot: ".", - hierarchy: HierarchyConfigurations.deep, - }, - ], + // TODO + // // A sample "deep" configuration. + // // All "parent" API items generate hierarchy. + // // All other items are rendered as documents under their parent hierarchy. + // [ + // "deep-config", + // { + // uriRoot: ".", + // hierarchy: HierarchyConfigurations.deep, + // }, + // ], ]); describe("HTML end-to-end tests", () => { diff --git a/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts index 9e95aaf09c0d..c11dafa4a1d8 100644 --- a/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts +++ b/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts @@ -67,16 +67,17 @@ const testConfigs = new Map< }, ], - // A sample "deep" configuration. - // All "parent" API items generate hierarchy. - // All other items are rendered as documents under their parent hierarchy. - [ - "deep-config", - { - uriRoot: ".", - hierarchy: HierarchyConfigurations.deep, - }, - ], + // TODO + // // A sample "deep" configuration. + // // All "parent" API items generate hierarchy. + // // All other items are rendered as documents under their parent hierarchy. + // [ + // "deep-config", + // { + // uriRoot: ".", + // hierarchy: HierarchyConfigurations.deep, + // }, + // ], ]); describe("Markdown end-to-end tests", () => { From 9f42ec0cacb8c6c3cec3e4336b42770bbd471948 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Tue, 7 Jan 2025 17:48:47 -0800 Subject: [PATCH 46/54] docs: Add comment --- tools/api-markdown-documenter/src/utilities/index.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/tools/api-markdown-documenter/src/utilities/index.ts b/tools/api-markdown-documenter/src/utilities/index.ts index d3e4969ef77e..2350c4f9e4fd 100644 --- a/tools/api-markdown-documenter/src/utilities/index.ts +++ b/tools/api-markdown-documenter/src/utilities/index.ts @@ -3,6 +3,7 @@ * Licensed under the MIT License. */ +// All of the utilities here are meant to be used outside of this directory. /* eslint-disable no-restricted-syntax */ export * from "./ApiItemUtilities.js"; From aa78ec4343180da75abd1f266896ac9491e2bc23 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 8 Jan 2025 18:59:34 +0000 Subject: [PATCH 47/54] docs: Add changelog entry --- tools/api-markdown-documenter/CHANGELOG.md | 121 +++++++++++++++++++++ 1 file changed, 121 insertions(+) diff --git a/tools/api-markdown-documenter/CHANGELOG.md b/tools/api-markdown-documenter/CHANGELOG.md index 1c926086d39d..24e29f493280 100644 --- a/tools/api-markdown-documenter/CHANGELOG.md +++ b/tools/api-markdown-documenter/CHANGELOG.md @@ -51,6 +51,127 @@ await MarkdownRenderer.renderApiModel({ }); ``` +#### Update pattern for controlling file-wise hierarchy + +Previously, users could control certain aspects of the output documentation suite's file-system hierarchy via the `documentBoundaries` and `hierarchyBoundaries` properties of the transformation configuration. +One particular limitation of this setup was that items yielding folder-wise hierarchy (`hierarchyBoundaries`) could never place their own document *inside* of their own hierarchy. +This naturally lent itself to a pattern where output would commonly be formatted as: + +``` +- foo.md +- foo + - bar.md + - baz.md +``` + +This pattern works fine for many site generation systems - a link to `/foo` will end up pointing `foo.md` and a link to `/foo/bar` will end up pointing to `foo/bar.md`. +But some systems (e.g. `Docusaurus`) don't handle this well, and instead prefer setups like the following: + +``` +- foo + - index.md + - bar.md + - baz.md +``` + +With the previous configuration options, this pattern was not possible, but now is. +Additionally, this pattern is *more* commonly accepted, so lack of support for this was a real detriment. + +Such patterns can now be produced via the consolidated `hierarchy` property, while still allowing full file-naming flexibility. + +##### Related changes + +For consistency / discoverability, the `DocumentationSuiteConfiguration.getFileNameForItem` property has also been moved under the new `hierarchy` property (`HierarchyConfiguration`) and renamed to `getDocumentName`. + +Additionally, where previously that property controlled both the document *and* folder naming corresponding to a given API item, folder naming can now be controlled independently via the `getFolderName` property. + +##### Example migration + +Consider the following configuration: + +```typescript +const config = { + ... + documentBoundaries: [ + ApiItemKind.Class, + ApiItemKind.Interface, + ApiItemKind.Namespace, + ], + hierarchyBoundaries: [ + ApiItemKind.Namespace, + ] + ... +} +``` + +With this configuration, `Class`, `Interface`, and `Namespace` API items would yield their own documents (rather than being rendered to a parent item's document), and `Namespace` items would additionally generate folder hierarchy (child items rendered to their own documents would be placed under a sub-directory). + +Output for this case might look something like the following: + +``` +- package.md +- class.md +- interface.md +- namespace.md +- namespace + - namespace-member-a.md + - namespace-member-b.md +``` + +This same behavior can now be configured via the following: + +```typescript +const config = { + ... + hierarchy: { + [ApiItemKind.Class]: HierarchyKind.Document, + [ApiItemKind.Interface]: HierarchyKind.Document, + [ApiItemKind.Namespace]: { + kind: HierarchyKind.Folder, + documentPlacement: FolderDocumentPlacement.Outside, + }, + } + ... +} +``` + +Further, if you would prefer to place the resulting `Namespace` documents *under* their resulting folder, you could use a configuration like the following: + +```typescript +const config = { + ... + hierarchy: { + [ApiItemKind.Class]: HierarchyKind.Document, + [ApiItemKind.Interface]: HierarchyKind.Document, + [ApiItemKind.Namespace]: { + kind: HierarchyKind.Folder, + documentPlacement: FolderDocumentPlacement.Inside, // <= + }, + getDocumentName: (apiItem) => { + switch(apiItem.kind) { + case ApiItemKind.Namespace: + return "index"; + default: + ... + } + } + } + ... +} +``` + +Output for this updated case might look something like the following: + +``` +- package.md +- class.md +- interface.md +- namespace + - index.md + - namespace-member-a.md + - namespace-member-b.md +``` + #### Type-renames - `ApiItemTransformationOptions` -> `ApiItemTransformations` From 90728fc9d5b63470b6ccd3c925796fff04181e97 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 8 Jan 2025 19:16:48 +0000 Subject: [PATCH 48/54] refactor: Make enum value strings upper-case for consistency --- .../api-report/api-markdown-documenter.alpha.api.md | 4 ++-- .../api-report/api-markdown-documenter.beta.api.md | 4 ++-- .../api-report/api-markdown-documenter.public.api.md | 4 ++-- .../src/api-item-transforms/configuration/Hierarchy.ts | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) 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 50b6389fb250..54a4cc9b2f7b 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 @@ -394,8 +394,8 @@ function filterItems(apiItems: readonly ApiItem[], config: ApiItemTransformation // @public export enum FolderDocumentPlacement { - Inside = "inside", - Outside = "outside" + Inside = "Inside", + Outside = "Outside" } // @public @sealed 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 011160c4bacb..fe9300bc85fc 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 @@ -394,8 +394,8 @@ function filterItems(apiItems: readonly ApiItem[], config: ApiItemTransformation // @public export enum FolderDocumentPlacement { - Inside = "inside", - Outside = "outside" + Inside = "Inside", + Outside = "Outside" } // @public @sealed 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 e7cc51a1d0bc..481115e84aea 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 @@ -394,8 +394,8 @@ function filterItems(apiItems: readonly ApiItem[], config: ApiItemTransformation // @public export enum FolderDocumentPlacement { - Inside = "inside", - Outside = "outside" + Inside = "Inside", + Outside = "Outside" } // @public @sealed diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts index 1592ca2c6a23..4c8a4b75f8ae 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts @@ -78,12 +78,12 @@ export enum FolderDocumentPlacement { /** * The document is placed inside its folder. */ - Inside = "inside", + Inside = "Inside", /** * The document is placed outside (adjacent to) its folder. */ - Outside = "outside", + Outside = "Outside", } /** From 13339cc29cb6773ce08ec1ace9966a6a088b68a6 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 8 Jan 2025 19:16:54 +0000 Subject: [PATCH 49/54] style: Prettier --- tools/api-markdown-documenter/CHANGELOG.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tools/api-markdown-documenter/CHANGELOG.md b/tools/api-markdown-documenter/CHANGELOG.md index 24e29f493280..1c1d4f938da6 100644 --- a/tools/api-markdown-documenter/CHANGELOG.md +++ b/tools/api-markdown-documenter/CHANGELOG.md @@ -54,7 +54,7 @@ await MarkdownRenderer.renderApiModel({ #### Update pattern for controlling file-wise hierarchy Previously, users could control certain aspects of the output documentation suite's file-system hierarchy via the `documentBoundaries` and `hierarchyBoundaries` properties of the transformation configuration. -One particular limitation of this setup was that items yielding folder-wise hierarchy (`hierarchyBoundaries`) could never place their own document *inside* of their own hierarchy. +One particular limitation of this setup was that items yielding folder-wise hierarchy (`hierarchyBoundaries`) could never place their own document _inside_ of their own hierarchy. This naturally lent itself to a pattern where output would commonly be formatted as: ``` @@ -75,7 +75,7 @@ But some systems (e.g. `Docusaurus`) don't handle this well, and instead prefer ``` With the previous configuration options, this pattern was not possible, but now is. -Additionally, this pattern is *more* commonly accepted, so lack of support for this was a real detriment. +Additionally, this pattern is _more_ commonly accepted, so lack of support for this was a real detriment. Such patterns can now be produced via the consolidated `hierarchy` property, while still allowing full file-naming flexibility. @@ -83,7 +83,7 @@ Such patterns can now be produced via the consolidated `hierarchy` property, whi For consistency / discoverability, the `DocumentationSuiteConfiguration.getFileNameForItem` property has also been moved under the new `hierarchy` property (`HierarchyConfiguration`) and renamed to `getDocumentName`. -Additionally, where previously that property controlled both the document *and* folder naming corresponding to a given API item, folder naming can now be controlled independently via the `getFolderName` property. +Additionally, where previously that property controlled both the document _and_ folder naming corresponding to a given API item, folder naming can now be controlled independently via the `getFolderName` property. ##### Example migration @@ -135,7 +135,7 @@ const config = { } ``` -Further, if you would prefer to place the resulting `Namespace` documents *under* their resulting folder, you could use a configuration like the following: +Further, if you would prefer to place the resulting `Namespace` documents _under_ their resulting folder, you could use a configuration like the following: ```typescript const config = { From a453d317d00ae735141357c4d2a1a19bedc87111 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 8 Jan 2025 19:30:02 +0000 Subject: [PATCH 50/54] refactor: Make properties readonly --- .../api-markdown-documenter.alpha.api.md | 22 ++++++++++++------- .../api-markdown-documenter.beta.api.md | 22 ++++++++++++------- .../api-markdown-documenter.public.api.md | 22 ++++++++++++------- .../configuration/Hierarchy.ts | 16 +++++++------- 4 files changed, 50 insertions(+), 32 deletions(-) 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 54a4cc9b2f7b..bb95416c3cc9 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 @@ -473,11 +473,14 @@ export class HeadingNode extends DocumentationParentNodeBase]: DocumentationHierarchyConfiguration; + /** + * Hierarchy configuration for the API item kind. + */ + readonly [Kind in Exclude]: DocumentationHierarchyConfiguration; } & { - [ApiItemKind.Model]: DocumentHierarchyConfiguration; - [ApiItemKind.Package]: DocumentHierarchyConfiguration | FolderHierarchyConfiguration; - [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; + readonly [ApiItemKind.Model]: DocumentHierarchyConfiguration; + readonly [ApiItemKind.Package]: DocumentHierarchyConfiguration | FolderHierarchyConfiguration; + readonly [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; readonly getDocumentName: (apiItem: ApiItem, config: HierarchyConfiguration) => string; readonly getFolderName: (apiItem: ApiItem, config: HierarchyConfiguration) => string; }; @@ -491,11 +494,14 @@ export enum HierarchyKind { // @public export type HierarchyOptions = { - [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyConfiguration; + /** + * Hierarchy configuration for the API item kind. + */ + readonly [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyConfiguration; } & { - [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; - [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; - [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + readonly [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + readonly [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; + readonly [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; readonly getDocumentName?: (apiItem: ApiItem, config: HierarchyConfiguration) => string; readonly getFolderName?: (apiItem: ApiItem, config: HierarchyConfiguration) => string; }; 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 fe9300bc85fc..8e723d942970 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 @@ -473,11 +473,14 @@ export class HeadingNode extends DocumentationParentNodeBase]: DocumentationHierarchyConfiguration; + /** + * Hierarchy configuration for the API item kind. + */ + readonly [Kind in Exclude]: DocumentationHierarchyConfiguration; } & { - [ApiItemKind.Model]: DocumentHierarchyConfiguration; - [ApiItemKind.Package]: DocumentHierarchyConfiguration | FolderHierarchyConfiguration; - [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; + readonly [ApiItemKind.Model]: DocumentHierarchyConfiguration; + readonly [ApiItemKind.Package]: DocumentHierarchyConfiguration | FolderHierarchyConfiguration; + readonly [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; readonly getDocumentName: (apiItem: ApiItem, config: HierarchyConfiguration) => string; readonly getFolderName: (apiItem: ApiItem, config: HierarchyConfiguration) => string; }; @@ -491,11 +494,14 @@ export enum HierarchyKind { // @public export type HierarchyOptions = { - [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyConfiguration; + /** + * Hierarchy configuration for the API item kind. + */ + readonly [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyConfiguration; } & { - [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; - [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; - [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + readonly [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + readonly [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; + readonly [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; readonly getDocumentName?: (apiItem: ApiItem, config: HierarchyConfiguration) => string; readonly getFolderName?: (apiItem: ApiItem, config: HierarchyConfiguration) => string; }; 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 481115e84aea..17e2d3881409 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 @@ -473,11 +473,14 @@ export class HeadingNode extends DocumentationParentNodeBase]: DocumentationHierarchyConfiguration; + /** + * Hierarchy configuration for the API item kind. + */ + readonly [Kind in Exclude]: DocumentationHierarchyConfiguration; } & { - [ApiItemKind.Model]: DocumentHierarchyConfiguration; - [ApiItemKind.Package]: DocumentHierarchyConfiguration | FolderHierarchyConfiguration; - [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; + readonly [ApiItemKind.Model]: DocumentHierarchyConfiguration; + readonly [ApiItemKind.Package]: DocumentHierarchyConfiguration | FolderHierarchyConfiguration; + readonly [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; readonly getDocumentName: (apiItem: ApiItem, config: HierarchyConfiguration) => string; readonly getFolderName: (apiItem: ApiItem, config: HierarchyConfiguration) => string; }; @@ -491,11 +494,14 @@ export enum HierarchyKind { // @public export type HierarchyOptions = { - [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyConfiguration; + /** + * Hierarchy configuration for the API item kind. + */ + readonly [Kind in Exclude]?: HierarchyKind | DocumentationHierarchyConfiguration; } & { - [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; - [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; - [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + readonly [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + readonly [ApiItemKind.Package]?: HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyConfiguration | FolderHierarchyConfiguration; + readonly [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; readonly getDocumentName?: (apiItem: ApiItem, config: HierarchyConfiguration) => string; readonly getFolderName?: (apiItem: ApiItem, config: HierarchyConfiguration) => string; }; diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts index 4c8a4b75f8ae..09e536395943 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Hierarchy.ts @@ -145,7 +145,7 @@ export type HierarchyConfiguration = { /** * Hierarchy configuration for the API item kind. */ - [Kind in Exclude< + readonly [Kind in Exclude< ValidApiItemKind, ApiItemKind.Model | ApiItemKind.EntryPoint | ApiItemKind.Package >]: DocumentationHierarchyConfiguration; @@ -157,7 +157,7 @@ export type HierarchyConfiguration = { * Always its own document. Never introduces folder hierarchy. * This is an important invariant, as it ensures that there is always at least one document in the output. */ - [ApiItemKind.Model]: DocumentHierarchyConfiguration; + readonly [ApiItemKind.Model]: DocumentHierarchyConfiguration; /** * Hierarchy configuration for the `Package` API item kind. @@ -168,7 +168,7 @@ export type HierarchyConfiguration = { * TODO: Allow all hierarchy configurations for packages. * There isn't a real reason to restrict this, except the way the code is currently structured. */ - [ApiItemKind.Package]: DocumentHierarchyConfiguration | FolderHierarchyConfiguration; + readonly [ApiItemKind.Package]: DocumentHierarchyConfiguration | FolderHierarchyConfiguration; /** * Hierarchy configuration for the `EntryPoint` API item kind. @@ -181,7 +181,7 @@ export type HierarchyConfiguration = { * TODO: Allow all hierarchy configurations for packages. * There isn't a real reason to restrict this, except the way the code is currently structured. */ - [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; + readonly [ApiItemKind.EntryPoint]: DocumentHierarchyConfiguration; /** * {@inheritDoc HierarchyOptions.getDocumentName} @@ -210,7 +210,7 @@ export type HierarchyOptions = { /** * Hierarchy configuration for the API item kind. */ - [Kind in Exclude< + readonly [Kind in Exclude< ValidApiItemKind, ApiItemKind.Model | ApiItemKind.EntryPoint | ApiItemKind.Package >]?: HierarchyKind | DocumentationHierarchyConfiguration; @@ -222,7 +222,7 @@ export type HierarchyOptions = { * Always its own document. Never introduces folder hierarchy. * This is an important invariant, as it ensures that there is always at least one document in the output. */ - [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + readonly [ApiItemKind.Model]?: HierarchyKind.Document | DocumentHierarchyConfiguration; /** * Hierarchy configuration for the `Package` API item kind. @@ -233,7 +233,7 @@ export type HierarchyOptions = { * TODO: Allow all hierarchy configurations for packages. * There isn't a real reason to restrict this, except the way the code is currently structured. */ - [ApiItemKind.Package]?: + readonly [ApiItemKind.Package]?: | HierarchyKind.Document | HierarchyKind.Folder | DocumentHierarchyConfiguration @@ -250,7 +250,7 @@ export type HierarchyOptions = { * TODO: Allow all hierarchy configurations for packages. * There isn't a real reason to restrict this, except the way the code is currently structured. */ - [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; + readonly [ApiItemKind.EntryPoint]?: HierarchyKind.Document | DocumentHierarchyConfiguration; /** * Generate the desired document name for the provided `ApiItem`. From 1920abd676179f3030ee6346f6cdab8b4d56e0a3 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 8 Jan 2025 21:42:36 +0000 Subject: [PATCH 51/54] refactor: Remove export of API that should not be needed externally --- .../api-report/api-markdown-documenter.alpha.api.md | 4 ---- .../api-report/api-markdown-documenter.beta.api.md | 4 ---- .../api-report/api-markdown-documenter.public.api.md | 4 ---- tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts | 1 - 4 files changed, 13 deletions(-) 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 b794c1839da4..ff52f52f0024 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 @@ -107,7 +107,6 @@ export interface ApiItemTransformations { declare namespace ApiItemUtilities { export { createQualifiedDocumentNameForApiItem, - doesItemKindRequireOwnDocument, filterItems, getHeadingForApiItem, getLinkForApiItem, @@ -371,9 +370,6 @@ export namespace DocumentWriter { export function create(): DocumentWriter; } -// @public -function doesItemKindRequireOwnDocument(apiItemKind: ValidApiItemKind, hierarchyConfig: Required): boolean; - // @public export class FencedCodeBlockNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { constructor(children: DocumentationNode[], language?: string); 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 c0898df8aaf1..220ffc66e011 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 @@ -107,7 +107,6 @@ export interface ApiItemTransformations { declare namespace ApiItemUtilities { export { createQualifiedDocumentNameForApiItem, - doesItemKindRequireOwnDocument, filterItems, getHeadingForApiItem, getLinkForApiItem, @@ -371,9 +370,6 @@ export namespace DocumentWriter { export function create(): DocumentWriter; } -// @public -function doesItemKindRequireOwnDocument(apiItemKind: ValidApiItemKind, hierarchyConfig: Required): boolean; - // @public export class FencedCodeBlockNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { constructor(children: DocumentationNode[], language?: string); 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 6c318c14783a..db51e0b53358 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 @@ -107,7 +107,6 @@ export interface ApiItemTransformations { declare namespace ApiItemUtilities { export { createQualifiedDocumentNameForApiItem, - doesItemKindRequireOwnDocument, filterItems, getHeadingForApiItem, getLinkForApiItem, @@ -371,9 +370,6 @@ export namespace DocumentWriter { export function create(): DocumentWriter; } -// @public -function doesItemKindRequireOwnDocument(apiItemKind: ValidApiItemKind, hierarchyConfig: Required): boolean; - // @public export class FencedCodeBlockNode extends DocumentationParentNodeBase implements MultiLineDocumentationNode { constructor(children: DocumentationNode[], language?: string); diff --git a/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts b/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts index cca0cb5ff398..354f617cb956 100644 --- a/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts +++ b/tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts @@ -9,7 +9,6 @@ export { createQualifiedDocumentNameForApiItem, - doesItemKindRequireOwnDocument, filterItems, getHeadingForApiItem, getLinkForApiItem, From bb91baa911466cc1838b17c84a8bec38a885a34c Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 8 Jan 2025 21:51:09 +0000 Subject: [PATCH 52/54] remove: Unwanted new module --- .../src/LoggingOptions.ts | 26 ------------------- 1 file changed, 26 deletions(-) delete mode 100644 tools/api-markdown-documenter/src/LoggingOptions.ts diff --git a/tools/api-markdown-documenter/src/LoggingOptions.ts b/tools/api-markdown-documenter/src/LoggingOptions.ts deleted file mode 100644 index 4aeb5ef1b154..000000000000 --- a/tools/api-markdown-documenter/src/LoggingOptions.ts +++ /dev/null @@ -1,26 +0,0 @@ -/*! - * Copyright (c) Microsoft Corporation and contributors. All rights reserved. - * Licensed under the MIT License. - */ - -import type { Logger } from "./Logging.js"; - -/** - * Common base interface for configurations that take a logger. - * - * @public - */ -export interface LoggingOptions { - /** - * Optional receiver of system log data. - * - * @defaultValue {@link defaultConsoleLogger} - * - * @remarks - * - * A custom logger can be provided for customized policy, or for a target other than the console. - * - * If you wish to enable `verbose` logging, consider using {@link verboseConsoleLogger}. - */ - readonly logger?: Logger; -} From c2dcc771107552f007acb35f4a25e383e1102704 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 8 Jan 2025 22:35:10 +0000 Subject: [PATCH 53/54] revert: Unwanted utility refactoring --- .../configuration/DocumentationSuite.ts | 11 ++++++++++- .../api-item-transforms/configuration/Utilities.ts | 14 -------------- 2 files changed, 10 insertions(+), 15 deletions(-) delete mode 100644 tools/api-markdown-documenter/src/api-item-transforms/configuration/Utilities.ts 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 32c7bb2e134e..0246a6f6d5e9 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 @@ -24,7 +24,6 @@ import { type HierarchyConfiguration, type HierarchyOptions, } from "./Hierarchy.js"; -import { trimTrailingSemicolon } from "./Utilities.js"; /** * Options for configuring the documentation suite generated by the API Item -\> Documentation Domain transformation. @@ -301,3 +300,13 @@ export function getDocumentationSuiteConfigurationWithDefaults( minimumReleaseLevel: options?.minimumReleaseLevel ?? ReleaseTag.Internal, }; } + +/** + * Trims a trailing semicolon from the provided text, if the text contains one. + */ +function trimTrailingSemicolon(text: string): string { + if (text.endsWith(";")) { + return text.slice(0, text.length - 1); + } + return text; +} diff --git a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Utilities.ts b/tools/api-markdown-documenter/src/api-item-transforms/configuration/Utilities.ts deleted file mode 100644 index 66ebb0cea6e2..000000000000 --- a/tools/api-markdown-documenter/src/api-item-transforms/configuration/Utilities.ts +++ /dev/null @@ -1,14 +0,0 @@ -/*! - * Copyright (c) Microsoft Corporation and contributors. All rights reserved. - * Licensed under the MIT License. - */ - -/** - * Trims a trailing semicolon from the provided text, if the text contains one. - */ -export function trimTrailingSemicolon(text: string): string { - if (text.endsWith(";")) { - return text.slice(0, text.length - 1); - } - return text; -} From c773644b089728faa443b0d4e4fb7afed2f89ed0 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Wed, 8 Jan 2025 14:42:39 -0800 Subject: [PATCH 54/54] docs: Update comment --- .../src/api-item-transforms/helpers/Helpers.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 d33a1c23002e..ee8f7f6a573b 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 @@ -391,7 +391,7 @@ export function createBreadcrumbParagraph( apiItem: ApiItem, config: ApiItemTransformationConfiguration, ): ParagraphNode { - // #region Get ordered ancestry of document items + // #region Get hierarchy of document items const breadcrumbLinks: Link[] = [getLinkForApiItem(apiItem, config)];