initial documentation

Also removes `public` from a few internal fields and uses ACL instead.

Please check the two `@todo`s before/after merging, I'm not quite sure how/why these work.