Skip to content

Commit 416865a

Browse files
leaysgurleaysgur
committed
feat(formatter,oxfmt): Add doc comments for JsdocConfig (#20644)
Follow up #19828
1 parent 47c56b6 commit 416865a

5 files changed

Lines changed: 257 additions & 59 deletions

File tree

‎apps/oxfmt/src-js/config.generated.ts‎

Lines changed: 62 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -216,20 +216,79 @@ export interface Oxfmtrc {
216216
vueIndentScriptAndStyle?: boolean;
217217
[k: string]: unknown;
218218
}
219-
/**
220-
* JSDoc configuration object with fine-grained options.
221-
*/
222219
export interface JsdocConfig {
220+
/**
221+
* Append default values to `@param` descriptions (e.g. "Default is `value`").
222+
*
223+
* - Default: `true`
224+
*/
223225
addDefaultToDescription?: boolean;
226+
/**
227+
* Add spaces inside JSDoc type braces: `{string}` → `{ string }`.
228+
*
229+
* - Default: `false`
230+
*/
224231
bracketSpacing?: boolean;
232+
/**
233+
* Capitalize the first letter of tag descriptions.
234+
*
235+
* - Default: `true`
236+
*/
225237
capitalizeDescriptions?: boolean;
238+
/**
239+
* How to format comment blocks.
240+
*
241+
* - `"singleLine"` — Convert to single-line `/** content * /` when possible.
242+
* - `"multiline"` — Always use multi-line format.
243+
* - `"keep"` — Preserve original formatting.
244+
*
245+
* - Default: `"singleLine"`
246+
*/
226247
commentLineStrategy?: string;
248+
/**
249+
* Emit `@description` tag instead of inline description.
250+
*
251+
* - Default: `false`
252+
*/
227253
descriptionTag?: boolean;
254+
/**
255+
* Add a trailing dot to the end of descriptions.
256+
*
257+
* - Default: `false`
258+
*/
228259
descriptionWithDot?: boolean;
260+
/**
261+
* Preserve indentation in unparsable `@example` code.
262+
*
263+
* - Default: `false`
264+
*/
229265
keepUnparsableExampleIndent?: boolean;
266+
/**
267+
* Strategy for wrapping description lines at print width.
268+
*
269+
* - `"greedy"` — Always re-wrap text to fit within print width.
270+
* - `"balance"` — Preserve original line breaks if all lines fit within print width.
271+
*
272+
* - Default: `"greedy"`
273+
*/
230274
lineWrappingStyle?: string;
275+
/**
276+
* Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag.
277+
*
278+
* - Default: `false`
279+
*/
231280
preferCodeFences?: boolean;
281+
/**
282+
* Add a blank line between the last `@param` and `@returns`.
283+
*
284+
* - Default: `false`
285+
*/
232286
separateReturnsFromParam?: boolean;
287+
/**
288+
* Add blank lines between different tag groups (e.g. between `@param` and `@returns`).
289+
*
290+
* - Default: `false`
291+
*/
233292
separateTagGroups?: boolean;
234293
[k: string]: unknown;
235294
}

‎apps/oxfmt/src/core/oxfmtrc/format_config.rs‎

Lines changed: 69 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -237,34 +237,6 @@ pub struct FormatConfig {
237237
pub jsdoc: Option<JsdocConfig>,
238238
}
239239

240-
/// JSDoc configuration object with fine-grained options.
241-
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
242-
#[serde(rename_all = "camelCase")]
243-
pub struct JsdocConfig {
244-
#[serde(skip_serializing_if = "Option::is_none")]
245-
pub capitalize_descriptions: Option<bool>,
246-
#[serde(skip_serializing_if = "Option::is_none")]
247-
pub description_with_dot: Option<bool>,
248-
#[serde(skip_serializing_if = "Option::is_none")]
249-
pub add_default_to_description: Option<bool>,
250-
#[serde(skip_serializing_if = "Option::is_none")]
251-
pub prefer_code_fences: Option<bool>,
252-
#[serde(skip_serializing_if = "Option::is_none")]
253-
pub line_wrapping_style: Option<String>,
254-
#[serde(skip_serializing_if = "Option::is_none")]
255-
pub comment_line_strategy: Option<String>,
256-
#[serde(skip_serializing_if = "Option::is_none")]
257-
pub separate_tag_groups: Option<bool>,
258-
#[serde(skip_serializing_if = "Option::is_none")]
259-
pub separate_returns_from_param: Option<bool>,
260-
#[serde(skip_serializing_if = "Option::is_none")]
261-
pub bracket_spacing: Option<bool>,
262-
#[serde(skip_serializing_if = "Option::is_none")]
263-
pub description_tag: Option<bool>,
264-
#[serde(skip_serializing_if = "Option::is_none")]
265-
pub keep_unparsable_example_indent: Option<bool>,
266-
}
267-
268240
impl FormatConfig {
269241
/// Resolve relative tailwind paths (`config`, `stylesheet`) to absolute paths.
270242
/// Otherwise, the plugin tries to resolve the Prettier's configuration file, not Oxfmt's.
@@ -656,6 +628,75 @@ pub struct SortTailwindcssConfig {
656628

657629
// ---
658630

631+
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
632+
#[serde(rename_all = "camelCase")]
633+
pub struct JsdocConfig {
634+
/// Capitalize the first letter of tag descriptions.
635+
///
636+
/// - Default: `true`
637+
#[serde(skip_serializing_if = "Option::is_none")]
638+
pub capitalize_descriptions: Option<bool>,
639+
/// Add a trailing dot to the end of descriptions.
640+
///
641+
/// - Default: `false`
642+
#[serde(skip_serializing_if = "Option::is_none")]
643+
pub description_with_dot: Option<bool>,
644+
/// Append default values to `@param` descriptions (e.g. "Default is `value`").
645+
///
646+
/// - Default: `true`
647+
#[serde(skip_serializing_if = "Option::is_none")]
648+
pub add_default_to_description: Option<bool>,
649+
/// Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag.
650+
///
651+
/// - Default: `false`
652+
#[serde(skip_serializing_if = "Option::is_none")]
653+
pub prefer_code_fences: Option<bool>,
654+
/// Strategy for wrapping description lines at print width.
655+
///
656+
/// - `"greedy"` — Always re-wrap text to fit within print width.
657+
/// - `"balance"` — Preserve original line breaks if all lines fit within print width.
658+
///
659+
/// - Default: `"greedy"`
660+
#[serde(skip_serializing_if = "Option::is_none")]
661+
pub line_wrapping_style: Option<String>,
662+
/// How to format comment blocks.
663+
///
664+
/// - `"singleLine"` — Convert to single-line `/** content */` when possible.
665+
/// - `"multiline"` — Always use multi-line format.
666+
/// - `"keep"` — Preserve original formatting.
667+
///
668+
/// - Default: `"singleLine"`
669+
#[serde(skip_serializing_if = "Option::is_none")]
670+
pub comment_line_strategy: Option<String>,
671+
/// Add blank lines between different tag groups (e.g. between `@param` and `@returns`).
672+
///
673+
/// - Default: `false`
674+
#[serde(skip_serializing_if = "Option::is_none")]
675+
pub separate_tag_groups: Option<bool>,
676+
/// Add a blank line between the last `@param` and `@returns`.
677+
///
678+
/// - Default: `false`
679+
#[serde(skip_serializing_if = "Option::is_none")]
680+
pub separate_returns_from_param: Option<bool>,
681+
/// Add spaces inside JSDoc type braces: `{string}` → `{ string }`.
682+
///
683+
/// - Default: `false`
684+
#[serde(skip_serializing_if = "Option::is_none")]
685+
pub bracket_spacing: Option<bool>,
686+
/// Emit `@description` tag instead of inline description.
687+
///
688+
/// - Default: `false`
689+
#[serde(skip_serializing_if = "Option::is_none")]
690+
pub description_tag: Option<bool>,
691+
/// Preserve indentation in unparsable `@example` code.
692+
///
693+
/// - Default: `false`
694+
#[serde(skip_serializing_if = "Option::is_none")]
695+
pub keep_unparsable_example_indent: Option<bool>,
696+
}
697+
698+
// ---
699+
659700
/// Merge two JSON values recursively.
660701
/// - Overlay values overwrite base values
661702
/// - `null` values in overlay reset the field to default (via `Option<T>` → `None`)

‎npm/oxfmt/configuration_schema.json‎

Lines changed: 34 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -427,44 +427,64 @@
427427
]
428428
},
429429
"JsdocConfig": {
430-
"description": "JSDoc configuration object with fine-grained options.",
431430
"type": "object",
432431
"properties": {
433432
"addDefaultToDescription": {
434-
"type": "boolean"
433+
"description": "Append default values to `@param` descriptions (e.g. \"Default is `value`\").\n\n- Default: `true`",
434+
"type": "boolean",
435+
"markdownDescription": "Append default values to `@param` descriptions (e.g. \"Default is `value`\").\n\n- Default: `true`"
435436
},
436437
"bracketSpacing": {
437-
"type": "boolean"
438+
"description": "Add spaces inside JSDoc type braces: `{string}` → `{ string }`.\n\n- Default: `false`",
439+
"type": "boolean",
440+
"markdownDescription": "Add spaces inside JSDoc type braces: `{string}` → `{ string }`.\n\n- Default: `false`"
438441
},
439442
"capitalizeDescriptions": {
440-
"type": "boolean"
443+
"description": "Capitalize the first letter of tag descriptions.\n\n- Default: `true`",
444+
"type": "boolean",
445+
"markdownDescription": "Capitalize the first letter of tag descriptions.\n\n- Default: `true`"
441446
},
442447
"commentLineStrategy": {
443-
"type": "string"
448+
"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\"`",
449+
"type": "string",
450+
"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\"`"
444451
},
445452
"descriptionTag": {
446-
"type": "boolean"
453+
"description": "Emit `@description` tag instead of inline description.\n\n- Default: `false`",
454+
"type": "boolean",
455+
"markdownDescription": "Emit `@description` tag instead of inline description.\n\n- Default: `false`"
447456
},
448457
"descriptionWithDot": {
449-
"type": "boolean"
458+
"description": "Add a trailing dot to the end of descriptions.\n\n- Default: `false`",
459+
"type": "boolean",
460+
"markdownDescription": "Add a trailing dot to the end of descriptions.\n\n- Default: `false`"
450461
},
451462
"keepUnparsableExampleIndent": {
452-
"type": "boolean"
463+
"description": "Preserve indentation in unparsable `@example` code.\n\n- Default: `false`",
464+
"type": "boolean",
465+
"markdownDescription": "Preserve indentation in unparsable `@example` code.\n\n- Default: `false`"
453466
},
454467
"lineWrappingStyle": {
455-
"type": "string"
468+
"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\"`",
469+
"type": "string",
470+
"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\"`"
456471
},
457472
"preferCodeFences": {
458-
"type": "boolean"
473+
"description": "Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag.\n\n- Default: `false`",
474+
"type": "boolean",
475+
"markdownDescription": "Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag.\n\n- Default: `false`"
459476
},
460477
"separateReturnsFromParam": {
461-
"type": "boolean"
478+
"description": "Add a blank line between the last `@param` and `@returns`.\n\n- Default: `false`",
479+
"type": "boolean",
480+
"markdownDescription": "Add a blank line between the last `@param` and `@returns`.\n\n- Default: `false`"
462481
},
463482
"separateTagGroups": {
464-
"type": "boolean"
483+
"description": "Add blank lines between different tag groups (e.g. between `@param` and `@returns`).\n\n- Default: `false`",
484+
"type": "boolean",
485+
"markdownDescription": "Add blank lines between different tag groups (e.g. between `@param` and `@returns`).\n\n- Default: `false`"
465486
}
466-
},
467-
"markdownDescription": "JSDoc configuration object with fine-grained options."
487+
}
468488
},
469489
"NewlinesBetweenMarker": {
470490
"description": "A marker object for overriding `newlinesBetween` at a specific group boundary.",

‎tasks/website_formatter/src/snapshots/schema_json.snap‎

Lines changed: 34 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -431,44 +431,64 @@ expression: json
431431
]
432432
},
433433
"JsdocConfig": {
434-
"description": "JSDoc configuration object with fine-grained options.",
435434
"type": "object",
436435
"properties": {
437436
"addDefaultToDescription": {
438-
"type": "boolean"
437+
"description": "Append default values to `@param` descriptions (e.g. \"Default is `value`\").\n\n- Default: `true`",
438+
"type": "boolean",
439+
"markdownDescription": "Append default values to `@param` descriptions (e.g. \"Default is `value`\").\n\n- Default: `true`"
439440
},
440441
"bracketSpacing": {
441-
"type": "boolean"
442+
"description": "Add spaces inside JSDoc type braces: `{string}` → `{ string }`.\n\n- Default: `false`",
443+
"type": "boolean",
444+
"markdownDescription": "Add spaces inside JSDoc type braces: `{string}` → `{ string }`.\n\n- Default: `false`"
442445
},
443446
"capitalizeDescriptions": {
444-
"type": "boolean"
447+
"description": "Capitalize the first letter of tag descriptions.\n\n- Default: `true`",
448+
"type": "boolean",
449+
"markdownDescription": "Capitalize the first letter of tag descriptions.\n\n- Default: `true`"
445450
},
446451
"commentLineStrategy": {
447-
"type": "string"
452+
"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\"`",
453+
"type": "string",
454+
"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\"`"
448455
},
449456
"descriptionTag": {
450-
"type": "boolean"
457+
"description": "Emit `@description` tag instead of inline description.\n\n- Default: `false`",
458+
"type": "boolean",
459+
"markdownDescription": "Emit `@description` tag instead of inline description.\n\n- Default: `false`"
451460
},
452461
"descriptionWithDot": {
453-
"type": "boolean"
462+
"description": "Add a trailing dot to the end of descriptions.\n\n- Default: `false`",
463+
"type": "boolean",
464+
"markdownDescription": "Add a trailing dot to the end of descriptions.\n\n- Default: `false`"
454465
},
455466
"keepUnparsableExampleIndent": {
456-
"type": "boolean"
467+
"description": "Preserve indentation in unparsable `@example` code.\n\n- Default: `false`",
468+
"type": "boolean",
469+
"markdownDescription": "Preserve indentation in unparsable `@example` code.\n\n- Default: `false`"
457470
},
458471
"lineWrappingStyle": {
459-
"type": "string"
472+
"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\"`",
473+
"type": "string",
474+
"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\"`"
460475
},
461476
"preferCodeFences": {
462-
"type": "boolean"
477+
"description": "Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag.\n\n- Default: `false`",
478+
"type": "boolean",
479+
"markdownDescription": "Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag.\n\n- Default: `false`"
463480
},
464481
"separateReturnsFromParam": {
465-
"type": "boolean"
482+
"description": "Add a blank line between the last `@param` and `@returns`.\n\n- Default: `false`",
483+
"type": "boolean",
484+
"markdownDescription": "Add a blank line between the last `@param` and `@returns`.\n\n- Default: `false`"
466485
},
467486
"separateTagGroups": {
468-
"type": "boolean"
487+
"description": "Add blank lines between different tag groups (e.g. between `@param` and `@returns`).\n\n- Default: `false`",
488+
"type": "boolean",
489+
"markdownDescription": "Add blank lines between different tag groups (e.g. between `@param` and `@returns`).\n\n- Default: `false`"
469490
}
470-
},
471-
"markdownDescription": "JSDoc configuration object with fine-grained options."
491+
}
472492
},
473493
"NewlinesBetweenMarker": {
474494
"description": "A marker object for overriding `newlinesBetween` at a specific group boundary.",

0 commit comments

Comments
 (0)