Improved documentation for Protocol::HTTP::Header.

Author: ioquatix

lib/protocol/http/header/authorization.rb

@@ -12,13 +12,21 @@ module Header
 			# ~~~ ruby
 			# headers.add('authorization', Authorization.basic("my_username", "my_password"))
 			# ~~~
+			#
+			# TODO Support other authorization mechanisms, e.g. bearer token.
 			class Authorization < String
-				# Splits the header and 
-				# @return [Tuple(String, String)]
+				# Splits the header into the credentials.
+				#
+				# @returns [Tuple(String, String)] The username and password.
 				def credentials
 					self.split(/\s+/, 2)
 				end
 
+				# Generate a new basic authorization header, encoding the given username and password.
+				#
+				# @parameter username [String] The username.
+				# @parameter password [String] The password.
+				# @returns [Authorization] The basic authorization header.
 				def self.basic(username, password)
 					strict_base64_encoded = ["#{username}:#{password}"].pack("m0")
 

lib/protocol/http/header/cache_control.rb

@@ -9,86 +9,118 @@
 module Protocol
 	module HTTP
 		module Header
+			# Represents the `cache-control` header, which is a list of cache directives.
 			class CacheControl < Split
+				# The `private` directive indicates that the response is intended for a single user and must not be stored by shared caches.
 				PRIVATE = "private"
+				
+				# The `public` directive indicates that the response may be stored by any cache, even if it would normally be considered non-cacheable.
 				PUBLIC = "public"
+				
+				# The `no-cache` directive indicates that caches must revalidate the response with the origin server before serving it to clients.
 				NO_CACHE = "no-cache"
+				
+				# The `no-store` directive indicates that caches must not store the response under any circumstances.
 				NO_STORE = "no-store"
+				
+				# The `max-age` directive indicates the maximum amount of time, in seconds, that a response is considered fresh.
 				MAX_AGE = "max-age"
+				
+				# The `s-maxage` directive is similar to `max-age` but applies only to shared caches. If both `s-maxage` and `max-age` are present, `s-maxage` takes precedence in shared caches.
 				S_MAXAGE = "s-maxage"
 
+				# The `static` directive is a custom directive often used to indicate that the resource is immutable or rarely changes, allowing longer caching periods.
 				STATIC = "static"
+				
+				# The `dynamic` directive is a custom directive used to indicate that the resource is generated dynamically and may change frequently, requiring shorter caching periods.
 				DYNAMIC = "dynamic"
+				
+				# The `streaming` directive is a custom directive used to indicate that the resource is intended for progressive or chunked delivery, such as live video streams.
 				STREAMING = "streaming"
 
+				# The `must-revalidate` directive indicates that once a response becomes stale, caches must not use it to satisfy subsequent requests without revalidating it with the origin server.
 				MUST_REVALIDATE = "must-revalidate"
+				
+				# The `proxy-revalidate` directive is similar to `must-revalidate` but applies only to shared caches.
 				PROXY_REVALIDATE = "proxy-revalidate"
 
+				# Initializes the cache control header with the given value. The value is expected to be a comma-separated string of cache directives.
+				#
+				# @parameter value [String | Nil] the raw Cache-Control header value.
 				def initialize(value = nil)
 					super(value&.downcase)
 				end
 
+				# Adds a directive to the Cache-Control header. The value will be normalized to lowercase before being added.
+				#
+				# @parameter value [String] the directive to add.
 				def << value
 					super(value.downcase)
 				end
 
+				# @returns [Boolean] whether the `static` directive is present.
 				def static?
 					self.include?(STATIC)
 				end
 
+				# @returns [Boolean] whether the `dynamic` directive is present.
 				def dynamic?
 					self.include?(DYNAMIC)
 				end
 
+				# @returns [Boolean] whether the `streaming` directive is present.
 				def streaming?
 					self.include?(STREAMING)
 				end
 
+				# @returns [Boolean] whether the `private` directive is present.
 				def private?
 					self.include?(PRIVATE)
 				end
 
+				# @returns [Boolean] whether the `public` directive is present.
 				def public?
 					self.include?(PUBLIC)
 				end
 
+				# @returns [Boolean] whether the `no-cache` directive is present.
 				def no_cache?
 					self.include?(NO_CACHE)
 				end
 
+				# @returns [Boolean] whether the `no-store` directive is present.
 				def no_store?
 					self.include?(NO_STORE)
 				end
 
-				# Indicates that a response must not be used once it is stale.
-				# See https://www.rfc-editor.org/rfc/rfc9111.html#name-must-revalidate
+				# @returns [Boolean] whether the `must-revalidate` directive is present.
 				def must_revalidate?
 					self.include?(MUST_REVALIDATE)
 				end
 
-				# Like must-revalidate, but for shared caches only.
-				# See https://www.rfc-editor.org/rfc/rfc9111.html#name-proxy-revalidate
+				# @returns [Boolean] whether the `proxy-revalidate` directive is present.
 				def proxy_revalidate?
 					self.include?(PROXY_REVALIDATE)
 				end
 
