Reset the source cache for GeoJSONSource#setData, and document the …

…reset in `Map#setFeatureState`

src/source/source_cache.js

@@ -217,6 +217,9 @@ class SourceCache extends Evented {
         }
 
         this._cache.reset();
+        //Reset the SourceCache when the source has been reloaded. For GeoJSON sources, 
+        // the `id`  of features is not guaranteed to be identical when updated
+        this._state = new SourceFeatureState();
 
         for (const i in this._tiles) {
             if (this._tiles[i].state !== "errored") this._reloadTile(i, 'reloading');

src/style-spec/reference/v8.json

@@ -381,7 +381,7 @@
     "generateId": {
         "type": "boolean",
         "default": false,
-        "doc": "Whether to generate ids for the geojson features. When enabled, the `feature.id` property will be auto assigned, over-writing any previous values."
+        "doc": "Whether to generate ids for the geojson features. When enabled, the `feature.id` property will be auto assigned based on it's index in the `features` array, over-writing any previous values."
     }
   },
   "source_video": {

src/ui/map.js

@@ -1423,11 +1423,17 @@ class Map extends Camera {
      *
      * @param {Object} [feature] Feature identifier. Feature objects returned from
      * {@link Map#queryRenderedFeatures} or event handlers can be used as feature identifiers.
+     * @param {string} [feature.id] Unique id of the feature.
      * @param {string} [feature.source] The Id of the vector source or GeoJSON source for the feature.
      * @param {string} [feature.sourceLayer] (optional)  *For vector tile sources, the sourceLayer is
      *  required.*
-     * @param {string} [feature.id] Unique id of the feature.
      * @param {Object} state A set of key-value pairs. The values should be valid JSON types.
+     *
+     * This method requires the `feature.id` attribute on vector data sets. For GeoJSON source that dont already
+     * the feature ids, set the `generateIds` option in the `GeoJSONSourceSpecification` to auto-assign them. This 
+     * option assigns ids based on a feature's index in the source data, and depends on the order of features in
+     * the source data. Changing the feature data using `map.getSource('some id').setData(..)` resets the cache of
+     * feature states and requires the caller re-apply the state as needed with the possibly modified `id` values.
      */
     setFeatureState(feature: { source: string; sourceLayer?: string; id: string; }, state: Object) {
         this.style.setFeatureState(feature, state);