api: add docstrings to core metrics instrument abstract methods

CHANGELOG.md

@@ -12,6 +12,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+- `opentelemetry-api`: Add docstrings to `Counter.add`, `UpDownCounter.add`, `Histogram.record`, and `Gauge.set` abstract methods
+  ([#4923](https://github.com/open-telemetry/opentelemetry-python/pull/4923))
+
 - `opentelemetry-sdk`: Clarify timeout units in environment variable documentation
   ([#4906](https://github.com/open-telemetry/opentelemetry-python/pull/4906))
 - `opentelemetry-exporter-otlp-proto-grpc`: Fix re-initialization of gRPC channel on UNAVAILABLE error

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):