From 01b5299355731d1b6857a7d246eb87d9d8124f71 Mon Sep 17 00:00:00 2001
From: Roman Khimov <roman@nspcc.ru>
Date: Mon, 18 May 2020 15:30:44 +0300
Subject: [PATCH] interop/iterator: documentation update

---
 pkg/interop/iterator/iterator.go | 45 +++++++++++++++++++++-----------
 1 file changed, 30 insertions(+), 15 deletions(-)

diff --git a/pkg/interop/iterator/iterator.go b/pkg/interop/iterator/iterator.go
index 84e85310e..b4bd281da 100644
--- a/pkg/interop/iterator/iterator.go
+++ b/pkg/interop/iterator/iterator.go
@@ -1,39 +1,54 @@
+/*
+Package iterator provides functions to work with Neo iterators.
+*/
 package iterator
 
-// Package iterator provides function signatures that can be used inside
-// smart contracts that are written in the neo-go framework.
+import "github.com/nspcc-dev/neo-go/pkg/interop/enumerator"
 
-// Iterator stubs a NEO iterator object type.
+// Iterator represents a Neo iterator, it's an opaque data structure that can
+// be properly created by Create or storage.Find. Unlike enumerators, iterators
+// range over key-value pairs, so it's convenient to use them for maps. This
+// structure is similar in function to Neo .net framework's Iterator.
 type Iterator struct{}
 
-// Create creates an iterator from the given items.
+// Create creates an iterator from the given items (array, struct or map). A new
+// iterator is set to point at element -1, so to access its first element you
+// need to call Next first. This function uses `Neo.Iterator.Create` syscall.
 func Create(items []interface{}) Iterator {
 	return Iterator{}
 }
 
-// Key returns the iterator key.
-// TODO: Better description for this.
+// Key returns iterator's key at current position. It's only valid to call after
+// successful Next call. This function uses `Neo.Iterator.Key` syscall.
 func Key(it Iterator) interface{} {
 	return nil
 }
 
-// Keys returns the iterator keys.
-func Keys(it Iterator) []interface{} {
-	return nil
+// Keys returns Enumerator ranging over keys or the given Iterator. Note that
+// this Enumerator is actually directly tied to the underlying Iterator, so that
+// advancing it with Next will actually advance the Iterator too. This function
+// uses `Neo.Iterator.Keys` syscall.
+func Keys(it Iterator) enumerator.Enumerator {
+	return enumerator.Enumerator{}
 }
 
-// Next advances the iterator, return true if it is was successful
-// and false otherwise.
+// Next advances the iterator returning true if it is was successful (and you
+// can use Key or Value) and false otherwise (and there are no more elements in
+// this Iterator). This function uses `Neo.Iterator.Next` syscall.
 func Next(it Iterator) bool {
 	return true
 }
 
-// Value returns the current iterator value.
+// Value returns iterator's current value. It's only valid to call after
+// successful Next call. This function uses `Neo.Iterator.Value` syscall.
 func Value(it Iterator) interface{} {
 	return nil
 }
 
-// Values returns the iterator values.
-func Values(it Iterator) []interface{} {
-	return nil
+// Values returns Enumerator ranging over values or the given Iterator. Note that
+// this Enumerator is actually directly tied to the underlying Iterator, so that
+// advancing it with Next will actually advance the Iterator too. This function
+// uses `Neo.Iterator.Values` syscall.
+func Values(it Iterator) enumerator.Enumerator {
+	return enumerator.Enumerator{}
 }