be more explicit defining the return values for the iterator callbacks

+ documentation