-				# The maximum time, in seconds, a response should be considered fresh.
-				# See https://www.rfc-editor.org/rfc/rfc9111.html#name-max-age-2
+				# @returns [Integer | Nil] the value of the `max-age` directive in seconds, or `nil` if the directive is not present or invalid.
 				def max_age
 					find_integer_value(MAX_AGE)
 				end
 
-				# Like max-age, but for shared caches only, which should use it before
-				# max-age when present.
-				# See https://www.rfc-editor.org/rfc/rfc9111.html#name-s-maxage
+				# @returns [Integer | Nil] the value of the `s-maxage` directive in seconds, or `nil` if the directive is not present or invalid.
 				def s_maxage
 					find_integer_value(S_MAXAGE)
 				end
 
 				private
 
+				# Finds and parses an integer value from a directive.
+				#
+				# @parameter value_name [String] the directive name to search for (e.g., "max-age").
+				# @returns [Integer | Nil] the parsed integer value, or `nil` if not found or invalid.
 				def find_integer_value(value_name)
-					if value = self.find{|value| value.start_with?(value_name)}
+					if value = self.find { |value| value.start_with?(value_name) }
 						_, age = value.split("=", 2)
 
 						if age =~ /\A[0-9]+\z/

lib/protocol/http/header/connection.rb

@@ -9,31 +9,48 @@
 module Protocol
 	module HTTP
 		module Header
+			# Represents the `connection` HTTP header, which controls options for the current connection.
+			#
+			# The `connection` header is used to specify control options such as whether the connection should be kept alive, closed, or upgraded to a different protocol.
 			class Connection < Split
+				# The `keep-alive` directive indicates that the connection should remain open for future requests or responses, avoiding the overhead of opening a new connection.
 				KEEP_ALIVE = "keep-alive"
+				
+				# The `close` directive indicates that the connection should be closed after the current request and response are complete.
 				CLOSE = "close"
+				
+				# The `upgrade` directive indicates that the connection should be upgraded to a different protocol, as specified in the `Upgrade` header.
 				UPGRADE = "upgrade"
 
+				# Initializes the connection header with the given value. The value is expected to be a comma-separated string of directives.
+				#
+				# @parameter value [String | Nil] the raw `connection` header value.
 				def initialize(value = nil)
 					super(value&.downcase)
 				end
 
+				# Adds a directive to the `connection` header. The value will be normalized to lowercase before being added.
+				#
+				# @parameter value [String] the directive to add.
 				def << value
 					super(value.downcase)
 				end
 
+				# @returns [Boolean] whether the `keep-alive` directive is present and the connection is not marked for closure with the `close` directive.
 				def keep_alive?
 					self.include?(KEEP_ALIVE) && !close?
 				end
 
+				# @returns [Boolean] whether the `close` directive is present, indicating that the connection should be closed after the current request and response.
 				def close?
 					self.include?(CLOSE)
 				end
 
+				# @returns [Boolean] whether the `upgrade` directive is present, indicating that the connection should be upgraded to a different protocol.
 				def upgrade?
 					self.include?(UPGRADE)
 				end
 			end
 		end
 	end
-end
+end

lib/protocol/http/header/cookie.rb

@@ -9,8 +9,13 @@
 module Protocol
 	module HTTP
 		module Header
-			# The Cookie HTTP request header contains stored HTTP cookies previously sent by the server with the Set-Cookie header.
+			# The `cookie` header contains stored HTTP cookies previously sent by the server with the `set-cookie` header.
+			#
+			# It is used by clients to send key-value pairs representing stored cookies back to the server.
 			class Cookie < Multiple
+				# Parses the `cookie` header into a hash of cookie names and their corresponding cookie objects.
+				#
+				# @returns [Hash(String, HTTP::Cookie)] a hash where keys are cookie names and values are {HTTP::Cookie} objects.
 				def to_h
 					cookies = self.collect do |string|
 						HTTP::Cookie.parse(string)
@@ -20,9 +25,11 @@ def to_h
 				end
 			end
 
-			# The Set-Cookie HTTP response header sends cookies from the server to the user agent.
+			# The `set-cookie` header sends cookies from the server to the user agent.
+			#
+			# It is used to store cookies on the client side, which are then sent back to the server in subsequent requests using the `cookie` header.
 			class SetCookie < Cookie
 			end
 		end
 	end
-end
+end

lib/protocol/http/header/date.rb

@@ -8,11 +8,20 @@
 module Protocol
 	module HTTP
 		module Header
+			# The `date` header represents the date and time at which the message was originated.
+			#
+			# This header is typically included in HTTP responses and follows the format defined in RFC 9110.
 			class Date < String
+				# Replaces the current value of the `date` header with the specified value.
+				#
+				# @parameter value [String] the new value for the `date` header.
 				def << value
 					replace(value)
 				end
 
+				# Converts the `date` header value to a `Time` object.
+				#
+				# @returns [Time] the parsed time object corresponding to the `date` header value.
 				def to_time
 					::Time.parse(self)
 				end

