Expand Choreographer docs.

This (hopefully) explains all the bits that confused me when I tried
to use these APIs for the first time. The existing docs leaned a lot
on developers already understanding the Java API, and even the Java
API docs didn't explain how to use this portion of the API well.

Bug: None
Test: I am the test
Change-Id: I48490112f92ef754b38daef7a4ebf6c031cc20f8