Add more documentation

Author: szg251

runtimes/rust/lbr-prelude-derive/src/lib.rs

@@ -175,8 +175,8 @@ fn impl_enum(
     ident: &syn::Ident,
     variants: &syn::punctuated::Punctuated<syn::Variant, syn::token::Comma>,
 ) -> (proc_macro2::TokenStream, proc_macro2::TokenStream) {
-    // Arms of the pattern match over the enum variants
-    let to_json_pattern_match = variants.iter().map(|variant| {
+    // Arms of the pattern match over the variants of the original data
+    let to_json_match_arms = variants.iter().map(|variant| {
         let variant_ident = &variant.ident;
         let variant_str = variant.ident.to_string();
 
@@ -206,13 +206,13 @@ fn impl_enum(
     let to_json_impl = quote! {
         fn to_json(&self) -> Result<serde_json::Value, lbr_prelude::error::Error> {
             Ok(match self {
-                #(#to_json_pattern_match)*
+                #(#to_json_match_arms)*
             })
         }
     };
 
-    // Arms of the pattern match over tuple containinig the key-value pair
-    let from_json_pattern_match = variants.iter().map(|variant| {
+    // Arms of the pattern match over the JSON name and fields
+    let from_json_match_arms = variants.iter().map(|variant| {
         let variant_ident = &variant.ident;
         let variant_str = variant.ident.to_string();
 
@@ -264,7 +264,7 @@ fn impl_enum(
     let from_json_impl = quote! {
         fn from_json(value: serde_json::Value) -> Result<Self, lbr_prelude::error::Error> {
             lbr_prelude::json::sum_parser(&value).and_then(|obj| match obj {
-                #(#from_json_pattern_match)*
+                #(#from_json_match_arms)*
                 _ => Err(lbr_prelude::error::Error::UnexpectedJsonInvariant {
                     wanted: #error_msg.to_owned(),
                     got: "unknown constructor name".to_owned(),

runtimes/rust/lbr-prelude-derive/tests/struct.rs

@@ -15,11 +15,10 @@ fn main() {
         age: BigInt::from(89),
     };
 
-    let mut dict = serde_json::Map::new();
-    dict.insert("name".to_owned(), Value::String("田中太郎".to_owned()));
-    dict.insert("age".to_owned(), Value::Number(Number::from(89)));
-
-    let expected = Value::Object(dict);
+    let expected = Value::Object(serde_json::Map::from_iter([
+        ("name".to_owned(), Value::String("田中太郎".to_owned())),
+        ("age".to_owned(), Value::Number(Number::from(89))),
+    ]));
 
     let actual = data.to_json().unwrap();
 

runtimes/rust/lbr-prelude/src/error.rs

@@ -1,3 +1,4 @@
+//! Common error type
 use serde_json::Value;
 use thiserror;
 
@@ -25,6 +26,7 @@ impl From<&Value> for JsonType {
     }
 }
 
+/// Error type representing Json conversion errors
 #[derive(thiserror::Error, Debug)]
 pub enum Error {
     #[error("Expected a JSON type: {wanted:?}, but got a JSON type: {got:?}")]

runtimes/rust/lbr-prelude/src/generators/correct.rs

@@ -1,3 +1,7 @@
+//! Proptest strategies for most common types
+//!
+//! These strategies always return valid values.
+
 use num_bigint::{BigInt, Sign};
 use proptest::arbitrary::{any, StrategyFor};
 use proptest::char::CharStrategy;

runtimes/rust/lbr-prelude/src/generators/mod.rs

@@ -1 +1,2 @@
+//! Proptest strategies for most common types
 pub mod correct;

runtimes/rust/lbr-prelude/src/json.rs

@@ -1,3 +1,4 @@
+//! Json serialization of Lambda Buffers types
 pub use crate::error::{Error, JsonType};
 use core::str::FromStr;
 use data_encoding::BASE64;
@@ -322,8 +323,8 @@ where
     }
 }
 
-/// Construct a JSON Value from a sum type
-/// We always encode sum types into a `{"name": string, "fields": any[]}` format in JSON
+/// Construct a JSON Value from a sum type.
+/// We always encode sum types into a `{"name": string, "fields": any[]}` format in JSON.
 pub fn sum_constructor(ctor_name: &str, ctor_product: Vec<Value>) -> Value {
     let mut obj = serde_json::Map::new();
     obj.insert("name".to_owned(), Value::String(ctor_name.to_owned()));
@@ -332,8 +333,8 @@ pub fn sum_constructor(ctor_name: &str, ctor_product: Vec<Value>) -> Value {
     Value::Object(obj)
 }
 
-/// Parse a JSON value into an intermediary representation of a sum type
-/// We always encode sum types into a `{"name": string, "fields": any[]}` format in JSON
+/// Parse a JSON value into an intermediary representation of a sum type.
+/// We always encode sum types into a `{"name": string, "fields": any[]}` format in JSON.
 pub fn sum_parser(value: &Value) -> Result<(&str, &Vec<Value>), Error> {
     match value {
         Value::Object(obj) => {

runtimes/rust/lbr-prelude/src/lib.rs

@@ -1,3 +1,6 @@
+//! Lambda Buffers Runtime Prelude
+//!
+//! Common functionality for Lamba Buffer types.
 pub mod error;
 pub mod generators;
 pub mod json;