Improved documentation.

Author: samuel-williams-shopify

lib/protocol/rack/adapter.rb

@@ -32,25 +32,25 @@ module Adapter
 
 			# Creates a new adapter instance for the given Rack application.
 			# 
-			# @parameter app [Interface(:call)] A Rack application that responds to #call
-			# @returns [Protocol::HTTP::Middleware] An adapter that can handle HTTP requests
+			# @parameter app [Interface(:call)] A Rack application that responds to `call`.
+			# @returns [Protocol::HTTP::Middleware] An adapter that can handle HTTP requests.
 			def self.new(app)
 				IMPLEMENTATION.wrap(app)
 			end
 
-			# Converts a Rack response into a Protocol::HTTP response.
+			# Converts a Rack response into a {Protocol::HTTP::Response}.
 			# 
-			# @parameter env [Hash] The Rack environment
-			# @parameter response [Array] The Rack response [status, headers, body]
-			# @returns [Protocol::HTTP::Response] A Protocol::HTTP response
+			# @parameter env [Hash] The Rack environment.
+			# @parameter response [Array] The Rack response tuple `[status, headers, body]`.
+			# @returns [Protocol::HTTP::Response] A Protocol::HTTP response.
 			def self.make_response(env, response)
 				IMPLEMENTATION.make_response(env, response)
 			end
 
-			# Parses a file path from the Rack environment.
+			# Parses a Rackup file and returns the application.
 			# 
-			# @parameter env [Hash] The Rack environment
-			# @returns [String | Nil] The parsed file path or nil if not found
+			# @parameter path [String] The path to the Rackup file.
+			# @returns [Interface(:call)] The parsed Rack application.
 			def self.parse_file(...)
 				IMPLEMENTATION.parse_file(...)
 			end

lib/protocol/rack/adapter/generic.rb

@@ -30,13 +30,13 @@ def self.wrap(app)
 				# @parameter path [String] The path to the Rackup file.
 				# @returns [Interface(:call)] The Rack application.
 				def self.parse_file(...)
-					# This is the old interface, which was changed in Rack 3.
+					# This is the old interface, which was changed in Rack 3:
 					::Rack::Builder.parse_file(...).first
 				end
 
-				# Initialize the rack adaptor middleware.
+				# Initialize the Rack adapter middleware.
 				# 
-				# @parameter app [Interface(:call)] The rack middleware.
+				# @parameter app [Interface(:call)] The Rack middleware.
 				# @raises [ArgumentError] If the app does not respond to `call`.
 				def initialize(app)
 					@app = app
@@ -51,20 +51,20 @@ def logger
 					Console
 				end
 
-				# Unwrap HTTP headers into the CGI-style expected by Rack middleware, and add them to the rack `env`.
+				# Unwrap HTTP headers into the CGI-style expected by Rack middleware, and add them to the Rack `env`.
 				#
-				# e.g. `accept-encoding` becomes `HTTP_ACCEPT_ENCODING`.
+				# For example, `accept-encoding` becomes `HTTP_ACCEPT_ENCODING`.
 				#
-				# Headers keys with underscores will generate the same CGI-style header key as headers with dashes.
+				# Header keys with underscores will generate the same CGI-style header key as headers with dashes.
 				#
-				# e.g `accept_encoding` becomes `HTTP_ACCEPT_ENCODING` too.
+				# For example, `accept_encoding` becomes `HTTP_ACCEPT_ENCODING` too.
 				#
 				# You should not implicitly trust the `HTTP_` headers for security purposes, as they are generated by the client.
 				#
 				# Multiple headers are combined with a comma, with one exception: `HTTP_COOKIE` headers are combined with a semicolon.
 				#
 				# @parameter headers [Protocol::HTTP::Headers] The raw HTTP request headers.
-				# @parameter env [Hash] The rack request `env`.
+				# @parameter env [Hash] The Rack request `env`.
 				def unwrap_headers(headers, env)
 					headers.each do |key, value|
 						http_key = "HTTP_#{key.upcase.tr('-', '_')}"
