From 6dff01672c145a798dae621aa9b4ecb4c7011aa8 Mon Sep 17 00:00:00 2001
From: Roman Khimov <roman@nspcc.ru>
Date: Sun, 17 May 2020 17:45:37 +0300
Subject: [PATCH] interop/account: update and extend documentation

---
 pkg/interop/account/account.go | 29 +++++++++++++++++++++--------
 1 file changed, 21 insertions(+), 8 deletions(-)

diff --git a/pkg/interop/account/account.go b/pkg/interop/account/account.go
index c2e4cb19c..c18172eb7 100644
--- a/pkg/interop/account/account.go
+++ b/pkg/interop/account/account.go
@@ -1,23 +1,36 @@
+/*
+Package account provides getter functions for Account interop structure.
+To use these functions you need to get an Account first via blockchain.GetAccount
+call.
+*/
 package account
 
-// Package account provides function signatures that can be used inside
-// smart contracts that are written in the neo-go framework.
-
-// Account stubs a NEO account type.
+// Account represents NEO account type that is used in interop functions, it's
+// an opaque data structure that you can get data from only using functions from
+// this package. It's similar in function to the Account class in the Neo .net
+// framework.
 type Account struct{}
 
-// GetScriptHash returns the script hash of the given account.
+// GetScriptHash returns the script hash of the given Account (20 bytes in BE
+// representation). It uses `Neo.Account.GetBalance` syscall internally.
 func GetScriptHash(a Account) []byte {
 	return nil
 }
 
-// GetVotes returns the votes of the given account which should be a slice of
-// public key raw bytes.
+// GetVotes returns current votes of the given account represented as a slice of
+// public keys. Keys are serialized into byte slices in their compressed form (33
+// bytes long each). This function uses `Neo.Account.GetVotes` syscall
+// internally.
 func GetVotes(a Account) [][]byte {
 	return nil
 }
 
-// GetBalance returns the balance of for the given account and asset id.
+// GetBalance returns current balance of the given asset (by its ID, 256 bit
+// hash in BE form) for the given account. Only native UTXO assets can be
+// queiried via this function, for NEP-5 ones use respective contract calls.
+// The value returned is represented as an integer with original value multiplied
+// by 10⁸ so you can work with fractional parts of the balance too. This function
+// uses `Neo.Account.GetBalance` syscall internally.
 func GetBalance(a Account, assetID []byte) int {
 	return 0
 }