Doc all the things

Retargeting to api-breaking-changes. 
Old PR for reference #858