@@ -81,17 +81,17 @@ def unwrap_headers(headers, env)
 					end
 				end
 
-				# Process the incoming request into a valid rack `env`.
+				# Process the incoming request into a valid Rack `env`.
 				#
 				# - Set the `env['CONTENT_TYPE']` and `env['CONTENT_LENGTH']` based on the incoming request body. 
 				# - Set the `env['HTTP_HOST']` header to the request authority.
 				# - Set the `env['HTTP_X_FORWARDED_PROTO']` header to the request scheme.
-				# - Set `env['REMOTE_ADDR']` to the request remote adress.
+				# - Set `env['REMOTE_ADDR']` to the request remote address.
 				#
 				# @parameter request [Protocol::HTTP::Request] The incoming request.
 				# @parameter env [Hash] The rack `env`.
 				def unwrap_request(request, env)
-					# The request protocol, either from the upgrade header or the HTTP/2 pseudo header of the same name.
+					# The request protocol, either from the upgrade header or the HTTP/2 pseudo header of the same name:
 					if protocol = request.protocol
 						env[RACK_PROTOCOL] = protocol
 					end
@@ -100,15 +100,15 @@ def unwrap_request(request, env)
 						env[CGI::CONTENT_TYPE] = content_type
 					end
 
-					# In some situations we don't know the content length, e.g. when using chunked encoding, or when decompressing the body.
+					# In some situations we don't know the content length, e.g. when using chunked encoding, or when decompressing the body:
 					if body = request.body and length = body.length
 						env[CGI::CONTENT_LENGTH] = length.to_s
 					end
 
 					# We ignore trailers for the purpose of constructing the rack environment:
 					self.unwrap_headers(request.headers.header, env)
 
-					# For the sake of compatibility, we set the `HTTP_UPGRADE` header to the requested protocol.
+					# For the sake of compatibility, we set the `HTTP_UPGRADE` header to the requested protocol:
 					if protocol = request.protocol and request.version.start_with?("HTTP/1")
 						env[CGI::HTTP_UPGRADE] = Array(protocol).join(",")
 					end
@@ -118,7 +118,7 @@ def unwrap_request(request, env)
 						env[RACK_HIJACK] = proc{request.hijack!.io}
 					end
 
-					# HTTP/2 prefers `:authority` over `host`, so we do this for backwards compatibility.
+					# HTTP/2 prefers `:authority` over `host`, so we do this for backwards compatibility:
 					env[CGI::HTTP_HOST] ||= request.authority
 
 					if peer = request.peer
@@ -149,26 +149,23 @@ def make_environment(request)
 				def handle_error(env, status, headers, body, error)
 					Console.error(self, "Error occurred during request processing:", error)
 
-					# Close the response body if it exists and supports closing.
+					# Close the response body if it exists and supports closing:
 					body&.close if body.respond_to?(:close)
 
-					# Invoke `rack.response_finished` callbacks in reverse order of registration.
-					# This ensures that callbacks registered later are invoked first, matching the Rack specification.
+					# Invoke `rack.response_finished` callbacks in reverse order of registration. This ensures that callbacks registered later are invoked first, matching the Rack specification.
 					env&.[](RACK_RESPONSE_FINISHED)&.reverse_each do |callback|
 						begin
 							callback.call(env, status, headers, error)
 						rescue => callback_error
-							# If a callback raises an exception, log it but continue invoking other callbacks.
-							# The Rack specification states that callbacks should not raise exceptions, but we handle
-							# this gracefully to prevent one misbehaving callback from breaking others.
+							# If a callback raises an exception, log it but continue invoking other callbacks. The Rack specification states that callbacks should not raise exceptions, but we handle this gracefully to prevent one misbehaving callback from breaking others.
 							Console.error(self, "Error occurred during response finished callback:", callback_error)
 						end
 					end
 
 					return failure_response(error)
 				end
 
-				# Build a rack `env` from the incoming request and apply it to the rack middleware.
+				# Build a Rack `env` from the incoming request and apply it to the Rack middleware.
 				#
 				# @parameter request [Protocol::HTTP::Request] The incoming request.
 				# @returns [Protocol::HTTP::Response] The HTTP response.
