inline documentation

Author: jialinli98

README.md

@@ -97,88 +97,6 @@ fn process_schema(text: [u8; NUM_BYTES])
   - Functions taking `key: [u8; KeyBytes]` expect a fixed-length key known at compile time.
   - Functions with `_var` take `key: BoundedVec<u8, KeyBytes>` for variable-length keys up to `KeyBytes`.
 
-### Object getters API
-
-- **`get_object<let KeyBytes>(key: [u8; KeyBytes])` → `Option<JSON>`**: From an object root, returns `Some(JSON)` if `key` exists and is an object, `None` if `key` is missing; errors if `key` exists but is not an object, or if called when the current root is an array.
-
-- **`get_object_unchecked<let KeyBytes>(key: [u8; KeyBytes])` → `JSON`**: From an object root, returns the object at `key`; errors otherwise.
-
-- **`get_object_var<let KeyBytes>(key: BoundedVec<u8, KeyBytes>)` → `Option<JSON>`**: Same as `get_object`, but the key can be variable-length up to `KeyBytes`.
-
-- **`get_object_unchecked_var<let KeyBytes>(key: BoundedVec<u8, KeyBytes>)` → `JSON`**: Same as `get_object_unchecked`, but with a variable-length key.
-
-- **`get_object_from_array(index: Field)` → `Option<JSON>`**: When the current root is an array, returns the object at `index` wrapped in `Option`. Returns `None` if `index` is out of bounds; errors if in-bounds but the element is not an object.
-
-- **`get_object_from_array_unchecked(index: Field)` → `JSON`**: When the current root is an array, returns the object at `index`. Errors if `index` is out of bounds or the element is not an object.
-
-### Array getters API
-
-- **`get_length()` → `u32`**: Returns its length when the current root is an array; errors otherwise.
-
-- **`get_array<let KeyBytes>(key: [u8; KeyBytes])` → `Option<JSON>`**: From an object root, returns Some(JSON) if key exists and is an array, None if key is missing; errors if key exists but is not an array, or if called when the current root is an array.
-
-- **`get_array_unchecked<let KeyBytes>(key: [u8; KeyBytes])` → `JSON`**: From an object root, returns the array at key; errors otherwise.
-
-- **`get_array_var<let KeyBytes>(key: BoundedVec<u8, KeyBytes>)` → `Option<JSON>`**: Same as `get_array`, but the key can be variable-length up to `KeyBytes`.
-
-- **`get_array_unchecked_var<let KeyBytes>(key: BoundedVec<u8, KeyBytes>)` → `JSON`**: Same as `get_array_unchecked`, but with a variable-length key.
-
-- **`get_array_from_array(index: Field)` → `Option<JSON>`**: When the current root is an array, returns the nested array at `index` wrapped in `Option`. Returns `None` if `index` is out of bounds; errors if in-bounds but the element is not an array.
-
-- **`get_array_from_array_unchecked(index: Field)` → `JSON`**: When the current root is an array, returns the nested array at `index`. Errors if `index` is out of bounds or the element is not an array.
-
-### Literal getters API
-
-Literals are the JSON keywords `true`, `false`, and `null`. They are represented by `JSONLiteral`, which supports:
-- `is_true()`, `is_false()`, `is_null()`
-- `to_bool()` (maps `true` → `true`, `false`/`null` → `false`)
-
-- **`get_literal<let KeyBytes>(key: [u8; KeyBytes])` → `Option<JSONLiteral>`**: From an object root, returns `Some(JSONLiteral)` if `key` exists and is a literal; `None` if `key` is missing; errors if `key` exists but is not a literal, or if called when the current root is an array.
-
-- **`get_literal_unchecked<let KeyBytes>(key: [u8; KeyBytes])` → `JSONLiteral`**: From an object root, returns the literal at `key`; errors if the key is missing, not a literal, or if called when the current root is an array.
-
-- **`get_literal_var<let KeyBytes>(key: BoundedVec<u8, KeyBytes>)` → `Option<JSONLiteral>`**: Same as `get_literal`, but accepts a variable-length key up to `KeyBytes`.
-
-- **`get_literal_unchecked_var<let KeyBytes>(key: BoundedVec<u8, KeyBytes>)` → `JSONLiteral`**: Same as `get_literal_unchecked`, with a variable-length key.
-
-- **`get_literal_from_array(index: Field)` → `Option<JSONLiteral>`**: When the current root is an array, returns the literal at `index` wrapped in `Option`. Returns `None` if `index` is out of bounds; errors if in-bounds but the element at `index` is not a literal.
-
-- **`get_literal_from_array_unchecked(index: Field)` → `JSONLiteral`**: When the current root is an array, returns the literal at `index`; errors if `index` is out of bounds or the element is not a literal.
-
-### Number getters API
-
-Numbers are parsed as unsigned integers and must fit into `u64` (no decimals).
-
-- **`get_number<let KeyBytes>(key: [u8; KeyBytes])` → `Option<u64>`**: From an object root, returns `Some(u64)` if `key` exists and is a number; `None` if `key` is missing; errors if `key` exists but is not a number, or if called when the current root is an array.
-
-- **`get_number_unchecked<let KeyBytes>(key: [u8; KeyBytes])` → `u64`**: From an object root, returns the number at `key`; errors if the key is missing, not a number, or if called when the current root is an array.
-
-- **`get_number_var<let KeyBytes>(key: BoundedVec<u8, KeyBytes>)` → `Option<u64>`**: Same as `get_number`, but accepts a variable-length key up to `KeyBytes`.
-
-- **`get_number_unchecked_var<let KeyBytes>(key: BoundedVec<u8, KeyBytes>)` → `u64`**: Same as `get_number_unchecked`, with a variable-length key.
-
-- **`get_number_from_array(index: Field)` → `Option<u64>`**: When the current root is an array, returns the number at `index` wrapped in `Option`. Returns `None` if `index` is out of bounds; errors if in-bounds but the element at `index` is not a number.
-
-- **`get_number_from_array_unchecked(index: Field)` → `u64`**: When the current root is an array, returns the number at `index`; errors if `index` is out of bounds or the element is not a number.
-
-### String getters API
-
-Strings are returned as `BoundedVec<u8, StringBytes>` where `StringBytes` is the maximum allowed length of the returned string.
-
-- **`get_string<let KeyBytes, let StringBytes>(key: [u8; KeyBytes])` → `Option<BoundedVec<u8, StringBytes>>`**: From an object root, returns `Some(string)` if `key` exists and is a string; `None` if `key` is missing; errors if `key` exists but is not a string, or if called when the current root is an array.
-
-- **`get_string_unchecked<let KeyBytes, let StringBytes>(key: [u8; KeyBytes])` → `BoundedVec<u8, StringBytes>`**: From an object root, returns the string at `key`; errors otherwise.
-
-- **`get_string_var<let KeyBytes, let StringBytes>(key: BoundedVec<u8, KeyBytes>)` → `Option<BoundedVec<u8, StringBytes>>`**: Same as `get_string`, but accepts a variable-length key up to `KeyBytes`.
-
-- **`get_string_unchecked_var<let KeyBytes, let StringBytes>(key: BoundedVec<u8, KeyBytes>)` → `BoundedVec<u8, StringBytes>`**: Same as `get_string_unchecked`, with a variable-length key.
-
-- **`get_string_from_array<let StringBytes>(index: Field)` → `Option<BoundedVec<u8, StringBytes>>`**: When the current root is an array, returns the string at `index` wrapped in `Option`. Returns `None` if `index` is out of bounds; errors if in-bounds but the element at `index` is not a string.
-
-- **`get_string_from_array_unchecked<let StringBytes>(index: Field)` → `BoundedVec<u8, StringBytes>`**: When the current root is an array, returns the string at `index`; errors if `index` is out of bounds or the element is not a string.
-
-- **`get_string_from_path<let KeyBytes, let StringBytes, let PathDepth>(keys: [BoundedVec<u8, KeyBytes>; PathDepth])` → `Option<BoundedVec<u8, StringBytes>>`**: Traverses nested objects by the given keys; returns Some(string) if the final value exists and is a string, otherwise None.
-
 
 # Edge Cases
 

