Added missing package document and canonical import paths (#1125)

Also simplified the first lines of some package docs
to focus on what the package provides instead of
explaining the implementation details.

Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com>

api/apitest/package.go → api/apitest/doc.go

@@ -12,4 +12,5 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package apitest provides utilities for testing.
 package apitest // import "go.opentelemetry.io/otel/api/apitest"

api/correlation/doc.go

@@ -12,8 +12,5 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// This package implements the correlation functionality as specified
-// in the OpenTelemetry specification. Currently it provides a data
-// structure for storing correlations (Map) and a way of putting Map
-// object into the context and retrieving it from context.
+// Package correlation provides types and utilities for correlation features.
 package correlation // import "go.opentelemetry.io/otel/api/correlation"

api/global/doc.go

@@ -0,0 +1,16 @@
+// 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 global provides global providers, propagators and more.
+package global // import "go.opentelemetry.io/otel/api/global"

api/metric/doc.go

@@ -12,8 +12,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// metric package provides an API for reporting diagnostic
-// measurements using instruments categorized as follows:
+// Package metric provides support for reporting measurements using instruments.
+//
+// Instruments are categorized as below:
 //
 // Synchronous instruments are called by the user with a Context.
 // Asynchronous instruments are called by the SDK during collection.

api/metric/metrictest/doc.go

@@ -0,0 +1,16 @@
+// 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 metrictest contains utilities for testing metrics.
+package metrictest // import "go.opentelemetry.io/otel/api/metric/metrictest"

api/propagation/doc.go

@@ -12,5 +12,5 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package propagation contains interface definition for HTTP propagators.
+// Package propagation provides support for propagating context over HTTP.
 package propagation // import "go.opentelemetry.io/otel/api/propagation"

api/trace/doc.go

@@ -12,4 +12,5 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package trace provides tracing support.
 package trace // import "go.opentelemetry.io/otel/api/trace"

api/trace/tracetest/tracer.go

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package tracetest provides testing utilities for tracing.
 package tracetest
 
 import (

api/unit/doc.go

@@ -12,4 +12,5 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package unit provides units.
 package unit // import "go.opentelemetry.io/otel/api/unit"