Do not discourage direct usage of Logs API (#6675)

Fixes #6572

## What

- Update documentation in `log/doc.go`.
- Fix naming of the Logs API in several documentation files `(Logs
Bridge API -> Logs API)`.

---------

Co-authored-by: Robert Pająk <[email protected]>
Co-authored-by: Damien Mathieu <[email protected]>

Author: 3 people

log/doc.go

@@ -4,10 +4,19 @@
 /*
 Package log provides the OpenTelemetry Logs API.
 
-This package is intended to be used by bridges between existing logging
-libraries and OpenTelemetry. Users should not directly use this package as a
-logging library. Instead, install one of the bridges listed in the
-[registry], and use the associated logging library.
+This API is separate from its implementation so the instrumentation built from
+it is reusable. See [go.opentelemetry.io/otel/sdk/log] for the official
+OpenTelemetry implementation of this API.
+
+The log package provides the OpenTelemetry Logs API, which serves as a standard
+interface for generating and managing log records within the OpenTelemetry ecosystem.
+This package allows users to emit LogRecords, enabling structured, context-rich logging
+that can be easily integrated with observability tools. It ensures that log data is captured
+in a way that is consistent with OpenTelemetry's data model.
+
+This package can be used to create bridges between existing logging libraries and OpenTelemetry.
+Log bridges allow integrating the existing logging setups with OpenTelemetry.
+Log bridges can be found in the [registry].
 
 # API Implementations
 

log/embedded/embedded.go

@@ -4,33 +4,33 @@
 // Package embedded provides interfaces embedded within the [OpenTelemetry Logs
 // Bridge API].
 //
-// Implementers of the [OpenTelemetry Logs Bridge API] can embed the relevant
+// Implementers of the [OpenTelemetry Logs API] can embed the relevant
 // type from this package into their implementation directly. Doing so will
 // result in a compilation error for users when the [OpenTelemetry Logs Bridge
 // API] is extended (which is something that can happen without a major version
 // bump of the API package).
 //
-// [OpenTelemetry Logs Bridge API]: https://pkg.go.dev/go.opentelemetry.io/otel/log
+// [OpenTelemetry Logs API]: https://pkg.go.dev/go.opentelemetry.io/otel/log
 package embedded // import "go.opentelemetry.io/otel/log/embedded"
 
-// LoggerProvider is embedded in the [Logs Bridge API LoggerProvider].
+// LoggerProvider is embedded in the [Logs API LoggerProvider].
 //
-// Embed this interface in your implementation of the [Logs Bridge API
+// Embed this interface in your implementation of the [Logs API
 // LoggerProvider] if you want users to experience a compilation error,
 // signaling they need to update to your latest implementation, when the [Logs
 // Bridge API LoggerProvider] interface is extended (which is something that
 // can happen without a major version bump of the API package).
 //
-// [Logs Bridge API LoggerProvider]: https://pkg.go.dev/go.opentelemetry.io/otel/log#LoggerProvider
+// [Logs API LoggerProvider]: https://pkg.go.dev/go.opentelemetry.io/otel/log#LoggerProvider
 type LoggerProvider interface{ loggerProvider() }
 
-// Logger is embedded in [Logs Bridge API Logger].
+// Logger is embedded in [Logs API Logger].
 //
-// Embed this interface in your implementation of the [Logs Bridge API Logger]
+// Embed this interface in your implementation of the [Logs API Logger]
 // if you want users to experience a compilation error, signaling they need to
-// update to your latest implementation, when the [Logs Bridge API Logger]
+// update to your latest implementation, when the [Logs API Logger]
 // interface is extended (which is something that can happen without a major
 // version bump of the API package).
 //
-// [Logs Bridge API Logger]: https://pkg.go.dev/go.opentelemetry.io/otel/log#Logger
+// [Logs API Logger]: https://pkg.go.dev/go.opentelemetry.io/otel/log#Logger
 type Logger interface{ logger() }

log/global/log.go

@@ -3,7 +3,7 @@
 
 /*
 Package global provides access to a global implementation of the OpenTelemetry
-Logs Bridge API.
+Logs API.
 
 This package is experimental. It will be deprecated and removed when the [log]
 package becomes stable. Its functionality will be migrated to

log/noop/noop.go

@@ -4,14 +4,14 @@
 // Package noop provides an implementation of the [OpenTelemetry Logs Bridge
 // API] that produces no telemetry and minimizes used computation resources.
 //
-// Using this package to implement the [OpenTelemetry Logs Bridge API] will
+// Using this package to implement the [OpenTelemetry Logs API] will
 // effectively disable OpenTelemetry.
 //
 // This implementation can be embedded in other implementations of the
-// [OpenTelemetry Logs Bridge API]. Doing so will mean the implementation
+// [OpenTelemetry Logs API]. Doing so will mean the implementation
 // defaults to no operation for methods it does not implement.
 //
-// [OpenTelemetry Logs Bridge API]: https://pkg.go.dev/go.opentelemetry.io/otel/log
+// [OpenTelemetry Logs API]: https://pkg.go.dev/go.opentelemetry.io/otel/log
 package noop // import "go.opentelemetry.io/otel/log/noop"
 
 import (

sdk/log/doc.go

@@ -31,6 +31,6 @@ is being run on. That way when multiple instances of the code are collected
 at a single endpoint their origin is decipherable.
 
 See [go.opentelemetry.io/otel/log] for more information about
-the OpenTelemetry Logs Bridge API.
+the OpenTelemetry Logs API.
 */
 package log // import "go.opentelemetry.io/otel/sdk/log"