@@ -178,12 +175,12 @@ def call(request)
 
 					status, headers, body = @app.call(env)
 
-					# The status must always be an integer.
+					# The status must always be an integer:
 					unless status.is_a?(Integer)
 						raise ArgumentError, "Status must be an integer!"
 					end
 
-					# Headers must always be a hash or equivalent.
+					# Headers must always be a hash or equivalent:
 					unless headers
 						raise ArgumentError, "Headers must not be nil!"
 					end
@@ -205,7 +202,7 @@ def failure_response(exception)
 
 				# Extract protocol information from the environment and response.
 				# 
-				# @parameter env [Hash] The rack environment.
+				# @parameter env [Hash] The Rack environment.
 				# @parameter response [Protocol::HTTP::Response] The HTTP response.
 				# @parameter headers [Hash] The response headers to modify.
 				def self.extract_protocol(env, response, headers)

lib/protocol/rack/adapter/rack2.rb

@@ -79,7 +79,7 @@ def make_environment(request)
 					return env
 				end
 
-				# Build a rack `env` from the incoming request and apply it to the rack middleware.
+				# Build a Rack `env` from the incoming request and apply it to the Rack middleware.
 				#
 				# @parameter request [Protocol::HTTP::Request] The incoming request.
 				# @returns [Protocol::HTTP::Response] The HTTP response.
@@ -105,7 +105,7 @@ def call(request)
 
 					headers, meta = self.wrap_headers(headers)
 
-					# Rack 2 spec does not allow only partial hijacking.
+					# Rack 2 spec does not allow only partial hijacking:
 					# if hijack_body = meta[RACK_HIJACK]
 					# 	body = hijack_body
 					# end
@@ -115,7 +115,7 @@ def call(request)
 					return self.handle_error(env, status, headers, body, error)
 				end
 
-				# Process the rack response headers into a {Protocol::HTTP::Headers} instance, along with any extra `rack.` metadata.
+				# Process the Rack response headers into a {Protocol::HTTP::Headers} instance, along with any extra `rack.` metadata.
 				# Headers with newline-separated values are split into multiple headers.
 				# 
 				# @parameter fields [Hash] The raw response headers.
@@ -144,9 +144,9 @@ def wrap_headers(fields)
 				# Convert a {Protocol::HTTP::Response} into a Rack 2 response tuple.
 				# Handles protocol upgrades and streaming responses.
 				# 
-				# @parameter env [Hash] The rack environment.
+				# @parameter env [Hash] The Rack environment.
 				# @parameter response [Protocol::HTTP::Response] The HTTP response.
-				# @returns [Tuple(Integer, Hash, Object)] The Rack 2 response tuple [status, headers, body].
+				# @returns [Tuple(Integer, Hash, Object)] The Rack 2 response tuple `[status, headers, body]`.
 				def self.make_response(env, response)
 					# These interfaces should be largely compatible:
 					headers = response.headers.to_h

lib/protocol/rack/adapter/rack3.rb

@@ -117,9 +117,9 @@ def wrap_headers(fields)
 				# Handles protocol upgrades and streaming responses.
 				# Unlike Rack 2, this adapter forces streaming responses by converting the body to a callable.
 				# 
-				# @parameter env [Hash] The rack environment.
+				# @parameter env [Hash] The Rack environment.
 				# @parameter response [Protocol::HTTP::Response] The HTTP response.
-				# @returns [Tuple(Integer, Hash, Object)] The Rack 3 response tuple [status, headers, body].
+				# @returns [Tuple(Integer, Hash, Object)] The Rack 3 response tuple `[status, headers, body]`.
 				def self.make_response(env, response)
 					# These interfaces should be largely compatible:
 					headers = response.headers.to_h

lib/protocol/rack/body.rb

@@ -45,21 +45,21 @@ def self.no_content?(status)
 			def self.wrap(env, status, headers, body, input = nil, head = false)
 				# In no circumstance do we want this header propagating out:
 				if length = headers.delete(CONTENT_LENGTH)
