From 7707ce3d4f90b2d97d2ce6f287d74d46a83036ae Mon Sep 17 00:00:00 2001
From: Wisdom Matthew <40186491+wisdommatt@users.noreply.github.com>
Date: Sun, 6 Nov 2022 15:59:23 +0100
Subject: [PATCH] docs(metric): document public interfaces with versioning
 policy (#3441)

* docs(metric): document public interfaces with versioning policy

* docs(metric): remove versioning policy warning from interfaces without public method(s)
---
 metric/instrument/asyncfloat64/asyncfloat64.go | 8 ++++++++
 metric/instrument/asyncint64/asyncint64.go     | 8 ++++++++
 metric/instrument/syncfloat64/syncfloat64.go   | 8 ++++++++
 metric/instrument/syncint64/syncint64.go       | 8 ++++++++
 metric/meter.go                                | 4 ++++
 5 files changed, 36 insertions(+)

diff --git a/metric/instrument/asyncfloat64/asyncfloat64.go b/metric/instrument/asyncfloat64/asyncfloat64.go
index 17bda2ceee1..330a14c2f64 100644
--- a/metric/instrument/asyncfloat64/asyncfloat64.go
+++ b/metric/instrument/asyncfloat64/asyncfloat64.go
@@ -22,6 +22,8 @@ import (
 )
 
 // InstrumentProvider provides access to individual instruments.
+//
+// Warning: methods may be added to this interface in minor releases.
 type InstrumentProvider interface {
 	// Counter creates an instrument for recording increasing values.
 	Counter(name string, opts ...instrument.Option) (Counter, error)
@@ -34,6 +36,8 @@ type InstrumentProvider interface {
 }
 
 // Counter is an instrument that records increasing values.
+//
+// Warning: methods may be added to this interface in minor releases.
 type Counter interface {
 	// Observe records the state of the instrument to be x. Implementations
 	// will assume x to be the cumulative sum of the count.
@@ -47,6 +51,8 @@ type Counter interface {
 }
 
 // UpDownCounter is an instrument that records increasing or decreasing values.
+//
+// Warning: methods may be added to this interface in minor releases.
 type UpDownCounter interface {
 	// Observe records the state of the instrument to be x. Implementations
 	// will assume x to be the cumulative sum of the count.
@@ -60,6 +66,8 @@ type UpDownCounter interface {
 }
 
 // Gauge is an instrument that records independent readings.
+//
+// Warning: methods may be added to this interface in minor releases.
 type Gauge interface {
 	// Observe records the state of the instrument to be x.
 	//
diff --git a/metric/instrument/asyncint64/asyncint64.go b/metric/instrument/asyncint64/asyncint64.go
index 1e17988e827..4fce9963c3b 100644
--- a/metric/instrument/asyncint64/asyncint64.go
+++ b/metric/instrument/asyncint64/asyncint64.go
@@ -22,6 +22,8 @@ import (
 )
 
 // InstrumentProvider provides access to individual instruments.
+//
+// Warning: methods may be added to this interface in minor releases.
 type InstrumentProvider interface {
 	// Counter creates an instrument for recording increasing values.
 	Counter(name string, opts ...instrument.Option) (Counter, error)
@@ -34,6 +36,8 @@ type InstrumentProvider interface {
 }
 
 // Counter is an instrument that records increasing values.
+//
+// Warning: methods may be added to this interface in minor releases.
 type Counter interface {
 	// Observe records the state of the instrument to be x. Implementations
 	// will assume x to be the cumulative sum of the count.
@@ -47,6 +51,8 @@ type Counter interface {
 }
 
 // UpDownCounter is an instrument that records increasing or decreasing values.
+//
+// Warning: methods may be added to this interface in minor releases.
 type UpDownCounter interface {
 	// Observe records the state of the instrument to be x. Implementations
 	// will assume x to be the cumulative sum of the count.
@@ -60,6 +66,8 @@ type UpDownCounter interface {
 }
 
 // Gauge is an instrument that records independent readings.
+//
+// Warning: methods may be added to this interface in minor releases.
 type Gauge interface {
 	// Observe records the state of the instrument to be x.
 	//
diff --git a/metric/instrument/syncfloat64/syncfloat64.go b/metric/instrument/syncfloat64/syncfloat64.go
index 435db1127bc..2ec192f70d8 100644
--- a/metric/instrument/syncfloat64/syncfloat64.go
+++ b/metric/instrument/syncfloat64/syncfloat64.go
@@ -22,6 +22,8 @@ import (
 )
 
 // InstrumentProvider provides access to individual instruments.
+//
+// Warning: methods may be added to this interface in minor releases.
 type InstrumentProvider interface {
 	// Counter creates an instrument for recording increasing values.
 	Counter(name string, opts ...instrument.Option) (Counter, error)
@@ -32,6 +34,8 @@ type InstrumentProvider interface {
 }
 
 // Counter is an instrument that records increasing values.
+//
+// Warning: methods may be added to this interface in minor releases.
 type Counter interface {
 	// Add records a change to the counter.
 	Add(ctx context.Context, incr float64, attrs ...attribute.KeyValue)
@@ -40,6 +44,8 @@ type Counter interface {
 }
 
 // UpDownCounter is an instrument that records increasing or decreasing values.
+//
+// Warning: methods may be added to this interface in minor releases.
 type UpDownCounter interface {
 	// Add records a change to the counter.
 	Add(ctx context.Context, incr float64, attrs ...attribute.KeyValue)
@@ -48,6 +54,8 @@ type UpDownCounter interface {
 }
 
 // Histogram is an instrument that records a distribution of values.
+//
+// Warning: methods may be added to this interface in minor releases.
 type Histogram interface {
 	// Record adds an additional value to the distribution.
 	Record(ctx context.Context, incr float64, attrs ...attribute.KeyValue)
diff --git a/metric/instrument/syncint64/syncint64.go b/metric/instrument/syncint64/syncint64.go
index c77a4672860..03b5d53e636 100644
--- a/metric/instrument/syncint64/syncint64.go
+++ b/metric/instrument/syncint64/syncint64.go
@@ -22,6 +22,8 @@ import (
 )
 
 // InstrumentProvider provides access to individual instruments.
+//
+// Warning: methods may be added to this interface in minor releases.
 type InstrumentProvider interface {
 	// Counter creates an instrument for recording increasing values.
 	Counter(name string, opts ...instrument.Option) (Counter, error)
@@ -32,6 +34,8 @@ type InstrumentProvider interface {
 }
 
 // Counter is an instrument that records increasing values.
+//
+// Warning: methods may be added to this interface in minor releases.
 type Counter interface {
 	// Add records a change to the counter.
 	Add(ctx context.Context, incr int64, attrs ...attribute.KeyValue)
@@ -40,6 +44,8 @@ type Counter interface {
 }
 
 // UpDownCounter is an instrument that records increasing or decreasing values.
+//
+// Warning: methods may be added to this interface in minor releases.
 type UpDownCounter interface {
 	// Add records a change to the counter.
 	Add(ctx context.Context, incr int64, attrs ...attribute.KeyValue)
@@ -48,6 +54,8 @@ type UpDownCounter interface {
 }
 
 // Histogram is an instrument that records a distribution of values.
+//
+// Warning: methods may be added to this interface in minor releases.
 type Histogram interface {
 	// Record adds an additional value to the distribution.
 	Record(ctx context.Context, incr int64, attrs ...attribute.KeyValue)
diff --git a/metric/meter.go b/metric/meter.go
index 21fc1c499fb..23e6853afbb 100644
--- a/metric/meter.go
+++ b/metric/meter.go
@@ -26,6 +26,8 @@ import (
 
 // MeterProvider provides access to named Meter instances, for instrumenting
 // an application or library.
+//
+// Warning: methods may be added to this interface in minor releases.
 type MeterProvider interface {
 	// Meter creates an instance of a `Meter` interface. The instrumentationName
 	// must be the name of the library providing instrumentation. This name may
@@ -36,6 +38,8 @@ type MeterProvider interface {
 }
 
 // Meter provides access to instrument instances for recording metrics.
+//
+// Warning: methods may be added to this interface in minor releases.
 type Meter interface {
 	// AsyncInt64 is the namespace for the Asynchronous Integer instruments.
 	//