[not ready] Docs updates

about to ping a bunch of people about TODOs here, be ready
Yes, made an issue about checking the implementation https://github.com/mapbox/mapbox-gl-js/issues/614