Improve API docs
#1811

toolness wants to merge better-api-docs into develop

We do not currently have an analysis of these two commits