Improve README

- add sections for `decorator` and `flatorator`.
- simplify doctests