srml-contract: ext_caller follow-up (#1266)

* s/account ID/address

* Add a note about CODE_CALLER

* Comment tests.

substrate/srml/contract/COMPLEXITY.md

@@ -277,9 +277,9 @@ This function receives a `data` buffer as an argument. Execution of the function
 
 ## ext_caller
 
-This function serializes the account ID of the caller into the scratch buffer.
+This function serializes the address of the caller into the scratch buffer.
 
-**complexity**: Assuming that the account ID is of constant size, this function has constant complexity.
+**complexity**: Assuming that the address is of constant size, this function has constant complexity.
 
 ## ext_input_size
 

substrate/srml/contract/src/tests.rs

@@ -879,19 +879,23 @@ const CODE_CALLER_LOGGER: &'static str = r#"
 	(import "env" "ext_set_storage" (func $ext_set_storage (param i32 i32 i32 i32)))
 	(import "env" "memory" (memory 1 1))
 
+	;; Memory layout
+	;; [0..32]: the storage key (passed as the key for ext_set_storage)
+	;; [32..40]: contents of the scratch buffer (which is expected to be 8 bytes long)
+
 	(func (export "call")
 		;; Fill the scratch buffer with the caller.
 		(call $ext_caller)
 
 		;; Copy contents of the scratch buffer into the contract's memory.
 		(call $ext_scratch_copy
-			(i32.const 32)		;; Pointer in memory to the place where to copy.
+			(i32.const 32)		;; Store scratch's buffer contents at this address.
 			(i32.const 0)		;; Offset from the start of the scratch buffer.
 			(i32.const 8)		;; Count of bytes to copy.
 		)
 
 		(call $ext_set_storage
-			(i32.const 0)		;; the storage key
+			(i32.const 0)		;; The storage key to save the value at. 32 bytes long.
 			(i32.const 1)		;; value_not_null=1, i.e. we are not removing the value
 			(i32.const 32)		;; the pointer to the value to store
 			(i32.const 8)		;; the length of the value

substrate/srml/contract/src/vm/mod.rs

@@ -541,6 +541,8 @@ mod tests {
 	}
 
 
+	/// calls `ext_caller`, loads the address from the scratch buffer and
+	/// compares it with the constant 42.
 	const CODE_CALLER: &'static str =
 r#"
 (module
@@ -559,7 +561,7 @@ r#"
 	)
 
 	(func (export "call")
-		;; Fill the scratch buffer with the caller.
+		;; fill the scratch buffer with the caller.
 		(call $ext_caller)
 
 		;; assert $ext_scratch_size == 8
@@ -570,7 +572,7 @@ r#"
 			)
 		)
 
-		;; Copy contents of the scratch buffer into the contract's memory.
+		;; copy contents of the scratch buffer into the contract's memory.
 		(call $ext_scratch_copy
 			(i32.const 8)		;; Pointer in memory to the place where to copy.
 			(i32.const 0)		;; Offset from the start of the scratch buffer.