From dff0f724cdb28ab7bc051187e30717d3e2e23cab Mon Sep 17 00:00:00 2001
From: Roman Khimov <roman@nspcc.ru>
Date: Mon, 18 May 2020 17:11:27 +0300
Subject: [PATCH] interop/runtime: update documentation, fix Notify

Notify doesn't return anything!
---
 pkg/interop/runtime/runtime.go | 56 +++++++++++++++++++++++-----------
 1 file changed, 39 insertions(+), 17 deletions(-)

diff --git a/pkg/interop/runtime/runtime.go b/pkg/interop/runtime/runtime.go
index fd07d7bd6..9b7e837d3 100644
--- a/pkg/interop/runtime/runtime.go
+++ b/pkg/interop/runtime/runtime.go
@@ -1,48 +1,70 @@
+/*
+Package runtime provides various service functions related to execution environment.
+It has similar function to Runtime class in .net framwork for Neo.
+*/
 package runtime
 
-// Package runtime provides function signatures that can be used inside
-// smart contracts that are written in the neo-go framework.
-
-// CheckWitness verifies if the given hash is the invoker of the contract.
-func CheckWitness(hash []byte) bool {
+// CheckWitness verifies if the given script hash (160-bit BE value in a 20 byte
+// slice) or key (compressed serialized 33-byte form) is one of the signers of
+// this invocation. It uses `Neo.Runtime.CheckWitness` syscall.
+func CheckWitness(hashOrKey []byte) bool {
 	return true
 }
 
-// Log instucts the VM to log the given message.
+// Log instructs VM to log the given message. It's mostly used for debugging
+// purposes as these messages are not saved anywhere normally and usually are
+// only visible in the VM logs. This function uses `Neo.Runtime.Log` syscall.
 func Log(message string) {}
 
-// Notify an event to the VM.
-func Notify(arg ...interface{}) int {
-	return 0
-}
+// Notify sends a notification (collecting all arguments in an array) to the
+// executing environment. Unlike Log it can accept any data and resulting
+// notification is saved in application log. It's intended to be used as a
+// part of contract's API to external systems, these events can be monitored
+// from outside and act upon accordingly. This function uses
+// `Neo.Runtime.Notify` syscall.
+func Notify(arg ...interface{}) {}
 
-// GetTime returns the timestamp of the most recent block.
+// GetTime returns the timestamp of the most recent block. Note that when running
+// script in test mode this would be the last accepted (persisted) block in the
+// chain, but when running as a part of the new block the time returned is the
+// time of this (currently being processed) block. This function uses
+// `Neo.Runtime.GetTime` syscall.
 func GetTime() int {
 	return 0
 }
 
-// GetTrigger returns the smart contract invoke trigger which can be either
-// verification or application.
+// GetTrigger returns the smart contract invocation trigger which can be either
+// verification or application. It can be used to differentiate running contract
+// as a part of verification process from running it as a regular application.
+// Some interop functions (especially ones that change the state in any way) are
+// not available when running with verification trigger. This function uses
+// `Neo.Runtime.GetTrigger` syscall.
 func GetTrigger() byte {
 	return 0x00
 }
 
-// Application returns the Application trigger type
+// Application returns the Application trigger type value to compare with
+// GetTrigger return value.
 func Application() byte {
 	return 0x10
 }
 
-// Verification returns the Verification trigger type
+// Verification returns the Verification trigger type value to compare with
+// GetTrigger return value.
 func Verification() byte {
 	return 0x00
 }
 
-// Serialize serializes and item into a bytearray.
+// Serialize serializes any given item into a byte slice. It works for all
+// regular VM types (not ones from interop package) and allows to save them in
+// storage or pass into Notify and then Deserialize them on the next run or in
+// the external event receiver. It uses `Neo.Runtime.Serialize` syscall.
 func Serialize(item interface{}) []byte {
 	return nil
 }
 
-// Deserialize an item from a bytearray.
+// Deserialize unpacks previously serialized value from a byte slice, it's the
+// opposite of Serialize. It uses `Neo.Runtime.Deserialize` syscall.
 func Deserialize(b []byte) interface{} {
 	return nil
 }