improved docs

Fix remarks in #138
rebased onto master
we still need a separate PR to fix the doc tests to work with the new Table api

review by @szeiger