refactoring and docblocks for ORM