add examples and explanation to README, refactoring comments