-					# We don't really trust the user to provide the right length to the transport.
+					# We don't really trust the user to provide the right length to the transport:
 					length = Integer(length)
 				end
 
-				# If we have an Async::HTTP body, we return it directly:
+				# If we have a Protocol::HTTP body, we return it directly:
 				if body.is_a?(::Protocol::HTTP::Body::Readable)
 					# Ignore.
 				elsif status == 200 and body.respond_to?(:to_path)
 					begin
-						# Don't mangle partial responses (206)
+						# Don't mangle partial responses (206):
 						body = ::Protocol::HTTP::Body::File.open(body.to_path).tap do
 							body.close if body.respond_to?(:close) # Close the original body.
 						end
 					rescue Errno::ENOENT
-						# If the file is not available, ignore.
+						# If the file is not available, ignore:
 					end
 				elsif body.respond_to?(:each)
 					body = Body::Enumerable.wrap(body, length)
@@ -116,14 +116,12 @@ def self.wrap(env, status, headers, body, input = nil, head = false)
 			# @returns [Proc] A callback that calls all response finished handlers.
 			def self.completion_callback(response_finished, env, status, headers)
 				proc do |error|
-					# Invoke callbacks in reverse order of registration, as specified by the Rack specification.
+					# Callbacks are invoked in reverse order of registration, as required by the Rack specification:
 					response_finished.reverse_each do |callback|
 						begin
 							callback.call(env, status, headers, error)
 						rescue => callback_error
-							# If a callback raises an exception, log it but continue invoking other callbacks.
-							# The Rack specification states that callbacks should not raise exceptions, but we handle
-							# this gracefully to prevent one misbehaving callback from breaking others.
+							# If a callback raises an exception, log it but continue invoking other callbacks. The Rack specification states that callbacks should not raise exceptions, but we handle this gracefully to prevent one misbehaving callback from breaking others:
 							Console.error(self, "Error occurred during response finished callback:", callback_error)
 						end
 					end

lib/protocol/rack/body/streaming.rb

@@ -10,7 +10,6 @@ module Rack
 		module Body
 			# Wraps a Rack streaming response body.
 			# The body must be callable and accept a stream argument.
-			# This is typically used for Rack hijack responses or bodies wrapped in `Rack::BodyProxy`.
 			# When closed, this class ensures the wrapped body's `close` method is called if it exists.
 			class Streaming < ::Protocol::HTTP::Body::Streamable::ResponseBody
 				# Initialize the streaming body wrapper.

lib/protocol/rack/constants.rb

@@ -5,10 +5,10 @@
 
 module Protocol
 	module Rack
-		# Used for injecting the raw request in the the rack environment.
+		# Used for injecting the raw request into the Rack environment.
 		PROTOCOL_HTTP_REQUEST = "protocol.http.request"
 
-		# CGI keys <https://tools.ietf.org/html/rfc3875#section-4.1>:
+		# CGI environment variable keys as defined in [RFC 3875](https://tools.ietf.org/html/rfc3875#section-4.1).
 		module CGI
 			HTTP_HOST = "HTTP_HOST"
 			HTTP_UPGRADE = "HTTP_UPGRADE"
@@ -27,19 +27,19 @@ module CGI
 
 			HTTP_COOKIE = "HTTP_COOKIE"
 
-			# Header constants:
+			# Additional HTTP header constants.
 			HTTP_X_FORWARDED_PROTO = "HTTP_X_FORWARDED_PROTO"
 		end
 
-		# Rack environment variables:
+		# Rack environment variable keys.
 		RACK_ERRORS = "rack.errors"
 		RACK_LOGGER = "rack.logger"
 		RACK_INPUT = "rack.input"
 		RACK_URL_SCHEME = "rack.url_scheme"
 		RACK_PROTOCOL = "rack.protocol"
 		RACK_RESPONSE_FINISHED = "rack.response_finished"
 
