Skip to content

Commit 964f811

Browse files
JosmithrJosmithr
authored
refactor(api-markdown-documenter): Rename DocumentationSuiteOptions to DocumentationSuiteConfiguration and make its properties required (#23388)
This library has an inconsistent mix of `Partial` and `Required` types to represent partial user input parameters and "complete" configurations needed by the system to function. This version of the library attempts to align its APIs with the following conventions: - Naming: - "Options": refers to user-provided API parameters, which may be incomplete. - "Configuration": refers to the "complete" sets of parameters needed by system functionality. - Typing: - When possible, "configuration" types will be declared with all properties required. - When possible, "options" types will be declared as `Partial<FooConfiguration>`. When not possible, they will be declared as separate types. This PR specifically makes the following name / structure changes: - `DocumentationSuiteOptions` -> `DocumentationSuiteConfiguration` (user input is taken as `Partial<DocumentationSuiteConfiguration>`).
1 parent 4a66474 commit 964f811

17 files changed

+102
-101
lines changed

‎tools/api-markdown-documenter/CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@ This version of the library attempts to align its APIs with the following conven
8686
##### Affected types
8787

8888
- `ApiTransformationConfiguration` -> `ApiTransformationOptions` (user input) and `ApiTransformationConfiguration` (derived system configuration).
89+
- `DocumentationSuiteOptions` -> `DocumentationSuiteConfiguration` (user input is taken as `Partial<DocumentationSuiteConfiguration>`).
8990

9091
#### Updated structure of `ApiTransformationConfiguration` and `ApiItemTransformations`
9192

‎tools/api-markdown-documenter/api-report/api-markdown-documenter.alpha.api.md‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ export { ApiItem }
4949
export { ApiItemKind }
5050

5151
// @public
52-
export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, Required<DocumentationSuiteOptions>, Required<LoggingConfiguration> {
52+
export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, DocumentationSuiteConfiguration, Required<LoggingConfiguration> {
5353
readonly defaultSectionLayout: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: ApiItemTransformationConfiguration) => SectionNode[];
5454
readonly transformations: ApiItemTransformations;
5555
}
@@ -61,7 +61,7 @@ export interface ApiItemTransformationConfigurationBase {
6161
}
6262

6363
// @public
64-
export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, DocumentationSuiteOptions, LoggingConfiguration {
64+
export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, Partial<DocumentationSuiteConfiguration>, LoggingConfiguration {
6565
readonly defaultSectionLayout?: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: ApiItemTransformationConfiguration) => SectionNode[];
6666
readonly transformations?: Partial<ApiItemTransformations>;
6767
}
@@ -305,18 +305,18 @@ export abstract class DocumentationParentNodeBase<TDocumentationNode extends Doc
305305
}
306306

