document API

[ci skip]
TODO updates and cleanup

[ci skip]