Update readme to reflect decorators
fix #581 + some other cleanup