docs(oxfmt): Add markdownDescription fields and unify the schema generation process.

With this change, the descriptions for each field in the JSON schema are rendered with proper markdown formatting in VS Code and other editors based on VS Code.

This now matches the implementation for the Oxlintrc schema generation.

Author: connorshea

crates/oxc_formatter/src/service/oxfmtrc.rs

@@ -1,6 +1,6 @@
 use std::path::Path;
 
-use schemars::JsonSchema;
+use schemars::{JsonSchema, schema_for};
 use serde::{Deserialize, Deserializer, Serialize};
 use serde_json::Value;
 
@@ -532,6 +532,60 @@ impl Oxfmtrc {
         // e.g. `plugins`, `htmlWhitespaceSensitivity`, `vueIndentScriptAndStyle`, etc.
         // Other options defined independently by plugins are also left as they are.
     }
+
+    /// Generates the JSON schema for Oxfmtrc configuration files.
+    ///
+    /// # Panics
+    /// Panics if the schema generation fails.
+    pub fn generate_schema_json() -> String {
+        let mut schema = schema_for!(Oxfmtrc);
+
+        // Allow comments and trailing commas for vscode-json-languageservice
+        // NOTE: This is NOT part of standard JSON Schema specification
+        // https://github.com/microsoft/vscode-json-languageservice/blob/fb83547762901f32d8449d57e24666573016b10c/src/jsonLanguageTypes.ts#L151-L159
+        schema.schema.extensions.insert("allowComments".to_string(), serde_json::Value::Bool(true));
+        schema
+            .schema
+            .extensions
+            .insert("allowTrailingCommas".to_string(), serde_json::Value::Bool(true));
+
+        // Inject markdownDescription fields for better editor support (e.g., VS Code)
+        let mut json = serde_json::to_value(&schema).unwrap();
+        Self::inject_markdown_descriptions(&mut json);
+
+        serde_json::to_string_pretty(&json).unwrap()
+    }
+
+    /// Recursively inject `markdownDescription` fields into the JSON schema.
+    /// This is a non-standard field that some editors (like VS Code) use to render
+    /// markdown in hover tooltips.
+    fn inject_markdown_descriptions(value: &mut serde_json::Value) {
+        match value {
+            serde_json::Value::Object(map) => {
+                // If this object has a `description` field, copy it to `markdownDescription`
+                if let Some(serde_json::Value::String(desc_str)) = map.get("description") {
+                    map.insert(
+                        "markdownDescription".to_string(),
+                        serde_json::Value::String(desc_str.clone()),
+                    );
+                }
+
+                // Recursively process all values in the object
+                for value in map.values_mut() {
+                    Self::inject_markdown_descriptions(value);
+                }
+            }
+            serde_json::Value::Array(items) => {
+                // Recursively process all items in the array
+                for item in items {
+                    Self::inject_markdown_descriptions(item);
+                }
+            }
+            _ => {
+                // Primitive values don't need processing
+            }
+        }
+    }
 }
 
 // ---

crates/oxc_formatter/tests/schema.rs

