Skip to content

feat(formatter,oxfmt): Add doc comments for JsdocConfig #20644

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
graphite-app merged 1 commit into from
Mar 23, 2026
+257 −59
Merged

feat(formatter,oxfmt): Add doc comments for JsdocConfig #20644

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 62 additions & 3 deletions apps/oxfmt/src-js/config.generated.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
Expand Down
97 changes: 69 additions & 28 deletions apps/oxfmt/src/core/oxfmtrc/format_config.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -237,34 +237,6 @@ pub struct FormatConfig {
pub jsdoc: Option<JsdocConfig>,
}

/// 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<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub description_with_dot: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub add_default_to_description: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub prefer_code_fences: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub line_wrapping_style: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub comment_line_strategy: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub separate_tag_groups: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub separate_returns_from_param: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub bracket_spacing: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub description_tag: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub keep_unparsable_example_indent: Option<bool>,
}

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.
Expand Down Expand Up @@ -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<bool>,
/// Add a trailing dot to the end of descriptions.
///
/// - Default: `false`
#[serde(skip_serializing_if = "Option::is_none")]
pub description_with_dot: Option<bool>,
/// 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<bool>,
/// 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<bool>,
/// 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<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"`
#[serde(skip_serializing_if = "Option::is_none")]
pub comment_line_strategy: Option<String>,
/// 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<bool>,
/// 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<bool>,
/// Add spaces inside JSDoc type braces: `{string}` → `{ string }`.
///
/// - Default: `false`
#[serde(skip_serializing_if = "Option::is_none")]
pub bracket_spacing: Option<bool>,
/// Emit `@description` tag instead of inline description.
///
/// - Default: `false`
#[serde(skip_serializing_if = "Option::is_none")]
pub description_tag: Option<bool>,
/// Preserve indentation in unparsable `@example` code.
///
/// - Default: `false`
#[serde(skip_serializing_if = "Option::is_none")]
pub keep_unparsable_example_indent: Option<bool>,
}

// ---

/// Merge two JSON values recursively.
/// - Overlay values overwrite base values
/// - `null` values in overlay reset the field to default (via `Option<T>` → `None`)
Expand Down
48 changes: 34 additions & 14 deletions npm/oxfmt/configuration_schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.",
Expand Down
48 changes: 34 additions & 14 deletions tasks/website_formatter/src/snapshots/schema_json.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.",
Expand Down
Loading
Loading