adding more documentation and refactoring some code to use Deferred objects instead of callbacks