more explicit error types; more documentation