lib/protocol/http/header/etag.rb

@@ -6,11 +6,22 @@
 module Protocol
 	module HTTP
 		module Header
+			# The `etag` header represents the entity tag for a resource.
+			#
+			# The `etag` header provides a unique identifier for a specific version of a resource, typically used for cache validation or conditional requests. It can be either a strong or weak validator as defined in RFC 9110.
 			class ETag < String
+				# Replaces the current value of the `etag` header with the specified value.
+				#
+				# @parameter value [String] the new value for the `etag` header.
 				def << value
 					replace(value)
 				end
 
+				# Checks whether the `etag` is a weak validator.
+				#
+				# Weak validators indicate semantically equivalent content but may not be byte-for-byte identical.
+				#
+				# @returns [Boolean] whether the `etag` is weak.
 				def weak?
 					self.start_with?("W/")
 				end

lib/protocol/http/header/etags.rb

@@ -9,32 +9,63 @@
 module Protocol
 	module HTTP
 		module Header
+			# The `etags` header represents a list of entity tags (ETags) for resources.
+			#
+			# The `etags` header is used for conditional requests to compare the current version of a resource with previously stored versions. It supports both strong and weak validators, as well as the wildcard character (`*`) to indicate a match for any resource.
 			class ETags < Split
+				# Checks if the `etags` header contains the wildcard (`*`) character.
+				#
+				# The wildcard character matches any resource version, regardless of its actual value.
+				#
+				# @returns [Boolean] whether the wildcard is present.
 				def wildcard?
 					self.include?("*")
 				end
 
-				# This implementation is not strictly correct according to the RFC-specified format.
+				# Checks if the specified ETag matches the `etags` header.
+				#
+				# This method returns `true` if the wildcard is present or if the exact ETag is found in the list. Note that this implementation is not strictly compliant with the RFC-specified format.
+				#
+				# @parameter etag [String] the ETag to compare against the `etags` header.
+				# @returns [Boolean] whether the specified ETag matches.
 				def match?(etag)
 					wildcard? || self.include?(etag)
 				end
 
-				# Useful with If-Match
+				# Checks for a strong match with the specified ETag, useful with the `if-match` header.
+				#
+				# A strong match requires that the ETag in the header list matches the specified ETag and that neither is a weak validator.
+				#
+				# @parameter etag [String] the ETag to compare against the `etags` header.
+				# @returns [Boolean] whether a strong match is found.
 				def strong_match?(etag)
 					wildcard? || (!weak_tag?(etag) && self.include?(etag))
 				end
 
-				# Useful with If-None-Match
+				# Checks for a weak match with the specified ETag, useful with the `if-none-match` header.
+				#
+				# A weak match allows for semantically equivalent content, including weak validators and their strong counterparts.
+				#
+				# @parameter etag [String] the ETag to compare against the `etags` header.
+				# @returns [Boolean] whether a weak match is found.
 				def weak_match?(etag)
 					wildcard? || self.include?(etag) || self.include?(opposite_tag(etag))
 				end
 
 				private
-			
+				
+				# Converts a weak tag to its strong counterpart or vice versa.
+				#
+				# @parameter etag [String] the ETag to convert.
+				# @returns [String] the opposite form of the provided ETag.
 				def opposite_tag(etag)
 					weak_tag?(etag) ? etag[2..-1] : "W/#{etag}"
 				end
 
+				# Checks if the given ETag is a weak validator.
+				#
+				# @parameter tag [String] the ETag to check.
+				# @returns [Boolean] whether the tag is weak.
 				def weak_tag?(tag)
 					tag&.start_with? "W/"
 				end

lib/protocol/http/header/multiple.rb

@@ -6,14 +6,22 @@
 module Protocol
 	module HTTP
 		module Header
-			# Header value which is split by newline charaters (e.g. cookies).
+			# Represents headers that can contain multiple distinct values separated by newline characters.
+			#
+			# This isn't a specific header but is used as a base for headers that store multiple values, such as cookies. The values are split and stored as an array internally, and serialized back to a newline-separated string when needed.
 			class Multiple < Array
+				# Initializes the multiple header with the given value. As the header key-value pair can only contain one value, the value given here is added to the internal array, and subsequent values can be added using the `<<` operator.
+				#
+				# @parameter value [String] the raw header value.
 				def initialize(value)
 					super()
 
 					self << value
 				end
 
+				# Serializes the stored values into a newline-separated string.
+				#
+				# @returns [String] the serialized representation of the header values.
 				def to_s
 					join("\n")
 				end

lib/protocol/http/header/priority.rb

@@ -8,6 +8,9 @@
 module Protocol
 	module HTTP
 		module Header
+			# Represents the `priority` header, used to indicate the relative importance of an HTTP request.
+			#
+			# The `priority` header allows clients to express their preference for how resources should be prioritized by the server. It can include directives like `urgency` to specify the importance of a request, and `progressive` to indicate whether a response can be delivered incrementally.
 			class Priority < Split
 				# Urgency levels as defined in RFC 9218:
 				#