refactor(heatmaps): Improve API clarity and documentation

Addresses feedback to make the heatmap API more intuitive and robust.

- Renames `setWeightedData` and `setData` in `HeatmapTileProvider` to `updateData` and `updateLatLngs` respectively. The `update` prefix better communicates that these methods perform expensive operations that rebuild internal state, rather than just setting a property.
- The old method names are preserved and marked as `@Deprecated` to provide a smooth migration path for existing users and avoid a breaking change.

- Adds a default value of 0.7 to the `opacity` parameter in `Gradient.generateColorMap`. This aligns with the default in `HeatmapTileProvider` and simplifies common use cases.
- Annotates `generateColorMap` with `@JvmOverloads` to ensure the new default parameter is exposed correctly to Java clients.

- Improves KDoc for all modified methods to be more descriptive, explaining the purpose of the code and the reasoning behind the design choices.

Author: dkhawk

library/src/main/java/com/google/maps/android/heatmaps/Gradient.kt

@@ -79,13 +79,20 @@ class Gradient @JvmOverloads constructor(
     }
 
     /**
-     * Generates the color map to use with a provided gradient.
+     * Generates a color map array from the gradient's colors and start points. This map is a key
+     * component for rendering the heatmap, where each color corresponds to a different intensity
+     * level.
      *
-     * @param opacity Overall opacity of entire image: every individual alpha value will be
-     * multiplied by this opacity.
-     * @return the generated color map based on the gradient
+     * The process involves interpolating between the specified colors in the HSV color space to create
+     * a smooth transition.
+     *
+     * @param opacity The overall opacity of the entire color map. Each color's alpha value will be
+     * multiplied by this factor. The default value is 0.7, chosen for consistency with the
+     * default opacity of [HeatmapTileProvider].
+     * @return An integer array representing the color map, where each element is a color integer.
      */
-    fun generateColorMap(opacity: Double): IntArray {
+    @JvmOverloads
+    fun generateColorMap(opacity: Double = 0.7): IntArray {
         val colorIntervals = generateColorIntervals()
         val colorMap = IntArray(colorMapSize)
         var interval = colorIntervals[0]

library/src/main/java/com/google/maps/android/heatmaps/HeatmapTileProvider.kt

@@ -55,7 +55,7 @@ class HeatmapTileProvider private constructor(builder: Builder) : TileProvider {
         // Don't compute anything till data is set
         kernel = generateKernel(radius, radius / 3.0)
         setGradient(gradient)
-        setWeightedData(data)
+        updateData(data)
     }
 
     /**
@@ -143,7 +143,21 @@ class HeatmapTileProvider private constructor(builder: Builder) : TileProvider {
         }
     }
 
+    @Deprecated("Use updateData(Collection<WeightedLatLng>) instead.", ReplaceWith("updateData(data)"))
     fun setWeightedData(data: Collection<WeightedLatLng>) {
+        updateData(data)
+    }
+
+    /**
+     * Refreshes the heatmap with a new collection of weighted data points.
+     *
+     * This is an expensive operation. It involves rebuilding the quadtree index and recalculating
+     * the bounds and maximum intensity values for the new dataset. This method should be used when
+     * the underlying data for the heatmap has changed.
+     *
+     * @param data The new collection of [WeightedLatLng] points.
+     */
+    fun updateData(data: Collection<WeightedLatLng>) {
         this.data = data
         require(this.data.isNotEmpty()) { "No input points." }
         this.bounds = getBounds(this.data)
@@ -154,8 +168,22 @@ class HeatmapTileProvider private constructor(builder: Builder) : TileProvider {
         this.maxIntensity = getMaxIntensities(this.radius)
     }
 
+    @Deprecated("Use updateLatLngs(Collection<LatLng>) instead.", ReplaceWith("updateLatLngs(latLngs)"))
     fun setData(latLngs: Collection<LatLng>) {
-        setWeightedData(wrapData(latLngs))
+        updateLatLngs(latLngs)
+    }
+
+    /**
+     * Refreshes the heatmap with a new collection of unweighted data points.
+     * Each point is assigned a default weight of 1.0.
+     *
+     * This is a convenience method that wraps the data in [WeightedLatLng] objects before
+     * calling [updateData].
+     *
+     * @param latLngs The new collection of [LatLng] points.
+     */
+    fun updateLatLngs(latLngs: Collection<LatLng>) {
+        updateData(wrapData(latLngs))
     }
 
     fun setGradient(gradient: Gradient) {
@@ -176,7 +204,7 @@ class HeatmapTileProvider private constructor(builder: Builder) : TileProvider {
 
     fun setMaxIntensity(intensity: Double) {
         this.customMaxIntensity = intensity
-        setWeightedData(this.data)
+        updateData(this.data)
     }
 
     override fun getTile(x: Int, y: Int, zoom: Int): Tile {