update README and some annotations