added documentation and refactoring to core api