updated logic and added documentation