100% documentation coverage.

Author: samuel-williams-shopify

lib/protocol/grpc/body/readable_body.rb

@@ -8,14 +8,16 @@
 
 module Protocol
 	module GRPC
+		# @namespace
 		module Body
-			# Reads length-prefixed gRPC messages from an HTTP body
-			# This is the standard readable body for gRPC - all gRPC responses use message framing
+			# Represents a readable body for gRPC messages with length-prefixed framing.
+			# This is the standard readable body for gRPC - all gRPC responses use message framing.
 			class ReadableBody
+				# Initialize a new readable body for gRPC messages.
 				# @parameter body [Protocol::HTTP::Body::Readable] The underlying HTTP body
-				# @parameter message_class [Class, nil] Protobuf message class with .decode method
-				#   If nil, returns raw binary data (useful for channel adapters)
-				# @parameter encoding [String, nil] Compression encoding (from grpc-encoding header)
+				# @parameter message_class [Class | Nil] Protobuf message class with .decode method.
+				#   If `nil`, returns raw binary data (useful for channel adapters)
+				# @parameter encoding [String | Nil] Compression encoding (from grpc-encoding header)
 				def initialize(body, message_class: nil, encoding: nil)
 					@body = body
 					@message_class = message_class
@@ -24,15 +26,15 @@ def initialize(body, message_class: nil, encoding: nil)
 					@closed = false
 				end
 
-				# The input body.
-				# @attribute [Protocol::HTTP::Body::Readable]
+				# @attribute [Protocol::HTTP::Body::Readable] The underlying HTTP body.
 				attr_reader :body
 
-				# The compression encoding.
-				# @attribute [String, nil]
+				# @attribute [String | Nil] The compression encoding.
 				attr_reader :encoding
 
-				# Close the input and output bodies.
+				# Close the input body.
+				# @parameter error [Exception | Nil] Optional error that caused the close
+				# @returns [Nil]
 				def close(error = nil)
 					@closed = true
 
@@ -44,18 +46,20 @@ def close(error = nil)
 					nil
 				end
 
-				# Whether the stream has been closed.
+				# Check if the stream has been closed.
+				# @returns [Boolean] `true` if the stream is closed, `false` otherwise
 				def closed?
 					@closed or @body.nil?
 				end
 
-				# Whether there are any input chunks remaining?
+				# Check if there are any input chunks remaining.
+				# @returns [Boolean] `true` if the body is empty, `false` otherwise
 				def empty?
 					@body.nil?
 				end
 
-				# Read the next gRPC message
-				# @returns [Object | String | Nil] Decoded message, raw binary, or nil if stream ended
+				# Read the next gRPC message.
+				# @returns [Object | String | Nil] Decoded message, raw binary, or `Nil` if stream ended
 				def read
 					return nil if closed?
 
@@ -66,17 +70,17 @@ def read
 					compressed = prefix[0].unpack1("C") == 1
 					length = prefix[1..4].unpack1("N")
 
-					# Read the message body
+					# Read the message body:
 					data = read_exactly(length)
 					return nil unless data
 
-					# Decompress if needed
+					# Decompress if needed:
 					data = decompress(data) if compressed
 
-					# Decode using message class if provided, otherwise return binary
+					# Decode using message class if provided, otherwise return binary:
 					# This allows binary mode for channel adapters
 					if @message_class
-						# Use protobuf gem's decode method
+						# Use protobuf gem's decode method:
 						@message_class.decode(data)
 					else
 						data # Return raw binary
@@ -103,39 +107,46 @@ def each
 
 			private
 
+				# Read exactly n bytes from the underlying body.
+				# @parameter n [Integer] The number of bytes to read
+				# @returns [String | Nil] The data read, or `Nil` if the stream ended
 				def read_exactly(n)
-					# Fill buffer until we have enough data
+					# Fill buffer until we have enough data:
 					while @buffer.bytesize < n
 						return nil if closed?
 
-						# Read chunk from underlying body
+						# Read chunk from underlying body:
 						chunk = @body.read
 
 						if chunk.nil?
-							# End of stream
+							# End of stream:
 							if @body && !@closed
 								@body.close
 								@closed = true
 							end
 							return nil
 						end
 
-						# Append to buffer
+						# Append to buffer:
 						@buffer << chunk.force_encoding(Encoding::BINARY)
 
-						# Check if body is empty and close if needed
+						# Check if body is empty and close if needed:
 						if @body.empty?
 							@body.close
 							@closed = true
 						end
 					end
 
-					# Extract the required data
+					# Extract the required data:
 					data = @buffer[0...n]
 					@buffer = @buffer[n..]
 					data
 				end
 
+				# Decompress data using the configured encoding.
+				# @parameter data [String] The compressed data
+				# @returns [String] The decompressed data
+				# @raises [Error] If decompression fails
 				def decompress(data)
 					case @encoding
 					when "gzip"

lib/protocol/grpc/body/writable_body.rb

@@ -10,64 +10,75 @@
 
 module Protocol
 	module GRPC
+		# @namespace
 		module Body
-			# Writes length-prefixed gRPC messages
-			# This is the standard writable body for gRPC - all gRPC requests use message framing
+			# Represents a writable body for gRPC messages with length-prefixed framing.
+			# This is the standard writable body for gRPC - all gRPC requests use message framing.
 			class WritableBody < Protocol::HTTP::Body::Writable
