adding examples and some more descriptions; fixes #2