add a nice global example and runnable code in docs; needs a bit more work