diff --git a/apps/api-documenter/src/documenters/MarkdownDocumenter.ts b/apps/api-documenter/src/documenters/MarkdownDocumenter.ts index 0deb6ed6edf..203509cf816 100644 --- a/apps/api-documenter/src/documenters/MarkdownDocumenter.ts +++ b/apps/api-documenter/src/documenters/MarkdownDocumenter.ts @@ -273,6 +273,7 @@ export class MarkdownDocumenter { case ApiItemKind.Function: this._writeParameterTables(output, apiItem as ApiParameterListMixin); this._writeThrowsSection(output, apiItem); + this._writeDefaultValueSection(output, apiItem); break; case ApiItemKind.Namespace: this._writePackageOrNamespaceTables(output, apiItem as ApiNamespace); @@ -285,10 +286,13 @@ export class MarkdownDocumenter { break; case ApiItemKind.Property: case ApiItemKind.PropertySignature: + this._writeDefaultValueSection(output, apiItem); break; case ApiItemKind.TypeAlias: + this._writeDefaultValueSection(output, apiItem); break; case ApiItemKind.Variable: + this._writeDefaultValueSection(output, apiItem); break; default: throw new Error('Unsupported API item kind: ' + apiItem.kind); @@ -469,6 +473,30 @@ export class MarkdownDocumenter { } } + private _writeDefaultValueSection(output: DocSection, apiItem: ApiItem): void { + const configuration: TSDocConfiguration = this._tsdocConfiguration; + + if (apiItem instanceof ApiDocumentedItem) { + const tsdocComment: DocComment | undefined = apiItem.tsdocComment; + + if (tsdocComment) { + // Write the @defaultValue blocks + const defaultValueBlocks: DocBlock[] = tsdocComment.customBlocks.filter( + (x) => x.blockTag.tagNameWithUpperCase === StandardTags.defaultValue.tagNameWithUpperCase + ); + + if (defaultValueBlocks.length > 0) { + const heading: string = 'Default Value'; + output.appendNode(new DocHeading({ configuration, title: heading })); + + for (const defaultValueBlock of defaultValueBlocks) { + this._appendSection(output, defaultValueBlock.content); + } + } + } + } + } + /** * GENERATE PAGE: MODEL */ diff --git a/apps/api-documenter/src/documenters/YamlDocumenter.ts b/apps/api-documenter/src/documenters/YamlDocumenter.ts index 3ca47d82954..73420328756 100644 --- a/apps/api-documenter/src/documenters/YamlDocumenter.ts +++ b/apps/api-documenter/src/documenters/YamlDocumenter.ts @@ -427,6 +427,18 @@ export class YamlDocumenter { yamlItem.example = [...(yamlItem.example || []), example]; } } + + // Write the @defaultValue block + const defaultValueBlocks: DocBlock[] = tsdocComment.customBlocks.filter( + (x) => x.blockTag.tagNameWithUpperCase === StandardTags.defaultValue.tagNameWithUpperCase + ); + + for (const defaultValueBlock of defaultValueBlocks) { + const defaultValueContent: string = this._renderMarkdown(defaultValueBlock.content, apiItem); + if (defaultValueContent) { + yamlItem.defaultValue = defaultValueContent.trim(); + } + } } if (tsdocComment.deprecatedBlock) { diff --git a/apps/api-documenter/src/utils/ToSdpConvertHelper.ts b/apps/api-documenter/src/utils/ToSdpConvertHelper.ts index 8d12f9df7f8..c81d01f6a18 100644 --- a/apps/api-documenter/src/utils/ToSdpConvertHelper.ts +++ b/apps/api-documenter/src/utils/ToSdpConvertHelper.ts @@ -304,6 +304,10 @@ function convertCommonYamlModel( result.example = []; } + if (element.defaultValue) { + result.defaultValue = element.defaultValue; + } + result.isPreview = element.isPreview; if (!result.isPreview) { result.isPreview = false; diff --git a/apps/api-documenter/src/yaml/ISDPYamlFile.ts b/apps/api-documenter/src/yaml/ISDPYamlFile.ts index 413d73e8d6b..574434154d4 100644 --- a/apps/api-documenter/src/yaml/ISDPYamlFile.ts +++ b/apps/api-documenter/src/yaml/ISDPYamlFile.ts @@ -16,6 +16,7 @@ export type CommonYamlModel = IBaseYamlModel & { remarks?: string; example?: string[]; customDeprecatedMessage?: string; + defaultValue?: string; }; export type PackageYamlModel = CommonYamlModel & { diff --git a/apps/api-documenter/src/yaml/IYamlApiFile.ts b/apps/api-documenter/src/yaml/IYamlApiFile.ts index 58048a50d41..59f1b2ab1ad 100644 --- a/apps/api-documenter/src/yaml/IYamlApiFile.ts +++ b/apps/api-documenter/src/yaml/IYamlApiFile.ts @@ -327,6 +327,12 @@ export interface IYamlItem { * NOTE: This is an extension and corresponds to `ItemViewModel.Metadata` in DocFX. */ package?: string; + + /** + * The default value for the item. + * NOTE: This is an extension and corresponds to `ItemViewModel.Metadata` in DocFX. + */ + defaultValue?: string; } /** diff --git a/apps/api-documenter/src/yaml/typescript.schema.json b/apps/api-documenter/src/yaml/typescript.schema.json index cc1ad42ccf0..d5baf66d72a 100644 --- a/apps/api-documenter/src/yaml/typescript.schema.json +++ b/apps/api-documenter/src/yaml/typescript.schema.json @@ -262,6 +262,9 @@ }, "package": { "type": "string" + }, + "defaultValue": { + "type": "string" } }, "patternProperties": { diff --git a/build-tests/api-documenter-test/etc/api-documenter-test.api.json b/build-tests/api-documenter-test/etc/api-documenter-test.api.json index a84567c2040..19aa17448e4 100644 --- a/build-tests/api-documenter-test/etc/api-documenter-test.api.json +++ b/build-tests/api-documenter-test/etc/api-documenter-test.api.json @@ -592,7 +592,7 @@ { "kind": "Method", "canonicalReference": "api-documenter-test!DocClass1#exampleFunction:member(2)", - "docComment": "/**\n * This is also an overloaded function.\n *\n * @param x - the number\n */\n", + "docComment": "/**\n * This is also an overloaded function.\n *\n * @param x - the number\n *\n * @defaultValue 123\n */\n", "excerptTokens": [ { "kind": "Content", @@ -2119,7 +2119,7 @@ { "kind": "PropertySignature", "canonicalReference": "api-documenter-test!IDocInterface5#regularProperty:member", - "docComment": "/**\n * Property of type string that does something\n */\n", + "docComment": "/**\n * Property of type string that does something\n *\n * @defaultValue \"Hello World\"\n */\n", "excerptTokens": [ { "kind": "Content", diff --git a/build-tests/api-documenter-test/src/DocClass1.ts b/build-tests/api-documenter-test/src/DocClass1.ts index fb343b1e1aa..1f7100236aa 100644 --- a/build-tests/api-documenter-test/src/DocClass1.ts +++ b/build-tests/api-documenter-test/src/DocClass1.ts @@ -219,6 +219,8 @@ export class DocClass1 extends DocBaseClass implements IDocInterface1, IDocInter /** * This is also an overloaded function. * @param x - the number + * + * @defaultValue 123 */ // eslint-disable-next-line @typescript-eslint/explicit-member-accessibility exampleFunction(x: number): number; @@ -316,6 +318,8 @@ export class DocClass1 extends DocBaseClass implements IDocInterface1, IDocInter export interface IDocInterface5 { /** * Property of type string that does something + * + * @defaultValue "Hello World" */ regularProperty: string; } diff --git a/build-tests/api-documenter-test/src/test/__snapshots__/snapshot.test.ts.snap b/build-tests/api-documenter-test/src/test/__snapshots__/snapshot.test.ts.snap index fabda2846fd..0d9cd4a9122 100644 --- a/build-tests/api-documenter-test/src/test/__snapshots__/snapshot.test.ts.snap +++ b/build-tests/api-documenter-test/src/test/__snapshots__/snapshot.test.ts.snap @@ -349,6 +349,7 @@ methods: summary: This is also an overloaded function. remarks: '' example: [] + defaultValue: '123' isPreview: false isDeprecated: false syntax: @@ -885,6 +886,7 @@ properties: summary: Property of type string that does something remarks: '' example: [] + defaultValue: '\\"Hello World\\"' isPreview: false isDeprecated: false syntax: @@ -1800,6 +1802,10 @@ the number number +## Default Value + +123 + ", "/api-documenter-test.docclass1.genericwithconstraintanddefault.md": " @@ -3452,6 +3458,11 @@ Property of type string that does something \`\`\`typescript regularProperty: string; \`\`\` + +## Default Value + +\\"Hello World\\" + ", "/api-documenter-test.idocinterface6.arrayproperty.md": " diff --git a/common/changes/@microsoft/api-documenter/fix-api-documenter-defaultvalue_2026-03-30-07-12.json b/common/changes/@microsoft/api-documenter/fix-api-documenter-defaultvalue_2026-03-30-07-12.json new file mode 100644 index 00000000000..0c6b6b6610b --- /dev/null +++ b/common/changes/@microsoft/api-documenter/fix-api-documenter-defaultvalue_2026-03-30-07-12.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "comment": "Add support for @defaultValue in Markdown and Yaml documenters", + "type": "minor", + "packageName": "@microsoft/api-documenter" + } + ], + "packageName": "@microsoft/api-documenter", + "email": "40660121+colinaaa@users.noreply.github.com" +} \ No newline at end of file