added some documentation and more informative exception behaviour