update doc comments with new usage

processor/baggage/lib/opentelemetry/processor/baggage/baggage_span_processor.rb

@@ -14,24 +14,30 @@ module Baggage
       ALLOW_ALL_BAGGAGE_KEYS = ->(_) { true }
 
       # The BaggageSpanProcessor reads key/values stored in Baggage in the
-      # starting span's parent context and adds them as attributes to the span.
+      # starting span's parent context and adds them as attributes to the span,
+      # if a key matches a provided predicate lambda.
       #
       # Keys and values added to Baggage will appear on all subsequent child spans
       # for a trace within this service *and* will be propagated to external services
       # via propagation headers. If the external services also have a Baggage span
-      # processor, the keys and values will appear in those child spans as well.
+      # processor, the keys and values will appear in those child spans as well provided
+      # that the keys match any predicate method configured there.
       #
       # ⚠️
       # To repeat: a consequence of adding data to Baggage is that the keys and
       # values will appear in all outgoing HTTP headers from the application.
       # Do not put sensitive information in Baggage.
       # ⚠️
       #
-      # @example
+      # @example Adding the BaggageSpanProcessor to the SDK, only add attributes for keys that start with 'myapp.'
+      #   OUR_BAGGAGE_KEY_PREFIX = 'myapp.'.freeze
+      #
       #   OpenTelemetry::SDK.configure do |c|
       #     # Add the BaggageSpanProcessor to the collection of span processors
-      #     c.add_span_processor(OpenTelemetry::Processor::Baggage::BaggageSpanProcessor.new(
-      #       OpenTelemetry::Processor::Baggage::ALLOW_ALL_BAGGAGE_KEYS)
+      #     c.add_span_processor(
+      #       OpenTelemetry::Processor::Baggage::BaggageSpanProcessor.new(
+      #         ->(key) { key.start_with?(OUR_BAGGAGE_KEY_PREFIX) } # a constant here improves performance
+      #       )
       #     )
       #
       #     # Because the span processor list is no longer empty, the SDK will not use the
@@ -46,12 +52,24 @@ module Baggage
       #       )
       #     )
       #   end
+      #
+      # @example Allow all Baggage keys to be added to the span as attributes
+      #   OpenTelemetry::Processor::Baggage::BaggageSpanProcessor.new(
+      #     # This processor provides a convenience predicate that allows all keys to be added as attributes.
+      #     OpenTelemetry::Processor::Baggage::ALLOW_ALL_BAGGAGE_KEYS
+      #   )
       class BaggageSpanProcessor < OpenTelemetry::SDK::Trace::SpanProcessor
         # Create a new BaggageSpanProcessor that reads Baggage keys and values from the parent context
         # and adds them as attributes to the span.
         #
-        # @param [lambda] baggage_key_predicate A lambda that takes a baggage key and returns true if
+        # @param [lambda] baggage_key_predicate A lambda that takes a baggage key [String] and returns true if
         #  the key should be added to the span as an attribute, false otherwise.
+        #
+        # @example Only add attributes for keys that start with a specific prefix
+        #   OUR_BAGGAGE_KEY_PREFIX = 'myapp.'.freeze
+        #   OpenTelemetry::Processor::Baggage::BaggageSpanProcessor.new(
+        #     ->(key) { key.start_with?(OUR_BAGGAGE_KEY_PREFIX) } # a constant here improves performance
+        #   )
         def initialize(baggage_key_predicate)
           raise ArgumentError, 'baggage_key_predicate must respond to :call (lambda/Proc)' unless baggage_key_predicate.respond_to?(:call)