From 9683adec644cd0a7c5f779142e54625c4564312e Mon Sep 17 00:00:00 2001
From: Caroline Cullen <cullen.caroline@gmail.com>
Date: Mon, 6 Aug 2018 16:06:39 -0700
Subject: [PATCH] Updating documentation for serde

---
 lib/serde/src/clif-json.rs       |  4 ++++
 lib/serde/src/serde_clif_json.rs | 17 +++++++++++++----
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/lib/serde/src/clif-json.rs b/lib/serde/src/clif-json.rs
index eb991343ce..81fe47b020 100644
--- a/lib/serde/src/clif-json.rs
+++ b/lib/serde/src/clif-json.rs
@@ -1,3 +1,5 @@
+//! Utility for `cranelift_serde`.
+
 #![deny(trivial_numeric_casts)]
 #![warn(unused_import_braces, unstable_features, unused_extern_crates)]
 #![cfg_attr(
@@ -49,6 +51,7 @@ struct Args {
 /// A command either succeeds or fails with an error message.
 pub type CommandResult = Result<(), String>;
 
+/// Serialize Cranelift IR to JSON
 fn call_ser(file: &str, pretty: bool) -> CommandResult {
     let ret_of_parse = parse_functions(file);
     match ret_of_parse {
@@ -67,6 +70,7 @@ fn call_ser(file: &str, pretty: bool) -> CommandResult {
     }
 }
 
+/// Deserialize JSON to Cranelift IR 
 fn call_de(file: &File) -> CommandResult {
     let de: serde_clif_json::SerObj = match serde_json::from_reader(file) {
         Result::Ok(val) => val,
diff --git a/lib/serde/src/serde_clif_json.rs b/lib/serde/src/serde_clif_json.rs
index 9bd44b5992..2cc6c006c8 100644
--- a/lib/serde/src/serde_clif_json.rs
+++ b/lib/serde/src/serde_clif_json.rs
@@ -228,6 +228,7 @@ pub enum SerInstData {
     },
 }
 
+/// Convert Cranelift IR instructions to JSON format.
 pub fn get_inst_data(inst_index: Inst, func: &Function) -> SerInstData {
     let inst = &func.dfg[inst_index];
     match *inst {
@@ -444,7 +445,6 @@ pub fn get_inst_data(inst_index: Inst, func: &Function) -> SerInstData {
                 destination: destination.to_string(),
             }
         }
-        // to add: jump table serialization
         InstructionData::BranchTable { opcode, arg, table } => SerInstData::BranchTable {
             opcode: opcode.to_string(),
             arg: arg.to_string(),
@@ -661,6 +661,7 @@ pub fn get_inst_data(inst_index: Inst, func: &Function) -> SerInstData {
     }
 }
 
+/// Serializable version of Cranelift IR instructions.
 #[derive(Clone, Deserialize, Serialize, Debug)]
 pub struct SerInst {
     pub inst_name: String,
@@ -676,6 +677,7 @@ impl SerInst {
     }
 }
 
+/// Serializable version of Cranelift IR Ebbs.
 #[derive(Clone, Deserialize, Serialize, Debug)]
 pub struct SerEbb {
     pub ebb: String,
@@ -703,6 +705,7 @@ pub fn populate_inst(func: &Function, ebb: Ebb) -> Vec<SerInst> {
     ser_vec
 }
 
+/// Translating Ebb parameters into serializable parameters.
 pub fn populate_params(func: &Function, ebb: &Ebb) -> Vec<String> {
     let mut ser_vec: Vec<String> = Vec::new();
     let parameters = func.dfg.ebb_params(*ebb);
@@ -712,12 +715,13 @@ pub fn populate_params(func: &Function, ebb: &Ebb) -> Vec<String> {
     ser_vec
 }
 
-/// Serializable Data Flow Graph
+/// Serializable Data Flow Graph.
 #[derive(Deserialize, Serialize, Debug)]
 pub struct SerDataFlowGraph {
     ebbs: Vec<SerEbb>,
 }
 
+/// Serialize all parts of the Cranelift Ebb data structure, this includes name, parameters, and instructions.
 pub fn populate_ebbs(func: &Function) -> Vec<SerEbb> {
     let mut ebb_vec: Vec<SerEbb> = Vec::new();
     for ebb in func.layout.ebbs() {
@@ -729,6 +733,7 @@ pub fn populate_ebbs(func: &Function) -> Vec<SerEbb> {
     ebb_vec
 }
 
+/// Serializable Cranelift IR data flow graph, including all ebbs.
 impl SerDataFlowGraph {
     pub fn create_new(func: &Function) -> Self {
         Self {
@@ -741,6 +746,7 @@ impl SerDataFlowGraph {
     }
 }
 
+/// Serializable signature including function parameters and returns.
 #[derive(Serialize, Deserialize, Debug)]
 pub struct SerSignature {
     pub func_params: Vec<String>,
@@ -748,6 +754,7 @@ pub struct SerSignature {
 }
 
 impl SerSignature {
+    /// Creating serializable signature data structure from all Cranelift IR functions.
     fn create_new(sig: &Signature) -> Self {
         let mut params_vec: Vec<String> = Vec::new();
         let mut returns_vec: Vec<String> = Vec::new();
@@ -768,7 +775,7 @@ impl SerSignature {
     }
 }
 
-/// Serializable Function type
+/// Serializable Function type, including name, signature, global values, and data flow graph.
 #[derive(Serialize, Deserialize, Debug)]
 pub struct SerFunction {
     pub name: String,
@@ -778,6 +785,7 @@ pub struct SerFunction {
 }
 
 impl SerFunction {
+    /// Creates serializable global values, as well as the functions signature, name, and data flow graph.
     fn create_new(func: &Function) -> Self {
         let mut global_vec: Vec<String> = Vec::new();
         for (glob_name, _) in func.global_values.iter() {
@@ -796,7 +804,8 @@ impl SerFunction {
     }
 }
 
-/// Must have SerObj for deserialization
+/// Must have SerObj for deserialization, contains all of the functions from inside the file to be serialized.
+/// Files have one SerObj each, with all SerFunctions contained inside that SerObj.
 #[derive(Serialize, Deserialize, Debug)]
 pub struct SerObj {
     pub functions: Vec<SerFunction>,