Add documentation on native format

lib/datadog/tracing/span_event.rb

@@ -36,12 +36,20 @@ def initialize(
         @time_unix_nano = time_unix_nano || (Time.now.to_r * 1_000_000_000).to_i
       end
 
+      # Converts the span event into a hash to be used by with the span tag serialization
+      # (`span.set_tag('events) = [event.to_hash]`). This serialization format has the drawback
+      # of being limiting span events to the size limit of a span tag.
+      # All Datadog agents support this format.
       def to_hash
         h = { 'name' => @name, 'time_unix_nano' => @time_unix_nano }
         h['attributes'] = @attributes unless @attributes.empty?
         h
       end
 
+      # Converts the span event into a hash to be used by the MessagePack serialization as a
+      # top-level span field (span.span_events = [event.to_native_format]).
+      # This serialization format removes the serialization limitations of the `span.set_tag('events)` approach,
+      # but is only supported by newer version of the Datadog agent.
       def to_native_format
         h = { 'name' => @name, 'time_unix_nano' => @time_unix_nano }
 

lib/datadog/tracing/transport/serializable_trace.rb

@@ -12,6 +12,8 @@ class SerializableTrace
         attr_reader \
           :trace
 
+        # @param trace [Datadog::Trace] the trace to serialize
+        # @param native_events_supported [Boolean] whether the agent supports span events as a top-level field
         def initialize(trace, native_events_supported = false)
           @trace = trace
           @native_events_supported = native_events_supported
@@ -42,6 +44,8 @@ class SerializableSpan
         attr_reader \
           :span
 
+        # @param span [Datadog::Span] the span to serialize
+        # @param native_events_supported [Boolean] whether the agent supports span events as a top-level field
         def initialize(span, native_events_supported)
           @span = span
           @trace_id = Tracing::Utils::TraceId.to_low_order(span.trace_id)