interop/enumerator: update doc, fix Next return value

pkg/interop/enumerator/enumerator.go

@@ -1,29 +1,41 @@
+/*
+Package enumerator provides functions to work with enumerators.
+*/
 package enumerator
 
-// Package enumerator provides function signatures that can be used inside
-// smart contracts that are written in the neo-go framework.
-
-// TODO: Check enumerator use cases and add them to the examples folder.
-
-// Enumerator stubs a NEO enumerator type.
+// Enumerator represents NEO enumerator type, it's an opaque data structure
+// that can be used with functions from this package. It's similar to more
+// widely used Iterator (see `iterator` package), but ranging over arrays
+// or structures that have values with no explicit keys.
 type Enumerator struct{}
 
-// Create creates a new enumerator from the given items.
+// Create creates a new enumerator from the given items (slice or structure).
+// New enumerator points at index -1 of its items, so the user of it has to
+// advance it first with Next. This function uses `Neo.Enumerator.Create`
+// syscall.
 func Create(items []interface{}) Enumerator {
 	return Enumerator{}
 }
 
-// Next returns the next item in the iteration.
-func Next(e Enumerator) interface{} {
-	return nil
+// Next moves position of the given enumerator by one and returns a bool that
+// tells whether there is a new value present in this new position. If it is,
+// you can use Value to get it, if not then there are no more values in this
+// enumerator. This function uses `Neo.Enumerator.Next` syscall.
+func Next(e Enumerator) bool {
+	return true
 }
 
-// Value returns the enumerator value.
+// Value returns current enumerator's item value, it's only valid to call it
+// after Next returning true. This function uses `Neo.Enumerator.Value` syscall.
 func Value(e Enumerator) interface{} {
 	return nil
 }
 
-// Concat concatenates the 2 given enumerators.
+// Concat concatenates two given enumerators returning one that will range on
+// a first and then continue with b. Enumerator positions are not reset for a
+// and b, so if any of them was already advanced by Next the resulting
+// Enumerator will point at this new position and never go back to previous
+// values. This function uses `Neo.Enumerator.Concat` syscall.
 func Concat(a, b Enumerator) Enumerator {
 	return Enumerator{}
 }