Hello

I thought about two bits in your message: “I think it's clear enough” 
and “So by reading it carefully”. They show that the doc is a bit 
ambiguous here, and while I agree that people should take the time to 
read and understand, I think that documentation can always be made 
clearer. The doc about iterables could tell to return an instance of 
another class or use a generator, and then a separate paragraph would 
explain about using next to define iterators, explaining that iterators 
may or may not be iterable.

Does that sound good?

Regards