-		# Rack hijack support:
+		# Rack hijack support keys.
 		RACK_IS_HIJACK = "rack.hijack?"
 		RACK_HIJACK = "rack.hijack"
 	end

lib/protocol/rack/request.rb

@@ -12,8 +12,8 @@
 module Protocol
 	module Rack
 		# A Rack-compatible HTTP request wrapper.
-		# This class provides a bridge between Rack's environment hash and Protocol::HTTP::Request.
-		# It handles conversion of Rack environment variables to HTTP request properties.
+		#
+		# This class provides a bridge between Rack's environment hash and {Protocol::HTTP::Request}. It handles conversion of Rack environment variables to HTTP request properties.
 		class Request < ::Protocol::HTTP::Request
 			# Get or create a Request instance for the given Rack environment.
 			# The request is cached in the environment to avoid creating multiple instances.
@@ -43,7 +43,8 @@ def initialize(env)
 			end
 
 			# Extract the protocol list from the Rack environment.
-			# Checks both `rack.protocol` and `HTTP_UPGRADE` headers.
+			#
+			# Checks both `rack.protocol` and {CGI::HTTP_UPGRADE} headers.
 			# 
 			# @parameter env [Hash] The Rack environment hash.
 			# @returns [Array(String) | Nil] The list of protocols or `nil` if none specified.

lib/protocol/rack/response.rb

@@ -12,17 +12,17 @@
 
 module Protocol
 	module Rack
-		# A wrapper for a `Rack` response.
+		# A Rack-compatible HTTP response wrapper
 		#
-		# A Rack response consisting of `[status, headers, body]` includes various rack-specific elements, including:
+		# A Rack response consisting of `[status, headers, body]` includes various Rack-specific elements, including:
 		#
 		# - A `headers['rack.hijack']` callback which bypasses normal response handling.
 		# - Potentially invalid content length.
 		# - Potentially invalid body when processing a `HEAD` request.
 		# - Newline-separated header values.
 		# - Other `rack.` specific header key/value pairs.
 		#
-		# This wrapper takes those issues into account and adapts the rack response tuple into a {Protocol::HTTP::Response}.
+		# This wrapper takes those issues into account and adapts the Rack response tuple into a {Protocol::HTTP::Response}.
 		class Response < ::Protocol::HTTP::Response
 			# HTTP hop headers which *should* not be passed through the proxy.
 			HOP_HEADERS = [
@@ -34,11 +34,15 @@ class Response < ::Protocol::HTTP::Response
 				"upgrade",
 			]
 
-			# Wrap a rack response.
-			# @parameter status [Integer] The rack response status.
-			# @parameter headers [Duck(:each)] The rack response headers.
-			# @parameter body [Duck(:each, :close) | Nil] The rack response body.
-			# @parameter request [Protocol::HTTP::Request] The original request.
+			# Wrap a Rack response into a {Response} instance.
+			# 
+			# @parameter env [Hash] The Rack environment hash.
+			# @parameter status [Integer] The Rack response status code.
+			# @parameter headers [Protocol::HTTP::Headers] The response headers.
+			# @parameter meta [Hash] The Rack-specific metadata (e.g., `rack.hijack`).
+			# @parameter body [Object] The Rack response body.
+			# @parameter request [Protocol::HTTP::Request | Nil] The original request.
+			# @returns [Response] A new response instance.
 			def self.wrap(env, status, headers, meta, body, request = nil)
 				ignored = headers.extract(HOP_HEADERS)
 
@@ -64,10 +68,11 @@ def self.wrap(env, status, headers, meta, body, request = nil)
 			end
 
 			# Initialize the response wrapper.
-			# @parameter status [Integer] The response status.
+			# 
+			# @parameter status [Integer] The response status code.
 			# @parameter headers [Protocol::HTTP::Headers] The response headers.
 			# @parameter body [Protocol::HTTP::Body] The response body.
-			# @parameter protocol [String] The response protocol for upgraded requests.
+			# @parameter protocol [String | Nil] The response protocol for upgraded requests.
 			def initialize(status, headers, body, protocol = nil)
 				super(nil, status, headers, body, protocol)
 			end