lib/opentelemetry/context/propagation.rb in opentelemetry-api-0.16.0 vs lib/opentelemetry/context/propagation.rb in opentelemetry-api-0.17.0

@@ -2,21 +2,51 @@
 
 # Copyright The OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
 
-require 'opentelemetry/context/propagation/composite_propagator'
-require 'opentelemetry/context/propagation/noop_extractor'
-require 'opentelemetry/context/propagation/noop_injector'
-require 'opentelemetry/context/propagation/propagator'
+require 'opentelemetry/context/propagation/composite_text_map_propagator'
+require 'opentelemetry/context/propagation/noop_text_map_propagator'
+require 'opentelemetry/context/propagation/rack_env_getter'
 require 'opentelemetry/context/propagation/text_map_getter'
+require 'opentelemetry/context/propagation/text_map_propagator'
 require 'opentelemetry/context/propagation/text_map_setter'
-require 'opentelemetry/context/propagation/rack_env_getter'
 
 module OpenTelemetry
   class Context
     # The propagation module contains APIs and utilities to interact with context
     # and propagate across process boundaries.
+    #
+    # The API implicitly defines 3 interfaces: TextMapPropagator, TextMapInjector
+    # and TextMapExtractor. Concrete implementations of TextMapPropagator are
+    # provided. Custom text map propagators can leverage these implementations
+    # or simply implement the expected interface. The interfaces are described
+    # below.
+    #
+    # The TextMapPropagator interface:
+    #
+    #    inject(carrier, context:, setter:)
+    #    extract(carrier, context:, getter:) -> Context
+    #    fields -> Array<String>
+    #
+    # The TextMapInjector interface:
+    #
+    #    inject(carrier, context:, setter:)
+    #    fields -> Array<String>
+    #
+    # The TextMapExtractor interface:
+    #
+    #    extract(carrier, context:, getter:) -> Context
+    #
+    # The API provides 3 TextMapPropagator implementations:
+    # - A default NoopTextMapPropagator that implements +inject+ and +extract+
+    #   methods as no-ops. Its +fields+ method returns an empty list.
+    # - A TextMapPropagator that composes an Injector and an Extractor. Its
+    #   +fields+ method delegates to the provided Injector.
+    # - A CompositeTextMapPropagator that wraps either a list of text map
+    #   propagators or a list of Injectors and a list of Extractors. Its
+    #   +fields+ method returns the union of fields returned by the Injectors
+    #   it wraps.
     module Propagation
       extend self
 
       TEXT_MAP_GETTER = TextMapGetter.new
       TEXT_MAP_SETTER = TextMapSetter.new