reviewed and tweaked api documentation