Add documentation for TileData::State

src/mbgl/map/tile_data.hpp

@@ -25,9 +25,42 @@ class TransformState;
 
 class TileData : private util::noncopyable {
 public:
+    // initial:
+    //   Initial state, only used when the TileData object is created.
+    //
+    // invalid:
+    //   FIXME: This state has a bit of overlap with 'initial' and 'obsolete'.
+    //
+    //   We report TileData being 'invalid' on Source::hasTile if we don't have the
+    //   TileData yet, then Source creates a request. This is misleading because
+    //   the TileData object is not effectively on the 'invalid' state and will
+    //   cause tiles on 'invalid' state to get reloaded.
+    //
+    //   Raster tiles (only) are changing to 'invalid' on error, which will cause a
+    //   re-request of the tile.
+    //
+    // loading:
+    //   A request to the FileSource was made for the actual tile data and TileData
+    //   is waiting for it to arrive.
+    //
+    // loaded:
+    //   The actual tile data has arrived and the tile can be parsed.
+    //
+    // partial:
+    //   TileData is partially parsed, some buckets are still waiting for dependencies
+    //   to arrive, but it is good for rendering. Partial tiles can also be re-parsed,
+    //   but might remain in the same state if dependencies are still missing.
+    //
+    // parsed:
+    //   TileData is fully parsed and its contents won't change from this point. This
+    //   is the only state which is safe to cache this object.
+    //
+    // obsolete:
+    //   The TileData can go to obsolete from any state, due to parsing or loading error,
+    //   request cancellation or because the tile is no longer in use.
     enum class State {
-        invalid,
         initial,
+        invalid,
         loading,
         loaded,
         partial,