docs: safety of useSortedKeys (#6112)

Co-authored-by: Emanuele Stoppa <my.burning@gmail.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Co-authored-by: dyc3 <1808807+dyc3@users.noreply.github.com>

Author: Sjlver

crates/biome_configuration/src/analyzer/assist/actions.rs

@@ -47,7 +47,7 @@ pub enum RuleDomainValue {
     All,
     /// Disables all the rules that belong to this domain
     None,
-    /// It enables only the recommended rules for this domain
+    /// Enables only the recommended rules for this domain
     Recommended,
 }
 

crates/biome_configuration/src/analyzer/linter/mod.rs

@@ -18,16 +18,28 @@ use biome_string_case::comparable_token::ComparableToken;
 use crate::JsRuleAction;
 
 declare_source_rule! {
-    /// Enforce ordering of a JS object properties.
-    ///
-    /// This rule checks if keys of the object are sorted in a consistent way.
-    /// Keys are sorted in a [natural sort order](https://en.wikipedia.org/wiki/Natural_sort_order).
-    /// This rule will consider spread/calculated keys e.g [k]: 1 as non-sortable.
-    /// Instead, whenever it encounters a non-sortable key, it will sort all the
-    /// previous sortable keys up until the nearest non-sortable key, if one
-    /// exist.
-    /// This prevents breaking the override of certain keys using spread
-    /// keys.
+    /// Sort properties of a JS object in natural order.
+    ///
+    /// [Natural order](https://en.wikipedia.org/wiki/Natural_sort_order) means
+    /// that uppercase letters come before lowercase letters (e.g. `A` < `a` <
+    /// `B` < `b`) and numbers are compared in a human way (e.g. `9` < `10`).
+    ///
+    /// This rule will consider spread/calculated keys e.g [k]: 1 as
+    /// non-sortable. Instead, whenever it encounters a non-sortable key, it
+    /// will sort all the previous sortable keys up until the nearest
+    /// non-sortable key, if one exist. This prevents breaking the override of
+    /// certain keys using spread keys.
+    ///
+    /// Sorting the keys of an object technically changes the semantics of the
+    /// program. It affects the result of operations like
+    /// `Object.getOwnPropertyNames`. Since ES2020, operations like `for-in`
+    /// loops, `Object.keys`, and `JSON.stringify` are guaranteed to process
+    /// string keys in insertion order.
+    ///
+    /// In cases where the order of such operations is important, you can
+    /// disable the assist action using a suppression comment:
+    ///
+    /// `// biome-ignore assist/source/useSortedKeys`
     ///
     /// ## Examples
     ///

crates/biome_configuration/src/analyzer/linter/rules.rs

@@ -13,7 +13,11 @@ use biome_string_case::comparable_token::ComparableToken;
 use std::ops::Not;
 
 declare_source_rule! {
-    /// Sorts the keys of a JSON object in natural order
+    /// Sort the keys of a JSON object in natural order.
+    ///
+    /// [Natural order](https://en.wikipedia.org/wiki/Natural_sort_order) means
+    /// that uppercase letters come before lowercase letters (e.g. `A` < `a` <
+    /// `B` < `b`) and numbers are compared in a human way (e.g. `9` < `10`).
     ///
     /// ## Examples
     ///

crates/biome_js_analyze/src/assist/source/use_sorted_keys.rs

@@ -937,7 +937,7 @@ fn generate_group_struct(
             #[serde(rename_all = "camelCase", default, deny_unknown_fields)]
             /// A list of rules that belong to this group
             pub struct #group_pascal_ident {
-                /// It enables the recommended rules for this group
+                /// Enables the recommended rules for this group
                 #[serde(skip_serializing_if = "Option::is_none")]
                 pub recommended: Option<bool>,
 
@@ -1010,7 +1010,7 @@ fn generate_group_struct(
             #[serde(rename_all = "camelCase", default, deny_unknown_fields)]
             /// A list of rules that belong to this group
             pub struct #group_pascal_ident {
-                /// It enables the recommended rules for this group
+                /// Enables the recommended rules for this group
                 #[serde(skip_serializing_if = "Option::is_none")]
                 pub recommended: Option<bool>,