Improve metrics API javadoc (#4493)

* Improve metrics API javadoc

* Fix typo

* Switch to Title Case for instrument names

* Add @SInCE annotations

api/all/src/main/java/io/opentelemetry/api/internal/ValidationUtil.java

@@ -70,7 +70,7 @@ public static boolean checkValidInstrumentName(String name, String logSuffix) {
     log(
         "Instrument name \""
             + name
-            + "\" is invalid, returning noop instrument. Instrument names must consist of 63 or less characters including alphanumeric, _, ., -, and start with a letter."
+            + "\" is invalid, returning noop instrument. Instrument names must consist of 63 or fewer characters including alphanumeric, _, ., -, and start with a letter."
             + logSuffix,
         Level.WARNING);
     return false;
@@ -95,7 +95,7 @@ public static boolean checkValidInstrumentUnit(String unit, String logSuffix) {
     log(
         "Unit \""
             + unit
-            + "\" is invalid. Instrument unit must be 63 or less ASCII characters."
+            + "\" is invalid. Instrument unit must be 63 or fewer ASCII characters."
             + logSuffix,
         Level.WARNING);
     return false;

api/all/src/main/java/io/opentelemetry/api/metrics/BatchCallback.java

@@ -8,6 +8,8 @@
 /**
  * A reference to a batch callback registered via {@link Meter#batchCallback(Runnable,
  * ObservableMeasurement, ObservableMeasurement...)}.
+ *
+ * @since 1.15.0
  */
 public interface BatchCallback extends AutoCloseable {
 

api/all/src/main/java/io/opentelemetry/api/metrics/DefaultMeter.java

@@ -12,26 +12,9 @@
 import javax.annotation.concurrent.ThreadSafe;
 
 /**
- * No-op implementations of {@link Meter}.
+ * No-op implementation of {@link Meter}.
  *
  * <p>This implementation should induce as close to zero overhead as possible.
- *
- * <p>A few notes from the specification on allowed behaviors leading to this design [<a
- * href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument">Instrument
- * Spec</a>]:
- *
- * <ul>
- *   <li>Multiple Instruments with the same name under the same Meter MUST return an error
- *   <li>Different Meters MUST be treated as separate namespaces
- *   <li>Implementations MUST NOT require users to repeatedly obtain a Meter again with the same
- *       name+version+schema_url to pick up configuration changes. This can be achieved either by
- *       allowing to work with an outdated configuration or by ensuring that new configuration
- *       applies also to previously returned Meters.
- *   <li>A MeterProvider could also return a no-op Meter here if application owners configure the
- *       SDK to suppress telemetry produced by this library
- *   <li>In case an invalid name (null or empty string) is specified, a working Meter implementation
- *       MUST be returned as a fallback rather than returning null or throwing an exception,
- * </ul>
  */
 @ThreadSafe
 class DefaultMeter implements Meter {

api/all/src/main/java/io/opentelemetry/api/metrics/DoubleCounter.java

@@ -9,7 +9,11 @@
 import io.opentelemetry.context.Context;
 import javax.annotation.concurrent.ThreadSafe;
 
-/** A counter instrument that records {@code double} values. */
+/**
+ * A Counter instrument that records {@code double} values.
+ *
+ * @since 1.10.0
+ */
 @ThreadSafe
 public interface DoubleCounter {
   /**
@@ -29,15 +33,15 @@ public interface DoubleCounter {
    * measurement.
    *
    * @param value The increment amount. MUST be non-negative.
-   * @param attributes A set of attributes to associate with the count.
+   * @param attributes A set of attributes to associate with the value.
    */
   void add(double value, Attributes attributes);
 
   /**
    * Records a value with a set of attributes.
    *
    * @param value The increment amount. MUST be non-negative.
-   * @param attributes A set of attributes to associate with the count.
+   * @param attributes A set of attributes to associate with the value.
    * @param context The explicit context to associate with this measurement.
    */
   void add(double value, Attributes attributes, Context context);

api/all/src/main/java/io/opentelemetry/api/metrics/DoubleCounterBuilder.java

@@ -7,45 +7,52 @@
 
 import java.util.function.Consumer;
 
-/** Builder class for {@link DoubleCounter}. */
+/**
+ * Builder class for {@link DoubleCounter}.
+ *
+ * @since 1.10.0
+ */
 public interface DoubleCounterBuilder {
   /**
    * Sets the description for this instrument.
    *
-   * <p>Description strings should follow the instrument description rules:
-   * https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description
+   * @param description The description.
+   * @see <a
+   *     href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description">Instrument
+   *     Description</a>
    */
   DoubleCounterBuilder setDescription(String description);
 
   /**
    * Sets the unit of measure for this instrument.
    *
-   * <p>Unit strings should follow the instrument unit rules:
-   * https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit
+   * @param unit The unit. Instrument units must be 63 or fewer ASCII characters.
+   * @see <a
+   *     href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit">Instrument
+   *     Unit</a>
    */
   DoubleCounterBuilder setUnit(String unit);
 
   /**
-   * Builds and returns a {@code DoubleCounter} with the desired options.
+   * Builds and returns a Counter instrument with the configuration.
    *
-   * @return a {@code DoubleCounter} with the desired options.
+   * @return The Counter instrument.
    */
   DoubleCounter build();
 
   /**
-   * Builds this asynchronous instrument with the given callback.
+   * Builds an Asynchronous Counter instrument with the given callback.
    *
-   * <p>The callback will be called when the {@link Meter} is being observed.
+   * <p>The callback will be called when the instrument is being observed.
    *
    * <p>Callbacks are expected to abide by the following restrictions:
    *
    * <ul>
    *   <li>Run in a finite amount of time.
    *   <li>Safe to call repeatedly, across multiple threads.
-   *   <li>Return positive, monotonically increasing values.
    * </ul>
    *
-   * @param callback A state-capturing callback used to observe values on-demand.
+   * @param callback A callback which observes measurements when invoked.
    */
   ObservableDoubleCounter buildWithCallback(Consumer<ObservableDoubleMeasurement> callback);
 
@@ -57,6 +64,7 @@ public interface DoubleCounterBuilder {
    * observed outside registered callbacks are ignored.
    *
    * @return an observable measurement that batch callbacks use to observe values.
+   * @since 1.15.0
    */
   default ObservableDoubleMeasurement buildObserver() {
     return DefaultMeter.getInstance().counterBuilder("noop").ofDoubles().buildObserver();

api/all/src/main/java/io/opentelemetry/api/metrics/DoubleGaugeBuilder.java

@@ -7,31 +7,39 @@
 
 import java.util.function.Consumer;
 
-/** A builder for Gauge metric types. These can only be asynchronously collected. */
+/**
+ * A builder for Gauge metric types. These can only be asynchronously collected.
+ *
+ * @since 1.10.0
+ */
 public interface DoubleGaugeBuilder {
   /**
    * Sets the description for this instrument.
    *
-   * <p>Description strings should follow the instrument description rules:
-   * https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description
+   * @param description The description.
+   * @see <a
+   *     href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description">Instrument
+   *     Description</a>
    */
   DoubleGaugeBuilder setDescription(String description);
 
   /**
    * Sets the unit of measure for this instrument.
    *
-   * <p>Unit strings should follow the instrument unit rules:
-   * https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit
+   * @param unit The unit. Instrument units must be 63 or fewer ASCII characters.
+   * @see <a
+   *     href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit">Instrument
+   *     Unit</a>
    */
   DoubleGaugeBuilder setUnit(String unit);
 
-  /** Sets the gauge for recording {@code long} values. */
+  /** Sets the Gauge for recording {@code long} values. */
   LongGaugeBuilder ofLongs();
 
   /**
-   * Builds this asynchronous instrument with the given callback.
+   * Builds an Asynchronous Gauge instrument with the given callback.
    *
-   * <p>The callback will be called when the {@link Meter} is being observed.
+   * <p>The callback will be called when the instrument is being observed.
    *
    * <p>Callbacks are expected to abide by the following restrictions:
    *
@@ -40,7 +48,7 @@ public interface DoubleGaugeBuilder {
    *   <li>Safe to call repeatedly, across multiple threads.
    * </ul>
    *
-   * @param callback A state-capturing callback used to observe values on-demand.
+   * @param callback A callback which observes measurements when invoked.
    */
   ObservableDoubleGauge buildWithCallback(Consumer<ObservableDoubleMeasurement> callback);
 
@@ -52,6 +60,7 @@ public interface DoubleGaugeBuilder {
    * observed outside registered callbacks are ignored.
    *
    * @return an observable measurement that batch callbacks use to observe values.
+   * @since 1.15.0
    */
   default ObservableDoubleMeasurement buildObserver() {
     return DefaultMeter.getInstance().gaugeBuilder("noop").buildObserver();

api/all/src/main/java/io/opentelemetry/api/metrics/DoubleHistogram.java

@@ -9,7 +9,11 @@
 import io.opentelemetry.context.Context;
 import javax.annotation.concurrent.ThreadSafe;
 
-/** A histogram instrument that records {@code long} values. */
+/**
+ * A Histogram instrument that records {@code double} values.
+ *
+ * @since 1.10.0
+ */
 @ThreadSafe
 public interface DoubleHistogram {
 
@@ -19,7 +23,7 @@ public interface DoubleHistogram {
    * <p>Note: This may use {@code Context.current()} to pull the context associated with this
    * measurement.
    *
-   * @param value The amount of the measurement.
+   * @param value The amount of the measurement. MUST be non-negative.
    */
   void record(double value);
 
@@ -29,16 +33,16 @@ public interface DoubleHistogram {
    * <p>Note: This may use {@code Context.current()} to pull the context associated with this
    * measurement.
    *
-   * @param value The amount of the measurement.
-   * @param attributes A set of attributes to associate with the count.
+   * @param value The amount of the measurement. MUST be non-negative.
+   * @param attributes A set of attributes to associate with the value.
    */
   void record(double value, Attributes attributes);
 
   /**
    * Records a value with a set of attributes.
    *
-   * @param value The amount of the measurement.
-   * @param attributes A set of attributes to associate with the count.
+   * @param value The amount of the measurement. MUST be non-negative.
+   * @param attributes A set of attributes to associate with the value.
    * @param context The explicit context to associate with this measurement.
    */
   void record(double value, Attributes attributes, Context context);

api/all/src/main/java/io/opentelemetry/api/metrics/DoubleHistogramBuilder.java

@@ -5,32 +5,40 @@
 
 package io.opentelemetry.api.metrics;
 
-/** Builder class for {@link DoubleHistogram}. */
+/**
+ * Builder class for {@link DoubleHistogram}.
+ *
+ * @since 1.10.0
+ */
 public interface DoubleHistogramBuilder {
 
   /**
    * Sets the description for this instrument.
    *
-   * <p>Description strings should follow the instrument description rules:
-   * https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description
+   * @param description The description.
+   * @see <a
+   *     href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description">Instrument
+   *     Description</a>
    */
   DoubleHistogramBuilder setDescription(String description);
 
   /**
    * Sets the unit of measure for this instrument.
    *
-   * <p>Unit strings should follow the instrument unit rules:
-   * https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit
+   * @param unit The unit. Instrument units must be 63 or fewer ASCII characters.
+   * @see <a
+   *     href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit">Instrument
+   *     Unit</a>
    */
   DoubleHistogramBuilder setUnit(String unit);
 
-  /** Sets the counter for recording {@code long} values. */
+  /** Sets the Counter for recording {@code long} values. */
   LongHistogramBuilder ofLongs();
 
   /**
-   * Builds and returns a {@code DoubleHistogram} with the desired options.
+   * Builds and returns a Histogram instrument with the configuration.
    *
-   * @return a {@code DoubleHistogram} with the desired options.
+   * @return The Histogram instrument.
    */
   DoubleHistogram build();
 }

api/all/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounter.java

@@ -9,7 +9,11 @@
 import io.opentelemetry.context.Context;
 import javax.annotation.concurrent.ThreadSafe;
 
-/** An up-down-counter instrument that records {@code double} values. */
+/**
+ * An UpDownCounter instrument that records {@code double} values.
+ *
+ * @since 1.10.0
+ */
 @ThreadSafe
 public interface DoubleUpDownCounter {
   /**
@@ -29,15 +33,15 @@ public interface DoubleUpDownCounter {
    * measurement.
    *
    * @param value The increment amount. May be positive, negative or zero.
-   * @param attributes A set of attributes to associate with the count.
+   * @param attributes A set of attributes to associate with the value.
    */
   void add(double value, Attributes attributes);
 
   /**
    * Records a value with a set of attributes.
    *
    * @param value The increment amount. May be positive, negative or zero.
-   * @param attributes A set of attributes to associate with the count.
+   * @param attributes A set of attributes to associate with the value.
    * @param context The explicit context to associate with this measurement.
    */
   void add(double value, Attributes attributes, Context context);