filling in more documentation, include some sample use cases