Document BTreeMap lexicographical order

crates/evm/src/executor/inspector/cheatcodes/ext.rs

@@ -210,7 +210,7 @@ fn get_env(key: &str, ty: DynSolType, delim: Option<&str>, default: Option<Strin
 /// Converts a JSON [`Value`] to a [`DynSolValue`].
 ///
 /// The function is designed to run recursively, so that in case of an object
-/// it will call itself to convert each of it's value and encode the whole as a
+/// it will call itself to convert each of its values and encode the whole as a
 /// Tuple
 pub fn value_to_token(value: &Value) -> Result<DynSolValue> {
     match value {
@@ -234,7 +234,7 @@ pub fn value_to_token(value: &Value) -> Result<DynSolValue> {
                 if f.fract() == 0.0 {
                     // Use the string representation of the `serde_json` Number type instead of
                     // calling f.to_string(), because some numbers are wrongly rounded up after
-                    // being convented to f64.
+                    // being converted to f64.
                     // Example: 18446744073709551615 becomes 18446744073709552000 after parsing it
                     // to f64.
                     let s = number.to_string();
@@ -321,9 +321,11 @@ fn parse_json_values(values: Vec<&Value>, key: &str) -> Result<Vec<DynSolValue>>
 }
 
 /// Parses a JSON and returns a single value, an array or an entire JSON object encoded as tuple.
-/// As the JSON object is parsed serially, with the keys ordered alphabetically, they must be
-/// deserialized in the same order. That means that the solidity `struct` should order it's fields
-/// alphabetically and not by efficient packing or some other taxonomy.
+/// As the JSON object is parsed serially, with the keys ordered alphabetically according to the
+/// Rust BTreeMap crate serialization, they must be deserialized in the same order. That means that
+/// the solidity `struct` should order its fields not by efficient packing or some other taxonomy
+/// but instead alphabetically, with attention to upper/lower casing since uppercase precedes
+/// lowercase in BTreeMap lexicographical ordering.
 fn parse_json(json_str: &str, key: &str, coerce: Option<DynSolType>) -> Result {
     trace!(%json_str, %key, ?coerce, "parsing json");
     let json =
@@ -412,7 +414,8 @@ fn parse_json_keys(json_str: &str, key: &str) -> Result {
 /// a new object in itself. The function will return a stringified version of the object, so that
 /// the user can use that as a value to a new invocation of the same function with a new object key.
 /// This enables the user to reuse the same function to crate arbitrarily complex object structures
-/// (JSON).
+/// (JSON). Note that the `BTreeMap` is used to serialize in lexicographical order, meaning
+/// uppercase precedes lowercase. More: <https://doc.rust-lang.org/std/collections/struct.BTreeMap.html>
 fn serialize_json(
     state: &mut Cheatcodes,
     object_key: &str,
@@ -445,8 +448,8 @@ fn serialize_json(
     Ok(DynSolValue::String(stringified).abi_encode().into())
 }
 
-/// Converts an array to it's stringified version, adding the appropriate quotes around it's
-/// ellements. This is to signify that the elements of the array are string themselves.
+/// Converts an array to its stringified version, adding the appropriate quotes around its
+/// elements. This is to signify that the elements of the array are strings themselves.
 fn array_str_to_str<T: UIfmt>(array: &Vec<T>) -> String {
     format!(
         "[{}]",
@@ -464,7 +467,7 @@ fn array_str_to_str<T: UIfmt>(array: &Vec<T>) -> String {
     )
 }
 
-/// Converts an array to it's stringified version. It will not add quotes around the values of the
+/// Converts an array to its stringified version. It will not add quotes around the values of the
 /// array, enabling serde_json to parse the values of the array as types (e.g numbers, booleans,
 /// etc.)
 fn array_eval_to_str<T: UIfmt>(array: &Vec<T>) -> String {