docs(metrics): Explain metric unit API design (#6087)

* docs(metrics): Explain metric unit API design

Document why metrics accept string units rather than reusing MeasurementUnit. This preserves the supported-unit distinction and lets older SDK versions send newly introduced units.

Co-Authored-By: Claude <noreply@anthropic.com>

* docs(metrics): Clarify unit API distinction

Distinguish units for the Metrics product from transaction and span measurement units used by mobile vitals.

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: adinauer

sentry/src/main/java/io/sentry/metrics/MetricsUnit.java

@@ -3,7 +3,13 @@
 /**
  * String constants for metric units.
  *
- * <p>These constants represent the API names of measurement units that can be used with metrics.
+ * <p>These constants are for the Metrics product and the {@link IMetricsApi} exposed through {@link
+ * io.sentry.Sentry#metrics()} and {@link io.sentry.IScopes#metrics()}. {@link
+ * io.sentry.MeasurementUnit} is instead used by transaction and span measurement APIs, including
+ * mobile vitals.
+ *
+ * <p>Metrics APIs accept strings so older SDK versions can use units introduced after their
+ * release.
  */
 public final class MetricsUnit {