add exceptions, annotations, some fixes