adding comments for clarity on methods and cleaning up examples