update logic and documentation