otelzap: Add package documentation

bridges/otelzap/core.go

@@ -2,7 +2,36 @@
 // SPDX-License-Identifier: Apache-2.0
 
 // Package otelzap provides a bridge between the [go.uber.org/zap] and
-// OpenTelemetry logging.
+// [OpenTelemetry].
+
+// # Record Conversion
+//
+// The [zapcore.Entry] and [zapcore.Field] are converted to OpenTelemetry [log.Record] in the following
+// way:
+//
+//   - Time is set as the Timestamp.
+//   - Message is set as the Body using a [log.StringValue].
+//   - Level is transformed and set as the Severity. The SeverityText is also
+//     set.
+//   - Fields are transformed and set as the Attributes.
+//   - Field value of type `context.Context` is used as context when emitting log records.
+//   - For named loggers, LoggerName is used to access [log.Logger] from [log.LoggerProvider]
+
+//
+// The Level is transformed to the OpenTelemetry Severity types in the following way.
+//
+//   - [zapcore.DebugLevel] is transformed to [log.SeverityDebug]
+//   - [zapcore.InfoLevel] is transformed to [log.SeverityInfo]
+//   - [zapcore.WarnLevel] is transformed to [log.SeverityWarn]
+//   - [zapcore.ErrorLevel] is transformed to [log.SeverityError]
+//   - [zapcore.DPanicLevel] is transformed to [log.SeverityFatal1]
+//   - [zapcore.PanicLevel] is transformed to [log.SeverityFatal2]
+//   - [zapcore.FatalLevel] is transformed to [log.SeverityFatal3]
+//
+// Fields are transformed based on their type into log attributes, or into a string value if there is no matching type.
+//
+// [OpenTelemetry]: https://opentelemetry.io/docs/concepts/signals/logs/
+
 package otelzap // import "go.opentelemetry.io/contrib/bridges/otelzap"
 
 import (

bridges/otelzap/example_test.go

@@ -4,6 +4,7 @@
 package otelzap_test
 
 import (
+	"context"
 	"os"
 
 	"go.opentelemetry.io/contrib/bridges/otelzap"
@@ -24,6 +25,10 @@ func Example() {
 
 	// You can now use your logger in your code.
 	logger.Info("something really cool")
+
+	// You can set context for trace correlation using zap.Any or zap.Reflect
+	ctx := context.Background()
+	logger.Info("setting context", zap.Any("context", ctx))
 }
 
 func Example_multiple() {