documentation

Summary: More thorough documentation with a bunch of TODOs added and visibility changed in some places.

Test Plan: manual. unit tests.

Reviewers: joy, dustin

Reviewed By: joy

CC: Engineering

Differential Revision: https://phabricator.poptip.com/D2907