Documentation and tests for IteratorDecorator.

[erikvanoosten]

If this is approved, I will add similar docs and tests for the other intersperse implementations.

[erikvanoosten]

I just realized that the correct term for things in a collection is element and not item. I will update this PR.

[erikvanoosten]

I completed docs and unit tests for IteratorDecorator.

I did not document lazyFoldLeft and lazyFoldRight since I could not find words to describe their exotic behavior:

    def op(acc: Int, e: => Int): Int = if (acc >= 5) acc + 1 else acc + e
    Iterator(4, 5, 20, 20).lazyFoldLeft(0)(op) === 11

I'll work some more on this project in a new PR.
Comments welcome!

[erikvanoosten]

Build fails. I had expected we could use $consumesIterator and $mayNotTerminateInf in the scaladocs...
Should I remove them?

[julienrf]

I had expected we could use $consumesIterator and $mayNotTerminateInf in the scaladocs...

I suggest that you copy their definitions from the standard library. https://github.com/scala/scala/blob/05d028e0eee1eaf9032e652395b94a124c6ad9ed/src/library/scala/collection/Iterator.scala#L50

[julienrf]

It should be just Iterator

[erikvanoosten]

oh.

[julienrf]

Thanks a lot! Could you please squash the comits into a single one?

[erikvanoosten]

Isn't squashing an option when you merge in github? If not, I can find out how to do that.

[julienrf]

Right, there is an option for that.