Rust codegen: update code comments

Author: szg251

lambda-buffers-codegen/src/LambdaBuffers/Codegen/Rust/Print/LamVal.hs

@@ -163,7 +163,9 @@ printOtherCase iTyDefs otherCase = do
   bodyDoc <- printValueE iTyDefs $ otherCase arg
   return $ group $ argDoc <+> "=>" <+> bodyDoc
 
---- | `printCaseIntE i [(1, x), (2,y)] (\other -> z)` translates into `LambdaBuffers.Runtime.Plutus.LamValcaseIntE i [(1,x), (2,y)] (\other -> z)`
+--- | Call `case_int` function `lbr_prelude`
+--
+-- `printCaseIntE i [(1, x), (2,y)] (\other -> z)` translates into `lbr_prelude::prelude::case_int(i, vec![(1, x), (2,y)]), Box::new(move |other| z)`
 printCaseIntE :: MonadPrint m => PC.TyDefs -> LV.ValueE -> [(LV.ValueE, LV.ValueE)] -> (LV.ValueE -> LV.ValueE) -> m (Doc ann)
 printCaseIntE iTyDefs caseIntVal cases otherCase = do
   caseIntERefDoc <- R.printRsQValName <$> LV.importValue RR.caseIntERef
@@ -180,11 +182,21 @@ printCaseIntE iTyDefs caseIntVal cases otherCase = do
   otherDoc <- printLamE iTyDefs otherCase
   return $ group $ caseIntERefDoc <> encloseSep lparen rparen comma [caseValDoc, align (R.printRsQValName RR.vecMacro <> encloseSep lbracket rbracket comma caseDocs), otherDoc]
 
+{- | Print a list of values
+ ```
+ [<A>, <B>]
+ ```
+-}
 printListE :: MonadPrint m => PC.TyDefs -> [LV.ValueE] -> m (Doc ann)
 printListE iTyDefs vals = do
   valDocs <- printValueE iTyDefs `traverse` vals
   return $ brackets (align (encloseSep mempty mempty (comma <> space) valDocs))
 
+{- | Print a list (Vector in Rust) construction using vec! macro
+ ```
+ std::vec![<A>, <B>]
+ ```
+-}
 printNewListE :: MonadPrint m => PC.TyDefs -> [LV.ValueE] -> m (Doc ann)
 printNewListE iTyDefs vals = do
   lst <- printListE iTyDefs vals
@@ -306,6 +318,19 @@ printCaseTextE iTyDefs txtVal cases otherCase = do
   otherDoc <- printOtherCase iTyDefs otherCase
   return $ "ma" <> align ("tch" <+> caseValDoc <+> braces (line <> vsep (punctuate comma (caseDocs <> [otherDoc]))))
 
+{- | Print a reference
+
+ To help Rust type inference, we inject type information for a few references.
+ In case of a `toPlutusData`, `fromPlutusData`, `toJson`, `fromJson` we call the reference as a trait
+ method on the target type:
+ ```rs
+ <TargetType>::to_plutus_data(...)
+ ```
+ In case of `jsonConstructor`, we print the target type in a turbofish syntax:
+ ```rs
+ lbr_prelude::json::json_constructr::<TargetType>::toPlutusData(...)
+ ```
+-}
 printRefE :: MonadPrint m => LV.Ref -> m (Doc ann)
 printRefE ref = do
   qvn <- LV.resolveRef ref

lambda-buffers-codegen/src/LambdaBuffers/Codegen/Rust/Print/TyDef.hs

@@ -40,8 +40,12 @@ opaque Maybe a
 
 translates to
 
-data Foo a b = Foo'MkFoo a | Foo'MkBar b
-type Maybe a = Prelude.Maybe a
+enum Foo<A, B> {
+  MkFoo<A>,
+  MkBar<B>
+}
+
+type Maybe<A> = lbf_prelude::prelude::maybe<a>
 -}
 printTyDef :: MonadPrint m => PC.TyDef -> m (Doc ann)
 printTyDef (PC.TyDef tyN tyabs _) = do
@@ -55,7 +59,6 @@ printTyDef (PC.TyDef tyN tyabs _) = do
           <> absDoc
     else return $ group $ printTyDefKw kw <+> printTyName tyN <> generics <+> equals <+> absDoc
 
--- TODO(szg251): should we have a Pub wrapper type?
 printTyDefKw :: TyDefKw -> Doc ann
 printTyDefKw StructTyDef = "pub struct"
 printTyDefKw EnumTyDef = "pub enum"
@@ -75,8 +78,12 @@ printDeriveDebug =
 
 For the above examples it prints
 
-a b = Foo'MkFoo a | Foo'MkBar b
-a = Prelude.Maybe a
+<A, B> {
+  MkFoo<A>,
+  MkBar<B>
+}
+
+<A> = lbf_prelude::prelude::maybe<a>
 -}
 printTyAbs :: MonadPrint m => PC.TyName -> PC.TyAbs -> m (TyDefKw, Doc ann, Doc ann)
 printTyAbs tyN (PC.TyAbs args body _) = do
@@ -88,8 +95,12 @@ printTyAbs tyN (PC.TyAbs args body _) = do
 
 For the above examples it prints
 
-Foo'MkFoo a | Foo'MkBar b
-Prelude.Maybe a
+{
+  MkFoo<A>,
+  MkBar<B>
+}
+
+lbf_prelude::prelude::maybe<a>
 -}
 printTyBody :: MonadPrint m => PC.TyName -> [PC.TyArg] -> PC.TyBody -> m (TyDefKw, Doc ann)
 printTyBody parentTyN tyArgs (PC.SumI s) = (EnumTyDef,) <$> printSum parentTyN tyArgs s
@@ -189,6 +200,14 @@ phantomFieldIdent tyArg =
   "phantom_" <> R.printTyArg tyArg
 
 {- | Prints an enum constructor with PhantomData fields
+ for an LB type
+
+ ```
+ prod Something a b = Integer
+ ```
+
+ it prints
+
  ```rs
  PhantomDataCtor(PhantomData<A>, PhantomData<B>)
  ```