improved doc. with code-examples of extending