BATCHEE-33 adding JavaDocs and test

txs to Reinhard Sandtner for the test. Applied.
I did not apply the method name change as getIterator is too technical
and does not tell the user what it should iterate over.
We also kept the Iterator after discussions on the list.