Add comprehensive documentation to achieve 100% coverage. (#7)

Author: samuel-williams-shopify

lib/traces/backend/open_telemetry/interface.rb

@@ -15,11 +15,19 @@ module OpenTelemetry
 			# See <https://github.com/open-telemetry/opentelemetry-ruby> for more details.
 			TRACER = ::OpenTelemetry.tracer_provider.tracer(Traces::Backend::OpenTelemetry.name, Traces::Backend::OpenTelemetry::VERSION)
 
+			# Provides the interface implementation for OpenTelemetry tracing backend.
 			module Interface
+				# Creates a trace span with the given name and attributes.
+				# @parameter name [String] The name of the trace span.
+				# @parameter attributes [Hash | Nil] Optional attributes to attach to the span.
+				# @yields {|span| ...} The block to execute within the trace span.
+				# @returns [Object] The result of the block execution.
 				def trace(name, attributes: nil, &block)
 					TRACER.in_span(name, attributes: attributes&.transform_keys(&:to_s), &block)
 				end
 
+				# Sets the current trace context.
+				# @parameter context [Traces::Context | Nil] The trace context to set as current.
 				def trace_context=(context)
 					if context
 						span_context = ::OpenTelemetry::Trace::SpanContext.new(
@@ -36,11 +44,16 @@ def trace_context=(context)
 					end
 				end
 
+				# Checks if there is currently an active trace span.
+				# @returns [Boolean] `true` if there is an active trace span, `false` otherwise.
 				def active?
 					# Check if there's a real active trace using OpenTelemetry's INVALID span:
 					::OpenTelemetry::Trace.current_span != ::OpenTelemetry::Trace::Span::INVALID
 				end
 
+				# Gets the current trace context from the active span.
+				# @parameter span [OpenTelemetry::Trace::Span] The span to extract context from, defaults to current span.
+				# @returns [Traces::Context | Nil] The trace context, or `nil` if no active trace.
 				def trace_context(span = ::OpenTelemetry::Trace.current_span)
 					# Return nil if no active trace (using INVALID span check):
 					return nil if span == ::OpenTelemetry::Trace::Span::INVALID
@@ -62,10 +75,16 @@ def trace_context(span = ::OpenTelemetry::Trace.current_span)
 					end
 				end
 
+				# Gets the current OpenTelemetry context.
+				# @returns [OpenTelemetry::Context] The current OpenTelemetry context.
 				def current_context
 					::OpenTelemetry::Context.current
 				end
 
+				# Executes code within the given context or attaches the context.
+				# @parameter context [OpenTelemetry::Context] The context to use.
+				# @yields {|| ...} Optional block to execute within the context.
+				# @returns [Object] The result of the block if given, otherwise the detach token.
 				def with_context(context)
 					if block_given?
 						::OpenTelemetry::Context.with_current(context) do
@@ -76,6 +95,10 @@ def with_context(context)
 					end
 				end
 
+				# Injects trace context into headers for propagation.
+				# @parameter headers [Hash | Nil] Optional headers hash to inject into, defaults to new hash.
+				# @parameter context [OpenTelemetry::Context | Nil] Optional context to inject, defaults to current context.
+				# @returns [Hash | Nil] The headers with injected trace context, or `nil` if no injection occurred.
 				def inject(headers = nil, context = nil)
 					context ||= ::OpenTelemetry::Context.current
 					headers ||= Hash.new
@@ -92,6 +115,9 @@ def inject(headers = nil, context = nil)
 					return headers
 				end
 
+				# Extracts trace context from headers.
+				# @parameter headers [Hash] The headers to extract trace context from.
+				# @returns [OpenTelemetry::Context] The extracted context.
 				def extract(headers)
 					::OpenTelemetry.propagation.extract(headers)
 				end

lib/traces/backend/open_telemetry/version.rb

@@ -3,8 +3,11 @@
 # Released under the MIT License.
 # Copyright, 2021-2025, by Samuel Williams.
 
+# @namespace
 module Traces
+	# @namespace
 	module Backend
+		# @namespace
 		module OpenTelemetry
 			VERSION = "0.3.0"
 		end