[runtime/vm_runtime] Add more documentation

src/runtime/vm_runtime.rs

@@ -303,7 +303,9 @@ impl Runtime {
         Ok(Self { instance, store, ctx })
     }
 
-    /// Perform a sanity check of the WASM bincode
+    /// Perform a sanity check of the WASM bincode. In particular, ensure that it contains
+    /// all the necessary symbols for executing contracts, including sections for
+    /// Deploy, Exec, Update, and Metadata.
     pub fn sanity_check(&self) -> Result<()> {
         debug!(target: "runtime::vm_runtime", "Performing sanity check on wasm bincode");
 
@@ -316,7 +318,9 @@ impl Runtime {
         Ok(())
     }
 
-    /// Call a contract method and supply a payload.
+    /// Call a contract method using a supplied payload. Returns a Vector of bytes
+    /// corresponding to the result data of the call. For calls that do not return
+    /// any data, an empty Vector is returned.
     fn call(&mut self, section: ContractSection, payload: &[u8]) -> Result<Vec<u8>> {
         debug!(target: "runtime::vm_runtime", "Calling {} method", section.name());
 
@@ -391,6 +395,9 @@ impl Runtime {
             }
         };
 
+        // Check the integer return value of the call. A value of `entrypoint::SUCCESS` (i.e. zero)
+        // corresponds to a successful contract call; in this case, we return the contract's
+        // result data. Otherwise, map the integer return value to a [`ContractError`].
         match retval {
             entrypoint::SUCCESS => Ok(retdata),
             // FIXME: we should be able to see the error returned from the contract
@@ -453,7 +460,7 @@ impl Runtime {
         Ok(())
     }
 
-    /// This funcion runs when someone wants to execute a smart contract.
+    /// This function runs when someone wants to execute a smart contract.
     /// The runtime will look for an `ENTRYPOINT` symbol in the wasm code, and
     /// execute it if found. A payload is also passed as an instruction that can
     /// be used inside the vm by the runtime.
@@ -482,6 +489,7 @@ impl Runtime {
         self.call(ContractSection::Metadata, payload)
     }
 
+    /// Prints the wasm contract logs.
     fn print_logs(&self) {
         let logs = self.ctx.as_ref(&self.store).logs.borrow();
         for msg in logs.iter() {
@@ -521,7 +529,7 @@ impl Runtime {
         }
     }
 
-    /// Set the memory page size
+    /// Set the memory page size. Returns the previous memory size.
     fn set_memory_page_size(&mut self, pages: u32) -> Result<Pages> {
         // Grab memory by value
         let memory = self.take_memory();
@@ -550,7 +558,7 @@ impl Runtime {
     }
 
     /// Serialize contract payload to the format accepted by the runtime functions.
-    /// We keep the same payload as a slice of bytes, and prepend it with a ContractId,
+    /// We keep the same payload as a slice of bytes, and prepend it with a [`ContractId`],
     /// and then a little-endian u64 to tell the payload's length.
     fn serialize_payload(cid: &ContractId, payload: &[u8]) -> Vec<u8> {
         let ser_cid = serialize(cid);