[MAPSAND-2541] Clarify scale/pixel density docs for addStyleImage and addImage (#10400)

### Summary

Fixes https://mapbox.atlassian.net/browse/MAPSAND-2541

- Updated `@param scale` KDoc in `addStyleImage` to explain pixel
density semantics with a concrete example
- Added pixel density explanation paragraphs to all 4 `addImage`
overloads in `MapboxStyleManager.kt`

### Problem

The `scale` parameter in `addStyleImage` was documented only as "A scale
factor for the image," giving no indication of how scale affects
rendering. Similarly, `addImage` overloads had no documentation
explaining how pixel dimensions relate to display size, causing
developer confusion when images appear at unexpected sizes.

### Solution

Clarify that `scale` represents pixel density: image pixel dimensions
are divided by the scale value to determine display size in dp. For
`addImage`, document that pixel dimensions are assumed to match device
screen density, and point users to `addStyleImage` when custom density
is needed.

### Key Changes

- **`MapboxStyleManager.kt` — `addStyleImage`**: `@param scale` updated
from "A scale factor for the image" to full pixel density explanation
with 100x100 @ scale=2.0 → 50x50dp example
- **`Style.kt` — `addStyleImage`**: Same `@param scale` clarification
applied
- **`MapboxStyleManager.kt` — `addImage` (×4 overloads)**: Added
paragraph explaining dimensions assumed to match device screen density,
with reference to `addStyleImage` for custom density

### Validation

- [x] Documentation-only change — no behavioral or API surface changes
- [x] Verified wording is consistent across all affected overloads
- [x] Confirm generated KDoc output renders correctly

cc @mapbox/maps-android

GitOrigin-RevId: bb6f72c95065ad19163d733caad2bfa12e71a1fb

Author: pengdev

maps-sdk/src/main/java/com/mapbox/maps/Style.kt

@@ -779,7 +779,9 @@ class Style internal constructor(
    * See [https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-fill-fill-pattern](https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-fill-fill-pattern)
    *
    * @param imageId ID of the image.
-   * @param scale Scale factor for the image.
+   * @param scale The pixel density of the provided image. The image's pixel dimensions are divided
+   * by this value to determine its display size in density-independent pixels. For example, a
+   * 100x100 pixel image with scale=2.0 will be displayed as 50x50 density-independent pixels.
    * @param image Pixel data of the image.
    * @param sdf Option to treat whether image is SDF(signed distance field) or not.
    * @param stretchX An array of two-element arrays, consisting of two numbers that represent

sdk-base/src/main/java/com/mapbox/maps/MapboxStyleManager.kt

@@ -1216,7 +1216,9 @@ open class MapboxStyleManager @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)
    * [`text-field`](https://www.mapbox.com/mapbox-gl-js/style-spec/#layout-symbol-text-field) properties.
    *
    * @param imageId An identifier of the image.
-   * @param scale A scale factor for the image.
+   * @param scale The pixel density of the provided image. The image's pixel dimensions are divided
+   * by this value to determine its display size in density-independent pixels. For example, a
+   * 100x100 pixel image with scale=2.0 will be displayed as 50x50 density-independent pixels.
    * @param image A pixel data of the image.
    * @param sdf An option to treat whether image is SDF(signed distance field) or not.
    * @param stretchX An array of two-element arrays, consisting of two numbers that represent
@@ -1541,6 +1543,10 @@ open class MapboxStyleManager @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)
    * See [https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-line-line-pattern](https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-line-line-pattern)
    * See [https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-fill-fill-pattern](https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-fill-fill-pattern)
    *
+   * The image's pixel dimensions are assumed to match the device's screen density. They are divided
+   * by the screen density to determine the display size in density-independent pixels. To add an
+   * image with a different density, use [addStyleImage] with an explicit scale parameter.
+   *
    * @param imageId ID of the image.
    * @param image Pixel data of the image.
    * @param sdf Option to treat whether image is SDF(signed distance field) or not.
@@ -1566,6 +1572,10 @@ open class MapboxStyleManager @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)
    * See [https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-line-line-pattern](https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-line-line-pattern)
    * See [https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-fill-fill-pattern](https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-fill-fill-pattern)
    *
+   * The image's pixel dimensions are assumed to match the device's screen density. They are divided
+   * by the screen density to determine the display size in density-independent pixels. To add an
+   * image with a different density, use [addStyleImage] with an explicit scale parameter.
+   *
    * @param imageId ID of the image.
    * @param image Pixel data of the image.
    *
@@ -1588,6 +1598,10 @@ open class MapboxStyleManager @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)
    * See [https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-line-line-pattern](https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-line-line-pattern)
    * See [https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-fill-fill-pattern](https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-fill-fill-pattern)
    *
+   * The bitmap's pixel dimensions are assumed to match the device's screen density. They are divided
+   * by the screen density to determine the display size in density-independent pixels. To add an
+   * image with a different density, use [addStyleImage] with an explicit scale parameter.
+   *
    * @param imageId ID of the image.
    * @param bitmap The bitmap image.
    * @param sdf Option to treat whether image is SDF(signed distance field) or not.
@@ -1619,6 +1633,10 @@ open class MapboxStyleManager @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)
    * See [https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-line-line-pattern](https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-line-line-pattern)
    * See [https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-fill-fill-pattern](https://www.mapbox.com/mapbox-gl-js/style-spec/#paint-fill-fill-pattern)
    *
+   * The bitmap's pixel dimensions are assumed to match the device's screen density. They are divided
+   * by the screen density to determine the display size in density-independent pixels. To add an
+   * image with a different density, use [addStyleImage] with an explicit scale parameter.
+   *
    * @param imageId ID of the image.
    * @param bitmap The bitmap image.
    *