Restore docs for deprecated Choreographer APIs.

They're deprecated, but still needed by most users, as the replacement
is not available until API 29. Restore the docs and explain the bugs.

Bug: None
Test: treehugger
Change-Id: I4227ce3f0ee57a73a13e394cd48373accf4a58a3