307307
// @public
308-
export interface DocumentationSuiteOptions {
309-
readonly documentBoundaries?: DocumentBoundaries;
310-
readonly getAlertsForItem?: (apiItem: ApiItem) => string[];
311-
readonly getFileNameForItem?: (apiItem: ApiItem) => string;
312-
readonly getHeadingTextForItem?: (apiItem: ApiItem) => string;
313-
readonly getLinkTextForItem?: (apiItem: ApiItem) => string;
314-
readonly getUriBaseOverrideForItem?: (apiItem: ApiItem) => string | undefined;
315-
readonly hierarchyBoundaries?: HierarchyBoundaries;
316-
readonly includeBreadcrumb?: boolean;
317-
readonly includeTopLevelDocumentHeading?: boolean;
318-
readonly minimumReleaseLevel?: Omit<ReleaseTag, ReleaseTag.None>;
319-
readonly skipPackage?: (apiPackage: ApiPackage) => boolean;
308+
export interface DocumentationSuiteConfiguration {
309+
readonly documentBoundaries: DocumentBoundaries;
310+
readonly getAlertsForItem: (apiItem: ApiItem) => string[];
311+
readonly getFileNameForItem: (apiItem: ApiItem) => string;
312+
readonly getHeadingTextForItem: (apiItem: ApiItem) => string;
313+
readonly getLinkTextForItem: (apiItem: ApiItem) => string;
314+
readonly getUriBaseOverrideForItem: (apiItem: ApiItem) => string | undefined;
315+
readonly hierarchyBoundaries: HierarchyBoundaries;
316+
readonly includeBreadcrumb: boolean;
317+
readonly includeTopLevelDocumentHeading: boolean;
318+
readonly minimumReleaseLevel: Omit<ReleaseTag, ReleaseTag.None>;
319+
readonly skipPackage: (apiPackage: ApiPackage) => boolean;
320320
}
321321

322322
// @public

‎tools/api-markdown-documenter/api-report/api-markdown-documenter.beta.api.md‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ export { ApiItem }
4949
export { ApiItemKind }
5050

5151
// @public
52-
export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, Required<DocumentationSuiteOptions>, Required<LoggingConfiguration> {
52+
export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, DocumentationSuiteConfiguration, Required<LoggingConfiguration> {
5353
readonly defaultSectionLayout: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: ApiItemTransformationConfiguration) => SectionNode[];
5454
readonly transformations: ApiItemTransformations;
5555
}
@@ -61,7 +61,7 @@ export interface ApiItemTransformationConfigurationBase {
6161
}
6262

6363
// @public
64-
export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, DocumentationSuiteOptions, LoggingConfiguration {
64+
export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, Partial<DocumentationSuiteConfiguration>, LoggingConfiguration {
6565
readonly defaultSectionLayout?: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: ApiItemTransformationConfiguration) => SectionNode[];
6666
readonly transformations?: Partial<ApiItemTransformations>;
6767
}
@@ -305,18 +305,18 @@ export abstract class DocumentationParentNodeBase<TDocumentationNode extends Doc
305305
}
306306

307307
// @public
308-
export interface DocumentationSuiteOptions {
309-
readonly documentBoundaries?: DocumentBoundaries;
310-
readonly getAlertsForItem?: (apiItem: ApiItem) => string[];
311-
readonly getFileNameForItem?: (apiItem: ApiItem) => string;
312-
readonly getHeadingTextForItem?: (apiItem: ApiItem) => string;
313-
readonly getLinkTextForItem?: (apiItem: ApiItem) => string;
314-
readonly getUriBaseOverrideForItem?: (apiItem: ApiItem) => string | undefined;
315-
readonly hierarchyBoundaries?: HierarchyBoundaries;
316-
readonly includeBreadcrumb?: boolean;
317-
readonly includeTopLevelDocumentHeading?: boolean;
318-
readonly minimumReleaseLevel?: Omit<ReleaseTag, ReleaseTag.None>;
319-
readonly skipPackage?: (apiPackage: ApiPackage) => boolean;
308+
export interface DocumentationSuiteConfiguration {
309+
readonly documentBoundaries: DocumentBoundaries;
310+
readonly getAlertsForItem: (apiItem: ApiItem) => string[];
311+
readonly getFileNameForItem: (apiItem: ApiItem) => string;
312+
readonly getHeadingTextForItem: (apiItem: ApiItem) => string;
313+
readonly getLinkTextForItem: (apiItem: ApiItem) => string;
314+
readonly getUriBaseOverrideForItem: (apiItem: ApiItem) => string | undefined;
315+
readonly hierarchyBoundaries: HierarchyBoundaries;
316+
readonly includeBreadcrumb: boolean;
317+
readonly includeTopLevelDocumentHeading: boolean;
318+
readonly minimumReleaseLevel: Omit<ReleaseTag, ReleaseTag.None>;
319+
readonly skipPackage: (apiPackage: ApiPackage) => boolean;
320320
}
321321

322322
// @public

‎tools/api-markdown-documenter/api-report/api-markdown-documenter.public.api.md‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ export { ApiItem }
4949
export { ApiItemKind }
5050

5151
// @public
52-
export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, Required<DocumentationSuiteOptions>, Required<LoggingConfiguration> {
52+
export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, DocumentationSuiteConfiguration, Required<LoggingConfiguration> {
5353
readonly defaultSectionLayout: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: ApiItemTransformationConfiguration) => SectionNode[];
5454
readonly transformations: ApiItemTransformations;
5555
}
@@ -61,7 +61,7 @@ export interface ApiItemTransformationConfigurationBase {
6161
}
6262

6363
// @public
64-
export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, DocumentationSuiteOptions, LoggingConfiguration {
64+
export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, Partial<DocumentationSuiteConfiguration>, LoggingConfiguration {
6565
readonly defaultSectionLayout?: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: ApiItemTransformationConfiguration) => SectionNode[];
6666
readonly transformations?: Partial<ApiItemTransformations>;
6767
}
@@ -305,18 +305,18 @@ export abstract class DocumentationParentNodeBase<TDocumentationNode extends Doc
305305
}
306306