src/get_array.nr

@@ -152,7 +152,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
 
     /**
      * @brief if the root JSON is an array, extract an array given by the position of the target in the source array
-     * @description will revert if the array does not exist
+     * @description When the current root is an array, returns the nested array at `index`. Errors if `index` is out of bounds or the element is not an array.
      **/
     pub fn get_array_from_array_unchecked(self, array_index: Field) -> Self {
         assert(

src/get_literal.nr

@@ -66,12 +66,13 @@ fn extract_literal_from_array(
 
 /**
  * @brief getter methods for extracting literal values out of a JSON struct
+ * @description iterals are the JSON keywords `true`, `false`, and `null`. They are represented by `JSONLiteral`, which supports: `is_true()`, `is_false()`, `is_null()`, `to_bool()` (maps `true` to `true`, `false`/`null` to `false`)
  **/
 impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let MaxNumValues: u32, let MaxKeyFields: u32> JSON<NumBytes, NumPackedFields, MaxNumTokens, MaxNumValues, MaxKeyFields> {
 
     /**
      * @brief if the root JSON is an object, extract a literal value given by `key`
-     * @description returns an Option<JSONLiteral> which will be null if the literal does not exist
+     * @description From an object root, returns `Some(JSONLiteral)` if `key` exists and is a literal; `None` if `key` is missing; errors if `key` exists but is not a literal, or if called when the current root is an array.
      **/
     pub fn get_literal<let KeyBytes: u32>(self, key: [u8; KeyBytes]) -> Option<JSONLiteral> {
         assert(self.layer_type_of_root != ARRAY_LAYER, "cannot extract array elements via a key");
@@ -93,7 +94,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
 
     /**
      * @brief if the root JSON is an object, extract a literal value given by `key`
-     * @description will revert if the literal does not exist
+     * @description From an object root, returns the literal at `key`; errors if the key is missing, not a literal, or if called when the current root is an array.
      **/
     pub fn get_literal_unchecked<let KeyBytes: u32>(self, key: [u8; KeyBytes]) -> JSONLiteral {
         assert(self.layer_type_of_root != ARRAY_LAYER, "cannot extract array elements via a key");
@@ -110,7 +111,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
     }
 
     /**
-     * @brief same as `get_literal` for where the key length may be less than KeyBytes
+     * @brief Same as `get_literal`, but accepts a variable-length key up to `KeyBytes`.
      **/
     pub fn get_literal_var<let KeyBytes: u32>(
         self,
@@ -134,7 +135,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
     }
 
     /**
-     * @brief same as `get_literal_unchecked` for where the key length may be less than KeyBytes
+     * @brief Same as `get_literal_unchecked`, with a variable-length key.
      **/
     pub fn get_literal_unchecked_var<let KeyBytes: u32>(
         self,
@@ -155,7 +156,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
 
     /**
      * @brief if the root JSON is an array, extract a literal given by the position of the target in the source array
-     * @description returns an Option<JSONLiteral> which will be null if the literal does not exist
+     * @description When the current root is an array, returns the literal at `index` wrapped in `Option`. Returns `None` if `index` is out of bounds; errors if in-bounds but the element at `index` is not a literal.
      **/
     fn get_literal_from_array(self, array_index: Field) -> Option<JSONLiteral> {
         assert(
@@ -191,7 +192,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
 
     /**
      * @brief if the root JSON is an array, extract a literal given by the position of the target in the source array
-     * @description will revert if the literal does not exist
+     * @description When the current root is an array, returns the literal at `index`; errors if `index` is out of bounds or the element is not a literal.
      **/
     pub fn get_literal_from_array_unchecked(self, array_index: Field) -> JSONLiteral {
         assert(

src/get_number.nr

@@ -52,7 +52,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
 
     /**
      * @brief if the root JSON is an object, extract a numeric value given by `key`
-     * @description returns an Option<u64> which will be null if the key does not exist
+     * @description From an object root, returns `Some(u64)` if `key` exists and is a number; `None` if `key` is missing; errors if `key` exists but is not a number, or if called when the current root is an array.
      **/
     pub fn get_number<let KeyBytes: u32>(self, key: [u8; KeyBytes]) -> Option<u64> {
         let (exists, entry) = self.get_json_entry(key);
@@ -71,7 +71,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
 
     /**
      * @brief if the root JSON is an object, extract a u64 value given by `key`
-     * @description will revert if the number does not exist
+     * @description From an object root, returns the number at `key`; errors if the key is missing, not a number, or if called when the current root is an array.
      **/
     pub fn get_number_unchecked<let KeyBytes: u32>(self, key: [u8; KeyBytes]) -> u64 {
         let entry = self.get_json_entry_unchecked(key);
@@ -85,7 +85,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
     }
 
     /**
-     * @brief same as `get_number` for where the key length may be less than KeyBytes
+     * @brief Same as `get_number`, but accepts a variable-length key up to `KeyBytes`.
      **/
     pub fn get_number_var<let KeyBytes: u32>(self, key: BoundedVec<u8, KeyBytes>) -> Option<u64> {
         let (exists, entry) = self.get_json_entry_var(key);
@@ -103,7 +103,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
     }
 
     /**
-     * @brief same as `get_number_unchecked` for where the key length may be less than KeyBytes
+     * @brief Same as `get_number_unchecked`, with a variable-length key.
      **/
     pub fn get_number_unchecked_var<let KeyBytes: u32>(self, key: BoundedVec<u8, KeyBytes>) -> u64 {
         let entry = self.get_json_entry_unchecked_var(key);
@@ -118,13 +118,10 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
 
     /**
      * @brief if the root JSON is an array, extract a numeric value given by the position of the target in the source array
-     * @description returns an Option<u64> which will be null if the number does not exist
+     * @description When the current root is an array, returns the number at `index` wrapped in `Option`. Returns `None` if `index` is out of bounds; errors if in-bounds but the element at `index` is not a number.
      **/
     pub fn get_number_from_array(self, array_index: Field) -> Option<u64> {
-        assert(
-            self.layer_type_of_root == ARRAY_LAYER,
-            "can only acceess array elements from array",
-        );
+        assert(self.layer_type_of_root == ARRAY_LAYER, "can only access array elements from array");
 
         let parent_entry: JSONEntry =
             self.json_entries_packed[self.root_index_in_transcript].into();
@@ -153,13 +150,10 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
 
     /**
      * @brief if the root JSON is an array, extract a numeric value given by the position of the target in the source array
-     * @description will revert if the number does not exist
+     * @description When the current root is an array, returns the number at `index`; errors if `index` is out of bounds or the element is not a number.
      **/
     pub fn get_number_from_array_unchecked(self, array_index: Field) -> u64 {
-        assert(
-            self.layer_type_of_root == ARRAY_LAYER,
-            "can only acceess array elements from array",
-        );
+        assert(self.layer_type_of_root == ARRAY_LAYER, "can only access array elements from array");
 
         let parent_entry: JSONEntry =
             self.json_entries_packed[self.root_index_in_transcript].into();

src/get_string.nr

@@ -98,7 +98,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
 
     /**
      * @brief if the root JSON is an object, extract a string given by `key`
-     * @description returns an Option<BoundedVec> which will be null if the key does not exist
+     * @description From an object root, returns `Some(string)` if `key` exists and is a string; `None` if `key` is missing; errors if `key` exists but is not a string, or if called when the current root is an array.
      * @note the `StringBytes` parameter defines the maximum allowable length of the returned string
      **/
     pub fn get_string<let KeyBytes: u32, let StringBytes: u32>(
@@ -125,7 +125,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
 
     /**
      * @brief if the root JSON is an object, extract a string given by `key`
-     * @description will revert if the string does not exist
+     * @description From an object root, returns the string at `key`; errors otherwise.
      * @note the `StringBytes` parameter defines the maximum allowable length of the returned string
      **/
     pub fn get_string_unchecked<let KeyBytes: u32, let StringBytes: u32>(
@@ -145,7 +145,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
     }
 
     /**
-     * @brief same as `get_string` for where the key length may be less than KeyBytes
+     * @brief Same as `get_string`, but accepts a variable-length key up to `KeyBytes`.
      **/
     pub fn get_string_var<let KeyBytes: u32, let StringBytes: u32>(
         self,
@@ -169,7 +169,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
     }
 
     /**
-     * @brief same as `get_string_unchecked` for where the key length may be less than KeyBytes
+     * @brief Same as `get_string_unchecked`, with a variable-length key.
      **/
     pub fn get_string_unchecked_var<let KeyBytes: u32, let StringBytes: u32>(
         self,
@@ -189,7 +189,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
 
     /**
      * @brief if the root JSON is an array, extract a string given by the position of the target in the source array
-     * @description returns an Option<BoundedVec> which will be null if the string does not exist
+     * @description When the current root is an array, returns the string at `index` wrapped in `Option`. Returns `None` if `index` is out of bounds; errors if in-bounds but the element at `index` is not a string.
      **/
     pub fn get_string_from_array<let StringBytes: u32>(
         self,
@@ -229,7 +229,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
 
     /**
      * @brief if the root JSON is an array, extract a string given by the position of the target in the source array
-     * @description will revert if the string does not exist
+     * @description When the current root is an array, returns the string at `index`; errors if `index` is out of bounds or the element is not a string.
      **/
     pub fn get_string_from_array_unchecked<let StringBytes: u32>(
         self,
@@ -262,7 +262,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
     }
 
     /**
-     * @brief if the root JSON is an object, get a nested string out of the JSON, which may be several keys deep
+     * @brief Traverses nested objects by the given keys; returns Some(string) if the final value exists and is a string, otherwise None.
      **/
     pub fn get_string_from_path<let KeyBytes: u32, let StringBytes: u32, let PathDepth: u32>(
         self,