some bugfixes, exception classes and utility functions decoupling
docs updated