diff --git a/apps/api-documenter/src/documenters/MarkdownDocumenter.ts b/apps/api-documenter/src/documenters/MarkdownDocumenter.ts index e2f3afdf7d9..943811d2bd8 100644 --- a/apps/api-documenter/src/documenters/MarkdownDocumenter.ts +++ b/apps/api-documenter/src/documenters/MarkdownDocumenter.ts @@ -173,7 +173,9 @@ export class MarkdownDocumenter { } if (ApiReleaseTagMixin.isBaseClassOf(apiItem)) { - if (apiItem.releaseTag === ReleaseTag.Beta) { + if (apiItem.releaseTag === ReleaseTag.Alpha) { + this._writeAlphaWarning(output); + } else if (apiItem.releaseTag === ReleaseTag.Beta) { this._writeBetaWarning(output); } } @@ -1000,10 +1002,13 @@ export class MarkdownDocumenter { const section: DocSection = new DocSection({ configuration }); if (ApiReleaseTagMixin.isBaseClassOf(apiItem)) { - if (apiItem.releaseTag === ReleaseTag.Beta) { + if (apiItem.releaseTag === ReleaseTag.Alpha || apiItem.releaseTag === ReleaseTag.Beta) { section.appendNodesInParagraph([ new DocEmphasisSpan({ configuration, bold: true, italic: true }, [ - new DocPlainText({ configuration, text: '(BETA)' }) + new DocPlainText({ + configuration, + text: `(${apiItem.releaseTag === ReleaseTag.Alpha ? 'ALPHA' : 'BETA'})` + }) ]), new DocPlainText({ configuration, text: ' ' }) ]); @@ -1152,10 +1157,22 @@ export class MarkdownDocumenter { } } + private _writeAlphaWarning(output: DocSection): void { + const configuration: TSDocConfiguration = this._tsdocConfiguration; + const betaWarning: string = + 'This API is provided as an alpha preview for developers and may change' + + ' based on feedback that we receive. Do not use this API in a production environment.'; + output.appendNode( + new DocNoteBox({ configuration }, [ + new DocParagraph({ configuration }, [new DocPlainText({ configuration, text: betaWarning })]) + ]) + ); + } + private _writeBetaWarning(output: DocSection): void { const configuration: TSDocConfiguration = this._tsdocConfiguration; const betaWarning: string = - 'This API is provided as a preview for developers and may change' + + 'This API is provided as a beta preview for developers and may change' + ' based on feedback that we receive. Do not use this API in a production environment.'; output.appendNode( new DocNoteBox({ configuration }, [ diff --git a/apps/api-documenter/src/documenters/YamlDocumenter.ts b/apps/api-documenter/src/documenters/YamlDocumenter.ts index 9f04aa959e0..5bc50269d73 100644 --- a/apps/api-documenter/src/documenters/YamlDocumenter.ts +++ b/apps/api-documenter/src/documenters/YamlDocumenter.ts @@ -425,7 +425,7 @@ export class YamlDocumenter { } if (ApiReleaseTagMixin.isBaseClassOf(apiItem)) { - if (apiItem.releaseTag === ReleaseTag.Beta) { + if (apiItem.releaseTag === ReleaseTag.Alpha || apiItem.releaseTag === ReleaseTag.Beta) { yamlItem.isPreview = true; } } diff --git a/apps/api-extractor/src/generators/ApiModelGenerator.ts b/apps/api-extractor/src/generators/ApiModelGenerator.ts index 64c4fc56ceb..0d0037cb2ba 100644 --- a/apps/api-extractor/src/generators/ApiModelGenerator.ts +++ b/apps/api-extractor/src/generators/ApiModelGenerator.ts @@ -176,8 +176,8 @@ export class ApiModelGenerator { const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration); const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag; - if (releaseTag === ReleaseTag.Internal || releaseTag === ReleaseTag.Alpha) { - return; // trim out items marked as "@internal" or "@alpha" + if (releaseTag === ReleaseTag.Internal) { + return; // trim out items marked as "@internal" } switch (astDeclaration.declaration.kind) { diff --git a/common/changes/@microsoft/api-documenter/patch-1_2023-09-20-22-22.json b/common/changes/@microsoft/api-documenter/patch-1_2023-09-20-22-22.json new file mode 100644 index 00000000000..03c87b4c08e --- /dev/null +++ b/common/changes/@microsoft/api-documenter/patch-1_2023-09-20-22-22.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@microsoft/api-documenter", + "comment": "Add notes for @alpha items when encountered. Mimics the existing behavior for @beta items.", + "type": "patch" + } + ], + "packageName": "@microsoft/api-documenter" +} diff --git a/common/changes/@microsoft/api-extractor/patch-1_2023-09-20-22-22.json b/common/changes/@microsoft/api-extractor/patch-1_2023-09-20-22-22.json new file mode 100644 index 00000000000..e86b732621d --- /dev/null +++ b/common/changes/@microsoft/api-extractor/patch-1_2023-09-20-22-22.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@microsoft/api-extractor", + "comment": "Don't strip out @alpha items when generating API reports.", + "type": "patch" + } + ], + "packageName": "@microsoft/api-extractor" +}