307307
// @public
308-
export interface DocumentationSuiteOptions {
309-
readonly documentBoundaries?: DocumentBoundaries;
310-
readonly getAlertsForItem?: (apiItem: ApiItem) => string[];
311-
readonly getFileNameForItem?: (apiItem: ApiItem) => string;
312-
readonly getHeadingTextForItem?: (apiItem: ApiItem) => string;
313-
readonly getLinkTextForItem?: (apiItem: ApiItem) => string;
314-
readonly getUriBaseOverrideForItem?: (apiItem: ApiItem) => string | undefined;
315-
readonly hierarchyBoundaries?: HierarchyBoundaries;
316-
readonly includeBreadcrumb?: boolean;
317-
readonly includeTopLevelDocumentHeading?: boolean;
318-
readonly minimumReleaseLevel?: Omit<ReleaseTag, ReleaseTag.None>;
319-
readonly skipPackage?: (apiPackage: ApiPackage) => boolean;
308+
export interface DocumentationSuiteConfiguration {
309+
readonly documentBoundaries: DocumentBoundaries;
310+
readonly getAlertsForItem: (apiItem: ApiItem) => string[];
311+
readonly getFileNameForItem: (apiItem: ApiItem) => string;
312+
readonly getHeadingTextForItem: (apiItem: ApiItem) => string;
313+
readonly getLinkTextForItem: (apiItem: ApiItem) => string;
314+
readonly getUriBaseOverrideForItem: (apiItem: ApiItem) => string | undefined;
315+
readonly hierarchyBoundaries: HierarchyBoundaries;
316+
readonly includeBreadcrumb: boolean;
317+
readonly includeTopLevelDocumentHeading: boolean;
318+
readonly minimumReleaseLevel: Omit<ReleaseTag, ReleaseTag.None>;
319+
readonly skipPackage: (apiPackage: ApiPackage) => boolean;
320320
}
321321

322322
// @public

‎tools/api-markdown-documenter/src/RenderHtml.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,13 +31,13 @@ export interface RenderApiModelAsHtmlOptions
3131
* @remarks
3232
*
3333
* Which API members get their own documents and which get written to the contents of their parent is
34-
* determined by {@link DocumentationSuiteOptions.documentBoundaries}.
34+
* determined by {@link DocumentationSuiteConfiguration.documentBoundaries}.
3535
*
3636
* The file paths under which the files will be generated is determined by the provided output path and the
3737
* following configuration properties:
3838
*
39-
* - {@link DocumentationSuiteOptions.documentBoundaries}
40-
* - {@link DocumentationSuiteOptions.hierarchyBoundaries}
39+
* - {@link DocumentationSuiteConfiguration.documentBoundaries}
40+
* - {@link DocumentationSuiteConfiguration.hierarchyBoundaries}
4141
*
4242
* @param transformConfig - Configuration for transforming API items into {@link DocumentationNode}s.
4343
* @param renderConfig - Configuration for rendering {@link DocumentNode}s as HTML.

‎tools/api-markdown-documenter/src/RenderMarkdown.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,13 +31,13 @@ export interface RenderApiModelAsMarkdownOptions
3131
* @remarks
3232
*
3333
* Which API members get their own documents and which get written to the contents of their parent is
34-
* determined by {@link DocumentationSuiteOptions.documentBoundaries}.
34+
* determined by {@link DocumentationSuiteConfiguration.documentBoundaries}.
3535
*
3636
* The file paths under which the files will be generated is determined by the provided output path and the
3737
* following configuration properties:
3838
*
39-
* - {@link DocumentationSuiteOptions.documentBoundaries}
40-
* - {@link DocumentationSuiteOptions.hierarchyBoundaries}
39+
* - {@link DocumentationSuiteConfiguration.documentBoundaries}
40+
* - {@link DocumentationSuiteConfiguration.hierarchyBoundaries}
4141
*
4242
* @param transformConfig - Configuration for transforming API items into {@link DocumentationNode}s.
4343
* @param renderConfig - Configuration for rendering {@link DocumentNode}s as Markdown.

‎tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -356,7 +356,7 @@ export function getAncestralHierarchy(
356356
/**
357357
* Determines whether or not the specified API item kind is one that should be rendered to its own document.
358358
*
359-
* @remarks This is essentially a wrapper around {@link DocumentationSuiteOptions.documentBoundaries}, but also enforces
359+
* @remarks This is essentially a wrapper around {@link DocumentationSuiteConfiguration.documentBoundaries}, but also enforces
360360
* system-wide invariants.
361361
*
362362
* Namely...
@@ -390,7 +390,7 @@ export function doesItemKindRequireOwnDocument(
390390
*
391391
* @remarks
392392
*
393-
* This is essentially a wrapper around {@link DocumentationSuiteOptions.hierarchyBoundaries}, but also enforces
393+
* This is essentially a wrapper around {@link DocumentationSuiteConfiguration.hierarchyBoundaries}, but also enforces
394394
* system-wide invariants.
395395
*
396396
* Namely...
@@ -419,7 +419,7 @@ export function doesItemRequireOwnDocument(
419419
*
420420
* @remarks
421421
*
422-
* This is essentially a wrapper around {@link DocumentationSuiteOptions.hierarchyBoundaries}, but also enforces
422+
* This is essentially a wrapper around {@link DocumentationSuiteConfiguration.hierarchyBoundaries}, but also enforces
423423
* system-wide invariants.
424424
*
425425
* Namely...
@@ -474,7 +474,7 @@ function doesItemGenerateHierarchy(
474474
/**
475475
* Determines whether or not the specified API item should have documentation generated for it.
476476
* This is determined based on its release tag (or inherited release scope) compared to
477-
* {@link DocumentationSuiteOptions.minimumReleaseLevel}.
477+
* {@link DocumentationSuiteConfiguration.minimumReleaseLevel}.
478478
*
479479
* @remarks
480480
*
@@ -538,7 +538,7 @@ export function shouldItemBeIncluded(
538538
/**
539539
* Filters and returns the provided list of `ApiItem`s to include only those desired by the user configuration.
540540
* This is determined based on its release tag (or inherited release scope) compared to
541-
* {@link DocumentationSuiteOptions.minimumReleaseLevel}.
541+
* {@link DocumentationSuiteConfiguration.minimumReleaseLevel}.
542542
* @param apiItem - The API item being queried.
543543
* @param config - See {@link ApiItemTransformationConfiguration}.
544544
*
@@ -554,7 +554,7 @@ export function filterItems(
554554
/**
555555
* Filters and returns the child members of the provided `apiItem` to include only those desired by the user configuration.
556556
* This is determined based on its release tag (or inherited release scope) compared to
557-
* {@link DocumentationSuiteOptions.minimumReleaseLevel}.
557+
* {@link DocumentationSuiteConfiguration.minimumReleaseLevel}.
558558
* @remarks See {@link shouldItemBeIncluded} for more details.
559559
* @param apiItem - The API item being queried.
560560
* @param config - See {@link ApiItemTransformationConfiguration}.

‎tools/api-markdown-documenter/src/api-item-transforms/TransformApiItem.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ import { createBreadcrumbParagraph, wrapInSection } from "./helpers/index.js";
3939
*
4040
* This should only be called for API item kinds that are intended to be rendered to their own document
4141
* (as opposed to being rendered to the same document as their parent) per the provided `config`
42-
* (see {@link DocumentationSuiteOptions.documentBoundaries}).
42+
* (see {@link DocumentationSuiteConfiguration.documentBoundaries}).
4343
*
4444
* Also note that this should not be called for the following item kinds, which must be handled specially:
4545
*

‎tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,13 +29,13 @@ import { createBreadcrumbParagraph, createEntryPointList, wrapInSection } from "
2929
* @remarks
3030
*
3131
* Which API members get their own documents and which get written to the contents of their parent is
32-
* determined by {@link DocumentationSuiteOptions.documentBoundaries}.
32+
* determined by {@link DocumentationSuiteConfiguration.documentBoundaries}.
3333
*
3434
* The generated nodes' {@link DocumentNode.documentPath}s are determined by the provided output path and the
3535
* following configuration properties:
3636
*
37-
* - {@link DocumentationSuiteOptions.documentBoundaries}
38-
* - {@link DocumentationSuiteOptions.hierarchyBoundaries}
37+
* - {@link DocumentationSuiteConfiguration.documentBoundaries}
38+
* - {@link DocumentationSuiteConfiguration.hierarchyBoundaries}
3939
*
4040
* @param options - Options for transforming API items into {@link DocumentationNode}s.
4141
*

‎tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@ import type { SectionNode } from "../../documentation-domain/index.js";
1111
import { createSectionForApiItem } from "../default-implementations/index.js";
1212

1313
import {
14-
type DocumentationSuiteOptions,
15-
getDocumentationSuiteOptionsWithDefaults,
16-
} from "./DocumentationSuiteOptions.js";
14+
type DocumentationSuiteConfiguration,
15+
getDocumentationSuiteConfigurationWithDefaults,
16+
} from "./DocumentationSuite.js";
1717
import {
1818
type ApiItemTransformations,
1919
getApiItemTransformationsWithDefaults,
@@ -57,7 +57,7 @@ export interface ApiItemTransformationConfigurationBase {
5757
*/
5858
export interface ApiItemTransformationConfiguration
5959
extends ApiItemTransformationConfigurationBase,
60-
Required<DocumentationSuiteOptions>,
60+
DocumentationSuiteConfiguration,
6161
Required<LoggingConfiguration> {
6262
/**
6363
* {@inheritDoc ApiItemTransformations}
@@ -89,7 +89,7 @@ export interface ApiItemTransformationConfiguration
8989
*/
9090
export interface ApiItemTransformationOptions
9191
extends ApiItemTransformationConfigurationBase,
92-
DocumentationSuiteOptions,
92+
Partial<DocumentationSuiteConfiguration>,
9393
LoggingConfiguration {
9494
/**
9595
* Optional overrides for the default transformations.
@@ -117,7 +117,7 @@ export function getApiItemTransformationConfigurationWithDefaults(
117117
): ApiItemTransformationConfiguration {
118118
const logger = options.logger ?? defaultConsoleLogger;
119119
const defaultSectionLayout = options.defaultSectionLayout ?? createSectionForApiItem;
120-
const documentationSuiteOptions = getDocumentationSuiteOptionsWithDefaults(options);
120+
const documentationSuiteOptions = getDocumentationSuiteConfigurationWithDefaults(options);
121121
const transformations = getApiItemTransformationsWithDefaults(options?.transformations);
122122
return {
123123
...documentationSuiteOptions,

0 commit comments

Comments
 (0)