add documentation, improve looping