docs for base logic classes, minor refactoring