Update the package docs for the new API layout (#1346)

baggage/doc.go

@@ -0,0 +1,24 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/*
+Package baggage provides functionality for storing and retrieving
+baggage items in Go context. For propagating the baggage, see the
+go.opentelemetry.io/otel/propagation package.
+
+This package is currently in a pre-GA phase. Backwards incompatible changes
+may be introduced in subsequent minor version releases as we work to track the
+evolving OpenTelemetry specification and user feedback.
+*/
+package baggage // import "go.opentelemetry.io/otel/baggage"

codes/codes.go

@@ -12,14 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package codes defines the canonical error codes used by OpenTelemetry.
-//
-// This package is currently in a pre-GA phase. Backwards incompatible changes
-// may be introduced in subsequent minor version releases as we work to track
-// the evolving OpenTelemetry specification and user feedback.
-//
-// It conforms to [the OpenTelemetry
-// specification](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#statuscanonicalcode).
 package codes // import "go.opentelemetry.io/otel/codes"
 
 import (

codes/doc.go

@@ -0,0 +1,25 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/*
+Package codes defines the canonical error codes used by OpenTelemetry.
+
+This package is currently in a pre-GA phase. Backwards incompatible changes
+may be introduced in subsequent minor version releases as we work to track
+the evolving OpenTelemetry specification and user feedback.
+
+It conforms to [the OpenTelemetry
+specification](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#statuscanonicalcode).
+*/
+package codes // import "go.opentelemetry.io/otel/codes"

doc.go

@@ -12,9 +12,25 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package global provides global providers, propagators and more.
-//
-// This package is currently in a pre-GA phase. Backwards incompatible changes
-// may be introduced in subsequent minor version releases as we work to track
-// the evolving OpenTelemetry specification and user feedback.
+/*
+Package otel provides global access to the OpenTelemetry API. The subpackages of
+the otel package provide an implementation of the OpenTelemetry API.
+
+This package is currently in a pre-GA phase. Backwards incompatible changes
+may be introduced in subsequent minor version releases as we work to track the
+evolving OpenTelemetry specification and user feedback.
+
+The provided API is used to instrument code and measure data about that code's
+performance and operation. The measured data, by default, is not processed or
+transmitted anywhere. An implementation of the OpenTelemetry SDK, like the
+default SDK implementation (go.opentelemetry.io/otel/sdk), and associated
+exporters are used to process and transport this data.
+
+To read more about tracing, see go.opentelemetry.io/otel/trace.
+
+To read more about metrics, see go.opentelemetry.io/otel/metric.
+
+To read more about propagation, see go.opentelemetry.io/otel/propagation and
+go.opentelemetry.io/otel/baggage.
+*/
 package otel // import "go.opentelemetry.io/otel"

metric/doc.go

@@ -0,0 +1,67 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/*
+Package metric provides an implementation of the metrics part of the
+OpenTelemetry API.
+
+This package is currently in a pre-GA phase. Backwards incompatible changes
+may be introduced in subsequent minor version releases as we work to track the
+evolving OpenTelemetry specification and user feedback.
+
+Measurements can be made about an operation being performed or the state of a
+system in general. These measurements can be crucial to the reliable operation
+of code and provide valuable insights about the inner workings of a system.
+
+Measurements are made using instruments provided by this package. The type of
+instrument used will depend on the type of measurement being made and of what
+part of a system is being measured.
+
+Instruments are categorized as Synchronous or Asynchronous and independently
+as Adding or Grouping. Synchronous instruments are called by the user with a
+Context. Asynchronous instruments are called by the SDK during collection.
+Additive instruments are semantically intended for capturing a sum. Grouping
+instruments are intended for capturing a distribution.
+
+Additive instruments may be monotonic, in which case they are non-decreasing
+and naturally define a rate.
+
+The synchronous instrument names are:
+
+  Counter:           additive, monotonic
+  UpDownCounter:     additive
+  ValueRecorder:     grouping
+
+and the asynchronous instruments are:
+
+  SumObserver:       additive, monotonic
+  UpDownSumObserver: additive
+  ValueObserver:     grouping
+
+All instruments are provided with support for either float64 or int64 input
+values.
+
+An instrument is created using a Meter. Additionally, a Meter is used to
+record batches of synchronous measurements or asynchronous observations. A
+Meter is obtained using a MeterProvider. A Meter, like a Tracer, is unique to
+the instrumentation it instruments and must be named and versioned when
+created with a MeterProvider with the name and version of the instrumentation
+library.
+
+Instrumentation should be designed to accept a MeterProvider from which it can
+create its own unique Meter. Alternatively, the registered global
+MeterProvider from the go.opentelemetry.io/otel package can be used as a
+default.
+*/
+package metric // import "go.opentelemetry.io/otel/metric"

metric/number/doc.go

@@ -0,0 +1,23 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/*
+Package number provides a number abstraction for instruments that
+either support int64 or float64 input values.
+
+This package is currently in a pre-GA phase. Backwards incompatible changes
+may be introduced in subsequent minor version releases as we work to track the
+evolving OpenTelemetry specification and user feedback.
+*/
+package number // import "go.opentelemetry.io/otel/metric/number"

metric/registry/doc.go

@@ -0,0 +1,24 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/*
+Package registry provides a non-standalone implementation of
+MeterProvider that adds uniqueness checking for instrument descriptors
+on top of other MeterProvider it wraps.
+
+This package is currently in a pre-GA phase. Backwards incompatible changes
+may be introduced in subsequent minor version releases as we work to track the
+evolving OpenTelemetry specification and user feedback.
+*/
+package registry // import "go.opentelemetry.io/otel/metric/registry"

trace/doc.go

@@ -0,0 +1,70 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/*
+Package trace provides an implementation of the tracing part of the
+OpenTelemetry API.
+
+This package is currently in a pre-GA phase. Backwards incompatible changes
+may be introduced in subsequent minor version releases as we work to track the
+evolving OpenTelemetry specification and user feedback.
+
+To participate in distributed traces a Span needs to be created for the
+operation being performed as part of a traced workflow. It its simplest form:
+
+	var tracer trace.Tracer
+
+	func init() {
+		tracer = otel.Tracer("instrumentation/package/name")
+	}
+
+	func operation(ctx context.Context) {
+		var span trace.Span
+		ctx, span = tracer.Start(ctx, "operation")
+		defer span.End()
+		// ...
+	}
+
+A Tracer is unique to the instrumentation and is used to create Spans.
+Instrumentation should be designed to accept a TracerProvider from which it
+can create its own unique Tracer. Alternatively, the registered global
+TracerProvider from the go.opentelemetry.io/otel package can be used as
+a default.
+
+	const (
+		name    = "instrumentation/package/name"
+		version = "0.1.0"
+	)
+
+	type Instrumentation struct {
+		tracer trace.Tracer
+	}
+
+	func NewInstrumentation(tp trace.TracerProvider) *Instrumentation {
+		if tp == nil {
+			tp = otel.TracerProvider()
+		}
+		return &Instrumentation{
+			tracer: tp.Tracer(name, trace.WithInstrumentationVersion(version)),
+		}
+	}
+
+	func operation(ctx context.Context, inst *Instrumentation) {
+		var span trace.Span
+		ctx, span = inst.tracer.Start(ctx, "operation")
+		defer span.End()
+		// ...
+	}
+*/
+package trace // import "go.opentelemetry.io/otel/trace"