From 416865ac324b4631e45a7d6c2762790c3c524cd0 Mon Sep 17 00:00:00 2001 From: leaysgur <6259812+leaysgur@users.noreply.github.com> Date: Mon, 23 Mar 2026 09:00:46 +0000 Subject: [PATCH] feat(formatter,oxfmt): Add doc comments for `JsdocConfig` (#20644) Follow up #19828 --- apps/oxfmt/src-js/config.generated.ts | 65 ++++++++++++- apps/oxfmt/src/core/oxfmtrc/format_config.rs | 97 +++++++++++++------ npm/oxfmt/configuration_schema.json | 48 ++++++--- .../src/snapshots/schema_json.snap | 48 ++++++--- .../src/snapshots/schema_markdown.snap | 58 +++++++++++ 5 files changed, 257 insertions(+), 59 deletions(-) diff --git a/apps/oxfmt/src-js/config.generated.ts b/apps/oxfmt/src-js/config.generated.ts index 58528e89f5e8a..e21b6cf474feb 100644 --- a/apps/oxfmt/src-js/config.generated.ts +++ b/apps/oxfmt/src-js/config.generated.ts @@ -216,20 +216,79 @@ export interface Oxfmtrc { vueIndentScriptAndStyle?: boolean; [k: string]: unknown; } -/** - * JSDoc configuration object with fine-grained options. - */ export interface JsdocConfig { + /** + * Append default values to `@param` descriptions (e.g. "Default is `value`"). + * + * - Default: `true` + */ addDefaultToDescription?: boolean; + /** + * Add spaces inside JSDoc type braces: `{string}` → `{ string }`. + * + * - Default: `false` + */ bracketSpacing?: boolean; + /** + * Capitalize the first letter of tag descriptions. + * + * - Default: `true` + */ capitalizeDescriptions?: boolean; + /** + * How to format comment blocks. + * + * - `"singleLine"` — Convert to single-line `/** content * /` when possible. + * - `"multiline"` — Always use multi-line format. + * - `"keep"` — Preserve original formatting. + * + * - Default: `"singleLine"` + */ commentLineStrategy?: string; + /** + * Emit `@description` tag instead of inline description. + * + * - Default: `false` + */ descriptionTag?: boolean; + /** + * Add a trailing dot to the end of descriptions. + * + * - Default: `false` + */ descriptionWithDot?: boolean; + /** + * Preserve indentation in unparsable `@example` code. + * + * - Default: `false` + */ keepUnparsableExampleIndent?: boolean; + /** + * Strategy for wrapping description lines at print width. + * + * - `"greedy"` — Always re-wrap text to fit within print width. + * - `"balance"` — Preserve original line breaks if all lines fit within print width. + * + * - Default: `"greedy"` + */ lineWrappingStyle?: string; + /** + * Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag. + * + * - Default: `false` + */ preferCodeFences?: boolean; + /** + * Add a blank line between the last `@param` and `@returns`. + * + * - Default: `false` + */ separateReturnsFromParam?: boolean; + /** + * Add blank lines between different tag groups (e.g. between `@param` and `@returns`). + * + * - Default: `false` + */ separateTagGroups?: boolean; [k: string]: unknown; } diff --git a/apps/oxfmt/src/core/oxfmtrc/format_config.rs b/apps/oxfmt/src/core/oxfmtrc/format_config.rs index 29a2542d1cc4e..7b7cd57a918f5 100644 --- a/apps/oxfmt/src/core/oxfmtrc/format_config.rs +++ b/apps/oxfmt/src/core/oxfmtrc/format_config.rs @@ -237,34 +237,6 @@ pub struct FormatConfig { pub jsdoc: Option, } -/// JSDoc configuration object with fine-grained options. -#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)] -#[serde(rename_all = "camelCase")] -pub struct JsdocConfig { - #[serde(skip_serializing_if = "Option::is_none")] - pub capitalize_descriptions: Option, - #[serde(skip_serializing_if = "Option::is_none")] - pub description_with_dot: Option, - #[serde(skip_serializing_if = "Option::is_none")] - pub add_default_to_description: Option, - #[serde(skip_serializing_if = "Option::is_none")] - pub prefer_code_fences: Option, - #[serde(skip_serializing_if = "Option::is_none")] - pub line_wrapping_style: Option, - #[serde(skip_serializing_if = "Option::is_none")] - pub comment_line_strategy: Option, - #[serde(skip_serializing_if = "Option::is_none")] - pub separate_tag_groups: Option, - #[serde(skip_serializing_if = "Option::is_none")] - pub separate_returns_from_param: Option, - #[serde(skip_serializing_if = "Option::is_none")] - pub bracket_spacing: Option, - #[serde(skip_serializing_if = "Option::is_none")] - pub description_tag: Option, - #[serde(skip_serializing_if = "Option::is_none")] - pub keep_unparsable_example_indent: Option, -} - impl FormatConfig { /// Resolve relative tailwind paths (`config`, `stylesheet`) to absolute paths. /// Otherwise, the plugin tries to resolve the Prettier's configuration file, not Oxfmt's. @@ -656,6 +628,75 @@ pub struct SortTailwindcssConfig { // --- +#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)] +#[serde(rename_all = "camelCase")] +pub struct JsdocConfig { + /// Capitalize the first letter of tag descriptions. + /// + /// - Default: `true` + #[serde(skip_serializing_if = "Option::is_none")] + pub capitalize_descriptions: Option, + /// Add a trailing dot to the end of descriptions. + /// + /// - Default: `false` + #[serde(skip_serializing_if = "Option::is_none")] + pub description_with_dot: Option, + /// Append default values to `@param` descriptions (e.g. "Default is `value`"). + /// + /// - Default: `true` + #[serde(skip_serializing_if = "Option::is_none")] + pub add_default_to_description: Option, + /// Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag. + /// + /// - Default: `false` + #[serde(skip_serializing_if = "Option::is_none")] + pub prefer_code_fences: Option, + /// Strategy for wrapping description lines at print width. + /// + /// - `"greedy"` — Always re-wrap text to fit within print width. + /// - `"balance"` — Preserve original line breaks if all lines fit within print width. + /// + /// - Default: `"greedy"` + #[serde(skip_serializing_if = "Option::is_none")] + pub line_wrapping_style: Option, + /// How to format comment blocks. + /// + /// - `"singleLine"` — Convert to single-line `/** content */` when possible. + /// - `"multiline"` — Always use multi-line format. + /// - `"keep"` — Preserve original formatting. + /// + /// - Default: `"singleLine"` + #[serde(skip_serializing_if = "Option::is_none")] + pub comment_line_strategy: Option, + /// Add blank lines between different tag groups (e.g. between `@param` and `@returns`). + /// + /// - Default: `false` + #[serde(skip_serializing_if = "Option::is_none")] + pub separate_tag_groups: Option, + /// Add a blank line between the last `@param` and `@returns`. + /// + /// - Default: `false` + #[serde(skip_serializing_if = "Option::is_none")] + pub separate_returns_from_param: Option, + /// Add spaces inside JSDoc type braces: `{string}` → `{ string }`. + /// + /// - Default: `false` + #[serde(skip_serializing_if = "Option::is_none")] + pub bracket_spacing: Option, + /// Emit `@description` tag instead of inline description. + /// + /// - Default: `false` + #[serde(skip_serializing_if = "Option::is_none")] + pub description_tag: Option, + /// Preserve indentation in unparsable `@example` code. + /// + /// - Default: `false` + #[serde(skip_serializing_if = "Option::is_none")] + pub keep_unparsable_example_indent: Option, +} + +// --- + /// Merge two JSON values recursively. /// - Overlay values overwrite base values /// - `null` values in overlay reset the field to default (via `Option` → `None`) diff --git a/npm/oxfmt/configuration_schema.json b/npm/oxfmt/configuration_schema.json index 26e76b79bcddb..3c1ed20a8f8e3 100644 --- a/npm/oxfmt/configuration_schema.json +++ b/npm/oxfmt/configuration_schema.json @@ -427,44 +427,64 @@ ] }, "JsdocConfig": { - "description": "JSDoc configuration object with fine-grained options.", "type": "object", "properties": { "addDefaultToDescription": { - "type": "boolean" + "description": "Append default values to `@param` descriptions (e.g. \"Default is `value`\").\n\n- Default: `true`", + "type": "boolean", + "markdownDescription": "Append default values to `@param` descriptions (e.g. \"Default is `value`\").\n\n- Default: `true`" }, "bracketSpacing": { - "type": "boolean" + "description": "Add spaces inside JSDoc type braces: `{string}` → `{ string }`.\n\n- Default: `false`", + "type": "boolean", + "markdownDescription": "Add spaces inside JSDoc type braces: `{string}` → `{ string }`.\n\n- Default: `false`" }, "capitalizeDescriptions": { - "type": "boolean" + "description": "Capitalize the first letter of tag descriptions.\n\n- Default: `true`", + "type": "boolean", + "markdownDescription": "Capitalize the first letter of tag descriptions.\n\n- Default: `true`" }, "commentLineStrategy": { - "type": "string" + "description": "How to format comment blocks.\n\n- `\"singleLine\"` — Convert to single-line `/** content */` when possible.\n- `\"multiline\"` — Always use multi-line format.\n- `\"keep\"` — Preserve original formatting.\n\n- Default: `\"singleLine\"`", + "type": "string", + "markdownDescription": "How to format comment blocks.\n\n- `\"singleLine\"` — Convert to single-line `/** content */` when possible.\n- `\"multiline\"` — Always use multi-line format.\n- `\"keep\"` — Preserve original formatting.\n\n- Default: `\"singleLine\"`" }, "descriptionTag": { - "type": "boolean" + "description": "Emit `@description` tag instead of inline description.\n\n- Default: `false`", + "type": "boolean", + "markdownDescription": "Emit `@description` tag instead of inline description.\n\n- Default: `false`" }, "descriptionWithDot": { - "type": "boolean" + "description": "Add a trailing dot to the end of descriptions.\n\n- Default: `false`", + "type": "boolean", + "markdownDescription": "Add a trailing dot to the end of descriptions.\n\n- Default: `false`" }, "keepUnparsableExampleIndent": { - "type": "boolean" + "description": "Preserve indentation in unparsable `@example` code.\n\n- Default: `false`", + "type": "boolean", + "markdownDescription": "Preserve indentation in unparsable `@example` code.\n\n- Default: `false`" }, "lineWrappingStyle": { - "type": "string" + "description": "Strategy for wrapping description lines at print width.\n\n- `\"greedy\"` — Always re-wrap text to fit within print width.\n- `\"balance\"` — Preserve original line breaks if all lines fit within print width.\n\n- Default: `\"greedy\"`", + "type": "string", + "markdownDescription": "Strategy for wrapping description lines at print width.\n\n- `\"greedy\"` — Always re-wrap text to fit within print width.\n- `\"balance\"` — Preserve original line breaks if all lines fit within print width.\n\n- Default: `\"greedy\"`" }, "preferCodeFences": { - "type": "boolean" + "description": "Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag.\n\n- Default: `false`", + "type": "boolean", + "markdownDescription": "Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag.\n\n- Default: `false`" }, "separateReturnsFromParam": { - "type": "boolean" + "description": "Add a blank line between the last `@param` and `@returns`.\n\n- Default: `false`", + "type": "boolean", + "markdownDescription": "Add a blank line between the last `@param` and `@returns`.\n\n- Default: `false`" }, "separateTagGroups": { - "type": "boolean" + "description": "Add blank lines between different tag groups (e.g. between `@param` and `@returns`).\n\n- Default: `false`", + "type": "boolean", + "markdownDescription": "Add blank lines between different tag groups (e.g. between `@param` and `@returns`).\n\n- Default: `false`" } - }, - "markdownDescription": "JSDoc configuration object with fine-grained options." + } }, "NewlinesBetweenMarker": { "description": "A marker object for overriding `newlinesBetween` at a specific group boundary.", diff --git a/tasks/website_formatter/src/snapshots/schema_json.snap b/tasks/website_formatter/src/snapshots/schema_json.snap index b00d8c46ff032..88d69e610684c 100644 --- a/tasks/website_formatter/src/snapshots/schema_json.snap +++ b/tasks/website_formatter/src/snapshots/schema_json.snap @@ -431,44 +431,64 @@ expression: json ] }, "JsdocConfig": { - "description": "JSDoc configuration object with fine-grained options.", "type": "object", "properties": { "addDefaultToDescription": { - "type": "boolean" + "description": "Append default values to `@param` descriptions (e.g. \"Default is `value`\").\n\n- Default: `true`", + "type": "boolean", + "markdownDescription": "Append default values to `@param` descriptions (e.g. \"Default is `value`\").\n\n- Default: `true`" }, "bracketSpacing": { - "type": "boolean" + "description": "Add spaces inside JSDoc type braces: `{string}` → `{ string }`.\n\n- Default: `false`", + "type": "boolean", + "markdownDescription": "Add spaces inside JSDoc type braces: `{string}` → `{ string }`.\n\n- Default: `false`" }, "capitalizeDescriptions": { - "type": "boolean" + "description": "Capitalize the first letter of tag descriptions.\n\n- Default: `true`", + "type": "boolean", + "markdownDescription": "Capitalize the first letter of tag descriptions.\n\n- Default: `true`" }, "commentLineStrategy": { - "type": "string" + "description": "How to format comment blocks.\n\n- `\"singleLine\"` — Convert to single-line `/** content */` when possible.\n- `\"multiline\"` — Always use multi-line format.\n- `\"keep\"` — Preserve original formatting.\n\n- Default: `\"singleLine\"`", + "type": "string", + "markdownDescription": "How to format comment blocks.\n\n- `\"singleLine\"` — Convert to single-line `/** content */` when possible.\n- `\"multiline\"` — Always use multi-line format.\n- `\"keep\"` — Preserve original formatting.\n\n- Default: `\"singleLine\"`" }, "descriptionTag": { - "type": "boolean" + "description": "Emit `@description` tag instead of inline description.\n\n- Default: `false`", + "type": "boolean", + "markdownDescription": "Emit `@description` tag instead of inline description.\n\n- Default: `false`" }, "descriptionWithDot": { - "type": "boolean" + "description": "Add a trailing dot to the end of descriptions.\n\n- Default: `false`", + "type": "boolean", + "markdownDescription": "Add a trailing dot to the end of descriptions.\n\n- Default: `false`" }, "keepUnparsableExampleIndent": { - "type": "boolean" + "description": "Preserve indentation in unparsable `@example` code.\n\n- Default: `false`", + "type": "boolean", + "markdownDescription": "Preserve indentation in unparsable `@example` code.\n\n- Default: `false`" }, "lineWrappingStyle": { - "type": "string" + "description": "Strategy for wrapping description lines at print width.\n\n- `\"greedy\"` — Always re-wrap text to fit within print width.\n- `\"balance\"` — Preserve original line breaks if all lines fit within print width.\n\n- Default: `\"greedy\"`", + "type": "string", + "markdownDescription": "Strategy for wrapping description lines at print width.\n\n- `\"greedy\"` — Always re-wrap text to fit within print width.\n- `\"balance\"` — Preserve original line breaks if all lines fit within print width.\n\n- Default: `\"greedy\"`" }, "preferCodeFences": { - "type": "boolean" + "description": "Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag.\n\n- Default: `false`", + "type": "boolean", + "markdownDescription": "Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag.\n\n- Default: `false`" }, "separateReturnsFromParam": { - "type": "boolean" + "description": "Add a blank line between the last `@param` and `@returns`.\n\n- Default: `false`", + "type": "boolean", + "markdownDescription": "Add a blank line between the last `@param` and `@returns`.\n\n- Default: `false`" }, "separateTagGroups": { - "type": "boolean" + "description": "Add blank lines between different tag groups (e.g. between `@param` and `@returns`).\n\n- Default: `false`", + "type": "boolean", + "markdownDescription": "Add blank lines between different tag groups (e.g. between `@param` and `@returns`).\n\n- Default: `false`" } - }, - "markdownDescription": "JSDoc configuration object with fine-grained options." + } }, "NewlinesBetweenMarker": { "description": "A marker object for overriding `newlinesBetween` at a specific group boundary.", diff --git a/tasks/website_formatter/src/snapshots/schema_markdown.snap b/tasks/website_formatter/src/snapshots/schema_markdown.snap index 798f63e333738..a039290ccd723 100644 --- a/tasks/website_formatter/src/snapshots/schema_markdown.snap +++ b/tasks/website_formatter/src/snapshots/schema_markdown.snap @@ -121,7 +121,9 @@ Pass an object (`jsdoc: {}`) to enable with defaults, or omit to disable. type: `boolean` +Append default values to `@param` descriptions (e.g. "Default is `value`"). +- Default: `true` ### jsdoc.bracketSpacing @@ -129,7 +131,9 @@ type: `boolean` type: `boolean` +Add spaces inside JSDoc type braces: `{string}` → `{ string }`. +- Default: `false` ### jsdoc.capitalizeDescriptions @@ -137,7 +141,9 @@ type: `boolean` type: `boolean` +Capitalize the first letter of tag descriptions. +- Default: `true` ### jsdoc.commentLineStrategy @@ -145,7 +151,13 @@ type: `boolean` type: `string` +How to format comment blocks. +- `"singleLine"` — Convert to single-line `/** content */` when possible. +- `"multiline"` — Always use multi-line format. +- `"keep"` — Preserve original formatting. + +- Default: `"singleLine"` ### jsdoc.descriptionTag @@ -153,7 +165,9 @@ type: `string` type: `boolean` +Emit `@description` tag instead of inline description. +- Default: `false` ### jsdoc.descriptionWithDot @@ -161,7 +175,9 @@ type: `boolean` type: `boolean` +Add a trailing dot to the end of descriptions. +- Default: `false` ### jsdoc.keepUnparsableExampleIndent @@ -169,7 +185,9 @@ type: `boolean` type: `boolean` +Preserve indentation in unparsable `@example` code. +- Default: `false` ### jsdoc.lineWrappingStyle @@ -177,7 +195,12 @@ type: `boolean` type: `string` +Strategy for wrapping description lines at print width. + +- `"greedy"` — Always re-wrap text to fit within print width. +- `"balance"` — Preserve original line breaks if all lines fit within print width. +- Default: `"greedy"` ### jsdoc.preferCodeFences @@ -185,7 +208,9 @@ type: `string` type: `boolean` +Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag. +- Default: `false` ### jsdoc.separateReturnsFromParam @@ -193,7 +218,9 @@ type: `boolean` type: `boolean` +Add a blank line between the last `@param` and `@returns`. +- Default: `false` ### jsdoc.separateTagGroups @@ -201,7 +228,9 @@ type: `boolean` type: `boolean` +Add blank lines between different tag groups (e.g. between `@param` and `@returns`). +- Default: `false` ## jsxSingleQuote @@ -369,7 +398,9 @@ Pass an object (`jsdoc: {}`) to enable with defaults, or omit to disable. type: `boolean` +Append default values to `@param` descriptions (e.g. "Default is `value`"). +- Default: `true` ###### overrides[n].options.jsdoc.bracketSpacing @@ -377,7 +408,9 @@ type: `boolean` type: `boolean` +Add spaces inside JSDoc type braces: `{string}` → `{ string }`. +- Default: `false` ###### overrides[n].options.jsdoc.capitalizeDescriptions @@ -385,7 +418,9 @@ type: `boolean` type: `boolean` +Capitalize the first letter of tag descriptions. +- Default: `true` ###### overrides[n].options.jsdoc.commentLineStrategy @@ -393,7 +428,13 @@ type: `boolean` type: `string` +How to format comment blocks. +- `"singleLine"` — Convert to single-line `/** content */` when possible. +- `"multiline"` — Always use multi-line format. +- `"keep"` — Preserve original formatting. + +- Default: `"singleLine"` ###### overrides[n].options.jsdoc.descriptionTag @@ -401,7 +442,9 @@ type: `string` type: `boolean` +Emit `@description` tag instead of inline description. +- Default: `false` ###### overrides[n].options.jsdoc.descriptionWithDot @@ -409,7 +452,9 @@ type: `boolean` type: `boolean` +Add a trailing dot to the end of descriptions. +- Default: `false` ###### overrides[n].options.jsdoc.keepUnparsableExampleIndent @@ -417,7 +462,9 @@ type: `boolean` type: `boolean` +Preserve indentation in unparsable `@example` code. +- Default: `false` ###### overrides[n].options.jsdoc.lineWrappingStyle @@ -425,7 +472,12 @@ type: `boolean` type: `string` +Strategy for wrapping description lines at print width. + +- `"greedy"` — Always re-wrap text to fit within print width. +- `"balance"` — Preserve original line breaks if all lines fit within print width. +- Default: `"greedy"` ###### overrides[n].options.jsdoc.preferCodeFences @@ -433,7 +485,9 @@ type: `string` type: `boolean` +Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag. +- Default: `false` ###### overrides[n].options.jsdoc.separateReturnsFromParam @@ -441,7 +495,9 @@ type: `boolean` type: `boolean` +Add a blank line between the last `@param` and `@returns`. +- Default: `false` ###### overrides[n].options.jsdoc.separateTagGroups @@ -449,7 +505,9 @@ type: `boolean` type: `boolean` +Add blank lines between different tag groups (e.g. between `@param` and `@returns`). +- Default: `false` ##### overrides[n].options.jsxSingleQuote