api: add docstrings to core metrics instrument abstract methods (open-telemetry#4923)

* api: add docstrings to core metrics instrument abstract methods

Add missing docstrings to the abstract measurement methods on the four
core synchronous metric instruments:

- Counter.add      – records a non-negative increment
- UpDownCounter.add – records a positive or negative delta
- Histogram.record  – records an arbitrary statistical measurement
- Gauge.set         – records the current (non-additive) value

Each docstring explains the intent of the method, any constraints on
the  parameter, and documents all three parameters
(amount, attributes, context) using the existing Google-style format
already present in the codebase.

These methods are the primary interaction surface for developers using
the OpenTelemetry Metrics API; having no docstring on the abstract
definition makes generated API docs and IDE tooltips silent.

* Apply suggestion from @xrmx

* api: remove CHANGELOG entry per reviewer request

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

* ci: retrigger CI checks

---------

Co-authored-by: Riccardo Magliocchetti <riccardo.magliocchetti@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

opentelemetry-api/src/opentelemetry/metrics/_internal/instrument.py

@@ -183,7 +183,14 @@ def add(
         attributes: Optional[Attributes] = None,
         context: Optional[Context] = None,
     ) -> None:
-        pass
+        """Records an increment to the counter.
+
+        Args:
+            amount: The amount to increment the counter by. Must be non-negative.
+            attributes: Optional set of attributes to associate with the measurement.
+            context: Optional context to associate with the measurement. If not
+                provided, the current context is used.
+        """
 
 
 class NoOpCounter(Counter):
@@ -234,7 +241,18 @@ def add(
         attributes: Optional[Attributes] = None,
         context: Optional[Context] = None,
     ) -> None:
-        pass
+        """Records an increment or decrement to the counter.
+
+        Unlike `Counter`, the ``amount`` may be negative, allowing the
+        instrument to track values that go up and down (e.g. number of
+        active requests, queue depth).
+
+        Args:
+            amount: The amount to add to the counter. May be positive or negative.
+            attributes: Optional set of attributes to associate with the measurement.
+            context: Optional context to associate with the measurement. If not
+                provided, the current context is used.
+        """
 
 
 class NoOpUpDownCounter(UpDownCounter):
@@ -376,7 +394,20 @@ def record(
         attributes: Optional[Attributes] = None,
         context: Optional[Context] = None,
     ) -> None:
-        pass
+        """Records a measurement.
+
+        Used to report measurements that are likely to be statistically
+        meaningful, such as request durations, payload sizes, or any value
+        for which a distribution (e.g. percentiles) is useful.
+
+        Args:
+            amount: The measurement to record. Should be non-negative in most
+                cases; negative values are only meaningful when the histogram
+                is used to track signed deltas.
+            attributes: Optional set of attributes to associate with the measurement.
+            context: Optional context to associate with the measurement. If not
+                provided, the current context is used.
+        """
 
 
 class NoOpHistogram(Histogram):
@@ -486,7 +517,18 @@ def set(
         attributes: Optional[Attributes] = None,
         context: Optional[Context] = None,
     ) -> None:
-        pass
+        """Records the current value of the gauge.
+
+        The gauge reports the last recorded value when observed. It is
+        intended for non-additive measurements where only the current
+        value matters (e.g. CPU utilisation percentage, room temperature).
+
+        Args:
+            amount: The current value to record.
+            attributes: Optional set of attributes to associate with the measurement.
+            context: Optional context to associate with the measurement. If not
+                provided, the current context is used.
+        """
 
 
 class NoOpGauge(Gauge):