@@ -8,16 +8,7 @@ use project_root::get_project_root;
 #[test]
 fn test_schema_json() {
     let path = get_project_root().unwrap().join("npm/oxfmt/configuration_schema.json");
-    let mut schema = schemars::schema_for!(Oxfmtrc);
-    // Allow comments and trailing commas for vscode-json-languageservice
-    // NOTE: This is NOT part of standard JSON Schema specification
-    // https://github.com/microsoft/vscode-json-languageservice/blob/fb83547762901f32d8449d57e24666573016b10c/src/jsonLanguageTypes.ts#L151-L159
-    schema.schema.extensions.insert("allowComments".to_string(), serde_json::Value::Bool(true));
-    schema
-        .schema
-        .extensions
-        .insert("allowTrailingCommas".to_string(), serde_json::Value::Bool(true));
-    let json = serde_json::to_string_pretty(&schema).unwrap();
+    let json = Oxfmtrc::generate_schema_json();
     let existing_json = fs::read_to_string(&path).unwrap_or_default();
     if existing_json.trim() != json.trim() {
         std::fs::write(&path, &json).unwrap();

crates/oxc_formatter/tests/snapshots/schema_json.snap

@@ -17,21 +17,24 @@ expression: json
         {
           "type": "null"
         }
-      ]
+      ],
+      "markdownDescription": "Include parentheses around a sole arrow function parameter. (Default: `\"always\"`)"
     },
     "bracketSameLine": {
       "description": "Put the `>` of a multi-line JSX element at the end of the last line\ninstead of being alone on the next line. (Default: `false`)",
       "type": [
         "boolean",
         "null"
-      ]
+      ],
+      "markdownDescription": "Put the `>` of a multi-line JSX element at the end of the last line\ninstead of being alone on the next line. (Default: `false`)"
     },
     "bracketSpacing": {
       "description": "Print spaces between brackets in object literals. (Default: `true`)",
       "type": [
         "boolean",
         "null"
-      ]
+      ],
+      "markdownDescription": "Print spaces between brackets in object literals. (Default: `true`)"
     },
     "embeddedLanguageFormatting": {
       "description": "Control whether formats quoted code embedded in the file. (Default: `\"auto\"`)",
@@ -42,7 +45,8 @@ expression: json
         {
           "type": "null"
         }
-      ]
+      ],
+      "markdownDescription": "Control whether formats quoted code embedded in the file. (Default: `\"auto\"`)"
     },
     "endOfLine": {
       "description": "Which end of line characters to apply. (Default: `\"lf\"`)",
@@ -53,7 +57,8 @@ expression: json
         {
           "type": "null"
         }
-      ]
+      ],
+      "markdownDescription": "Which end of line characters to apply. (Default: `\"lf\"`)"
     },
     "experimentalSortImports": {
       "description": "Experimental: Sort import statements. Disabled by default.",
@@ -64,7 +69,8 @@ expression: json
         {
           "type": "null"
         }
-      ]
+      ],
+      "markdownDescription": "Experimental: Sort import statements. Disabled by default."
     },
     "experimentalSortPackageJson": {
       "description": "Experimental: Sort `package.json` keys. (Default: true)",
@@ -79,14 +85,16 @@ expression: json
       ],
       "items": {
         "type": "string"
-      }
+      },
+      "markdownDescription": "Ignore files matching these glob patterns. Current working directory is used as the root."
     },
     "jsxSingleQuote": {
       "description": "Use single quotes instead of double quotes in JSX. (Default: `false`)",
       "type": [
         "boolean",
         "null"
-      ]
+      ],
+      "markdownDescription": "Use single quotes instead of double quotes in JSX. (Default: `false`)"
     },
     "objectWrap": {
       "description": "How to wrap object literals when they could fit on one line or span multiple lines. (Default: `\"preserve\"`)\nNOTE: In addition to Prettier's `\"preserve\"` and `\"collapse\"`, we also support `\"always\"`.",
@@ -97,7 +105,8 @@ expression: json
         {
           "type": "null"
         }
-      ]
+      ],
+      "markdownDescription": "How to wrap object literals when they could fit on one line or span multiple lines. (Default: `\"preserve\"`)\nNOTE: In addition to Prettier's `\"preserve\"` and `\"collapse\"`, we also support `\"always\"`."
     },
     "printWidth": {
       "description": "The line length that the printer will wrap on. (Default: `100`)",
@@ -106,7 +115,8 @@ expression: json
         "null"
       ],
       "format": "uint16",
-      "minimum": 0.0
+      "minimum": 0.0,
+      "markdownDescription": "The line length that the printer will wrap on. (Default: `100`)"
     },
     "quoteProps": {
       "description": "Change when properties in objects are quoted. (Default: `\"as-needed\"`)",
@@ -117,28 +127,32 @@ expression: json
         {
           "type": "null"
         }
-      ]
+      ],
+      "markdownDescription": "Change when properties in objects are quoted. (Default: `\"as-needed\"`)"
     },
     "semi": {
       "description": "Print semicolons at the ends of statements. (Default: `true`)",
       "type": [
         "boolean",
         "null"
-      ]
+      ],
+      "markdownDescription": "Print semicolons at the ends of statements. (Default: `true`)"
     },
     "singleAttributePerLine": {
       "description": "Put each attribute on a new line in JSX. (Default: `false`)",
       "type": [
         "boolean",
         "null"
-      ]
+      ],
+      "markdownDescription": "Put each attribute on a new line in JSX. (Default: `false`)"
     },
     "singleQuote": {
       "description": "Use single quotes instead of double quotes. (Default: `false`)",
       "type": [
         "boolean",
         "null"
-      ]
+      ],
+      "markdownDescription": "Use single quotes instead of double quotes. (Default: `false`)"
     },
     "tabWidth": {
       "description": "Number of spaces per indentation level. (Default: `2`)",
@@ -147,7 +161,8 @@ expression: json
         "null"
       ],
       "format": "uint8",
-      "minimum": 0.0
+      "minimum": 0.0,
+      "markdownDescription": "Number of spaces per indentation level. (Default: `2`)"
     },
     "trailingComma": {
       "description": "Print trailing commas wherever possible. (Default: `\"all\"`)",
@@ -158,14 +173,16 @@ expression: json
         {
           "type": "null"
         }
-      ]
+      ],
+      "markdownDescription": "Print trailing commas wherever possible. (Default: `\"all\"`)"
     },
     "useTabs": {
       "description": "Use tabs for indentation or spaces. (Default: `false`)",
       "type": [
         "boolean",
         "null"
-      ]
+      ],
+      "markdownDescription": "Use tabs for indentation or spaces. (Default: `false`)"
     }
   },
   "allowComments": true,
@@ -222,7 +239,8 @@ expression: json
             "items": {
               "type": "string"
             }
-          }
+          },
+          "markdownDescription": "Custom groups configuration for organizing imports.\nEach array element represents a group, and multiple group names in the same array are treated as one.\nAccepts both `string` and `string[]` as group elements."
         },
         "ignoreCase": {
           "default": true,
@@ -280,5 +298,6 @@ expression: json
         "none"
       ]
     }
-  }
+  },
+  "markdownDescription": "Configuration options for the formatter.\nMost options are the same as Prettier's options.\nSee also <https://prettier.io/docs/options>"
 }