Add info about (de-)serialization as doc comments

src/literal.rs

@@ -1,5 +1,8 @@
 //! A subset of [`crate::ast::Expr`] that is used as input / output by an
 //! [`crate::eval::Evaluator`].
+//!
+//! See [`crate::literal::Literal`] for examples on how to (de-)serialize to/from Garble literals
+//! using `serde`.
 
 use std::{
     collections::{HashMap, HashSet},
@@ -23,6 +26,59 @@ use crate::{
 
 /// A subset of [`crate::ast::Expr`] that is used as input / output by an
 /// [`crate::eval::Evaluator`].
+///
+/// If the `serde` crate feature is enabled, literals can be (de-)serialized to any format supported
+/// by `serde`. The following ABNF grammar shows how literals are represented when serialized using
+/// `serde_json`:
+///
+/// ```asci
+/// literal = "\"True\"" /
+///           "\"False\"" /
+///           "{\"NumUnsigned\":[" uint "," uint-ty "]}" /
+///           "{\"NumSigned\":[" int "," int-ty "]}" /
+///           "{\"ArrayRepeat\":[" literal "," uint "]}" /
+///           "{\"Array\":[" [literal *("," literal)] "]}" /
+///           "{\"Tuple\":[" [literal *("," literal)] "]}" /
+///           "{\"Enum\":[\"" string "\",\"" string "\"," variant "]}" /
+///           "{\"Range\":[" uint "," uint "," uint-type "]}"
+///
+/// uint    = 1*DIGIT
+///
+/// uint-ty = "\"Usize\"" /
+///           "\"U8\"" /
+///           "\"U16\"" /
+///           "\"U32\"" /
+///           "\"U64\"" /
+///           "\"Unspecified\""
+///
+/// int     = ["-"] uint
+///
+/// int-ty  = "\"I8\"" /
+///           "\"I16\"" /
+///           "\"I32\"" /
+///           "\"I64\"" /
+///           "\"Unspecified\""
+///
+/// string  = 1*ALPHA
+///
+/// variant = "\"Unit\"" /
+///           "{\"Tuple\":[" [literal *("," literal)] "]}"
+/// ```
+///
+/// Here are some example Garble literals and how they would be serialized as JSON:
+///
+/// | Garble Literal                   | Serialized as JSON                                       |
+/// | -------------------------------- | -------------------------------------------------------- |
+/// | `true`                           | `"True"`                                                 |
+/// | `200u32`                         | `{"NumUnsigned":[200,"U32"]}`                            |
+/// | `-200`                           | `{"NumSigned":[-200,"Unspecified"]}`                     |
+/// | `[true; 3]`                      | `{"ArrayRepeat":["True",3]}`                             |
+/// | `[true, false]`                  | `{"Array":["True","False"]}`                             |
+/// | `(true, false, 10)`              | `{"Tuple":["True","False",{"NumUnsigned":[10,"U8"]}]}`   |
+/// | `FooBar {foo: true, bar: false}` | `{"Struct":["FooBar",[["foo","True"],["bar","False"]]]}` |
+/// | `FooBar::Foo`                    | `{"Enum":["FooBar","Foo","Unit"]}`                       |
+/// | `FooBar::Bar(true, false)`       | `{"Enum":["FooBar","Bar",{"Tuple":["True","False"]}]}`   |
+/// | `2u8..10u8`                      | `{"Range":[2,10,"U8"]}`                                  |
 #[derive(Debug, Clone, Hash, PartialEq, Eq, PartialOrd, Ord)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub enum Literal {