use iterators, update docstrings