re docs: particularly that this returns a generator