Added a lot of comments and included deferreds

methods are now more commented and promises are now used also
throughout the api