improve api docs
add throttle example
improve explanation of throttle example
add style for examples
fix formatting in examples
improve explanation of running the examples in the readme