-				# @parameter encoding [String, nil] Compression encoding (gzip, deflate, identity)
+				# Initialize a new writable body for gRPC messages.
+				# @parameter encoding [String | Nil] Compression encoding (gzip, deflate, identity)
 				# @parameter level [Integer] Compression level if encoding is used
-				# @parameter message_class [Class, nil] Expected message class for validation
+				# @parameter message_class [Class | Nil] Expected message class for validation
 				def initialize(encoding: nil, level: Zlib::DEFAULT_COMPRESSION, message_class: nil, **options)
 					super(**options)
 					@encoding = encoding
 					@level = level
 					@message_class = message_class
 				end
 
+				# @attribute [String | Nil] The compression encoding.
 				attr_reader :encoding
+				
+				# @attribute [Class | Nil] The expected message class for validation.
 				attr_reader :message_class
 
-				# Write a message with gRPC framing
+				# Write a message with gRPC framing.
 				# @parameter message [Object, String] Protobuf message instance or raw binary data
-				# @parameter compressed [Boolean] Whether to compress this specific message
+				# @parameter compressed [Boolean | Nil] Whether to compress this specific message. If `nil`, uses the encoding setting.
 				def write(message, compressed: nil)
-					# Validate message type if message_class is specified
+					# Validate message type if message_class is specified:
 					if @message_class && !message.is_a?(String)
 						unless message.is_a?(@message_class)
 							raise TypeError, "Expected #{@message_class}, got #{message.class}"
 						end
 					end
-					# Encode message to binary if it's not already a string
+					
+					# Encode message to binary if it's not already a string:
 					# This supports both high-level (protobuf objects) and low-level (binary) usage
 					data = if message.is_a?(String)
 						message # Already binary, use as-is (for channel adapters)
 					elsif message.respond_to?(:to_proto)
-						# Use protobuf gem's to_proto or encode method
+						# Use protobuf gem's to_proto method:
 						message.to_proto
 					elsif message.respond_to?(:encode)
+						# Use encode method:
 						message.encode
 					else
 						raise ArgumentError, "Message must respond to :to_proto or :encode"
 					end
 
-					# Determine if we should compress this message
+					# Determine if we should compress this message:
 					# If compressed param is nil, use the encoding setting
 					should_compress = compressed.nil? ? (@encoding && @encoding != "identity") : compressed
 
-					# Compress if requested
+					# Compress if requested:
 					data = compress(data) if should_compress
 
 					# Build prefix: compression flag + length
 					compression_flag = should_compress ? 1 : 0
 					length = data.bytesize
 					prefix = [compression_flag].pack("C") + [length].pack("N")
 
-					# Write prefix + data to underlying body
+					# Write prefix + data to underlying body:
 					super(prefix + data) # Call Protocol::HTTP::Body::Writable#write
 				end
 
-					protected
+				protected
 
+				# Compress data using the configured encoding.
+				# @parameter data [String] The data to compress
+				# @returns [String] The compressed data
+				# @raises [Error] If compression fails
 				def compress(data)
 					case @encoding
 					when "gzip"

lib/protocol/grpc/call.rb

@@ -8,53 +8,54 @@
 
 module Protocol
 	module GRPC
-		# Represents context for a single RPC call
+		# Represents context for a single RPC call.
 		class Call
+			# Initialize a new RPC call context.
 			# @parameter request [Protocol::HTTP::Request] The HTTP request
-			# @parameter deadline [Async::Deadline, nil] Deadline for the call
+			# @parameter deadline [Async::Deadline | Nil] Deadline for the call
 			def initialize(request, deadline: nil)
 				@request = request
 				@deadline = deadline
 				@cancelled = false
 			end
 
-			# @attribute [Protocol::HTTP::Request] The underlying HTTP request
+			# @attribute [Protocol::HTTP::Request] The underlying HTTP request.
 			attr_reader :request
 
-			# @attribute [Async::Deadline, nil] The deadline for this call
+			# @attribute [Async::Deadline | Nil] The deadline for this call.
 			attr_reader :deadline
 
-			# Extract metadata from request headers
-			# @returns [Hash] Custom metadata
+			# Extract metadata from request headers.
+			# @returns [Hash] Custom metadata key-value pairs
 			def metadata
 				@metadata ||= Methods.extract_metadata(@request.headers)
 			end
 
-			# Check if the deadline has expired
-			# @returns [Boolean]
+			# Check if the deadline has expired.
+			# @returns [Boolean] `true` if the deadline has expired, `false` otherwise
 			def deadline_exceeded?
 				@deadline&.expired? || false
 			end
 
-			# Time remaining until deadline
-			# @returns [Numeric, nil] Seconds remaining, or nil if no deadline
+			# Get the time remaining until the deadline.
+			# @returns [Numeric | Nil] Seconds remaining, or `Nil` if no deadline is set
 			def time_remaining
 				@deadline&.remaining
 			end
 
-			# Mark this call as cancelled
+			# Mark this call as cancelled.
 			def cancel!
 				@cancelled = true
 			end
 
-			# Check if call was cancelled
-			# @returns [Boolean]
+			# Check if the call was cancelled.
+			# @returns [Boolean] `true` if the call was cancelled, `false` otherwise
 			def cancelled?
 				@cancelled
 			end
 
-			# Get peer information (client address)
-			# @returns [String, nil]
+			# Get peer information (client address).
+			# @returns [String | Nil] The peer address as a string, or `Nil` if not available
 			def peer
 				@request.peer&.to_s
 			end