clean up the api a bit and adds some more examples