Generally Improve r* method documentation

[Deconstrained]

I'm thinking that instead of the current verbose mess, we could make it loosely follow the same structure as the general API documentation while briefly introducing all the cool ways that the implementation of that stuff is handled by the client.

https://developer.pagerduty.com/docs/ZG9jOjQ2NDA2-introduction