inline documentation

Author: jialinli98

src/get_array.nr

@@ -12,7 +12,7 @@ use crate::utils::cast_num_to_u32;
 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 array, return its length
+     * @brief Returns its length when the current root is an array; errors otherwise.
      **/
     pub fn get_length(self) -> u32 {
         assert(self.layer_type_of_root == ARRAY_LAYER, "can only get length of an array type");
@@ -23,7 +23,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
 
     /**
      * @brief if the root JSON is an object, extract an array given by `key`
-     * @description returns an Option<JSON> where, if the array exists, the JSON object will have the requested array as its root value  
+     * @description 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.  
      **/
     pub fn get_array<let KeyBytes: u32>(self, key: [u8; KeyBytes]) -> Option<Self> {
         assert(self.layer_type_of_root != ARRAY_LAYER, "cannot extract array elements via a key");
@@ -49,7 +49,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
 
     /**
      * @brief if the root JSON is an object, extract an array given by `key`
-     * @description will revert if the array does not exist
+     * @description From an object root, returns the array at key; errors otherwise.
      **/
     pub fn get_array_unchecked<let KeyBytes: u32>(self, key: [u8; KeyBytes]) -> Self {
         assert(self.layer_type_of_root != ARRAY_LAYER, "cannot extract array elements via a key");
@@ -67,7 +67,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
     }
 
     /**
-     * @brief same as `get_array` for where the key length may be less than KeyBytes
+     * @brief Same as `get_array`, but the key can be variable-length up to `KeyBytes`.
      **/
     pub fn get_array_var<let KeyBytes: u32>(self, key: BoundedVec<u8, KeyBytes>) -> Option<Self> {
         assert(self.layer_type_of_root != ARRAY_LAYER, "cannot extract array elements via a key");
@@ -96,7 +96,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
     }
 
     /**
-     * @brief same as `get_array_unchecked` for where the key length may be less than KeyBytes
+     * @brief Same as `get_array_unchecked`, but with a variable-length key.
      **/
     pub fn get_array_unchecked_var<let KeyBytes: u32>(self, key: BoundedVec<u8, KeyBytes>) -> Self {
         assert(self.layer_type_of_root != ARRAY_LAYER, "cannot extract array elements via a key");
@@ -115,7 +115,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 returns an Option<JSON> where, if the array exists, the JSON object will have the requested array as its root value  
+     * @description 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.  
      **/
     pub fn get_array_from_array(self, array_index: Field) -> Option<Self> {
         assert(

src/get_object.nr

@@ -11,8 +11,7 @@ use crate::utils::cast_num_to_u32;
 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 child object given by `key`
-     * @description returns an Option<JSON> where, if the object exists, the JSON object will have the requested object as its root value  
+     * @brief 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.
      **/
     pub fn get_object<let KeyBytes: u32>(self, key: [u8; KeyBytes]) -> Option<Self> {
         assert(self.layer_type_of_root != ARRAY_LAYER, "cannot extract array elements via a key");
@@ -37,8 +36,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
     }
 
     /**
-     * @brief if the root JSON is an object, extract a child object given by `key`
-     * @description will revert if the requested object does not exist
+     * @brief From an object root, returns the object at `key`; errors otherwise.
      **/
     pub fn get_object_unchecked<let KeyBytes: u32>(self, key: [u8; KeyBytes]) -> Self {
         assert(self.layer_type_of_root != ARRAY_LAYER, "cannot extract array elements via a key");
@@ -58,7 +56,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
     }
 
     /**
-     * @brief same as `get_object` for where the key length may be less than KeyBytes
+     * @brief Same as `get_object`, but the key can be variable-length up to `KeyBytes`.
      **/
     pub fn get_object_var<let KeyBytes: u32>(self, key: BoundedVec<u8, KeyBytes>) -> Option<Self> {
         assert(self.layer_type_of_root != ARRAY_LAYER, "cannot extract array elements via a key");
@@ -83,7 +81,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
     }
 
     /**
-     * @brief same as `get_object_unchecked` for where the key length may be less than KeyBytes
+     * @brief Same as `get_object_unchecked`, but with a variable-length key.
      **/
     pub fn get_object_unchecked_var<let KeyBytes: u32>(
         self,
@@ -107,7 +105,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
 
     /**
      * @brief if the root JSON is an array, extract an object given by the position of the target in the source array
-     * @description returns an Option<JSON> where, if the object exists, the JSON object will have the requested object as its root value  
+     * @description 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.
      **/
     pub fn get_object_from_array(self, array_index: Field) -> Option<Self> {
         assert(
@@ -145,7 +143,7 @@ impl<let NumBytes: u32, let NumPackedFields: u32, let MaxNumTokens: u32, let Max
 
     /**
      * @brief if the root JSON is an array, extract an object given by the position of the target in the source array
-     * @description will revert if the object does not exist
+     * @description 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.
      **/
     pub fn get_object_from_array_unchecked(self, array_index: Field) -> Self {
         assert(