more refactoring of API and documentation