Documentation improvements for new API.

Signed-off-by: Tim Henderson <tim.tadh@gmail.com>