100% documentation coverage.

Author: ioquatix

lib/protocol/url/absolute.rb

@@ -10,6 +10,13 @@ module URL
 		# Represents an absolute URL with scheme and/or authority.
 		# Examples: "https://example.com/path", "//cdn.example.com/lib.js", "http://localhost/"
 		class Absolute < Relative
+			# Initialize a new absolute URL.
+			#
+			# @parameter scheme [String] The URL scheme (e.g., "https", "http").
+			# @parameter authority [String] The authority component (e.g., "example.com", "user@host:port").
+			# @parameter path [String] The path component (defaults to "/").
+			# @parameter query [String, nil] The query string.
+			# @parameter fragment [String, nil] The fragment identifier.
 			def initialize(scheme, authority, path = "/", query = nil, fragment = nil)
 				@scheme = scheme
 				@authority = authority
@@ -18,18 +25,25 @@ def initialize(scheme, authority, path = "/", query = nil, fragment = nil)
 				super(path, query, fragment)
 			end
 
+			# @attribute [String] The URL scheme.
 			attr :scheme
+			
+			# @attribute [String] The authority component.
 			attr :authority
 
+			# Check if the URL has a non-empty scheme.
+			#
+			# @returns [Boolean] True if a scheme is present and non-empty.
 			def scheme?
 				@scheme and !@scheme.empty?
 			end
 
+			# Check if the URL has a non-empty authority.
+			#
+			# @returns [Boolean] True if an authority is present and non-empty.
 			def authority?
 				@authority and !@authority.empty?
-			end
-			
-			# Combine this absolute URL with a relative reference according to RFC 3986 Section 5.
+			end			# Combine this absolute URL with a relative reference according to RFC 3986 Section 5.
 			#
 			# @parameter other [String, Relative, Reference, Absolute] The reference to resolve.
 			# @returns [Absolute, String] The resolved absolute URL.
@@ -118,14 +132,24 @@ def with(scheme: @scheme, authority: @authority, path: nil, query: @query, fragm
 				self.class.new(scheme, authority, Path.expand(@path, path, pop), query, fragment)
 			end
 
+			# Convert the URL to an array representation.
+			#
+			# @returns [Array] An array of `[scheme, authority, path, query, fragment]`.
 			def to_ary
 				[@scheme, @authority, @path, @query, @fragment]
 			end
 
+			# Compare this URL with another for sorting purposes.
+			#
+			# @parameter other [Absolute] The URL to compare with.
+			# @returns [Integer] -1, 0, or 1 based on component-wise comparison.
 			def <=>(other)
 				to_ary <=> other.to_ary
 			end
 
+			# Convert the URL to its string representation.
+			#
+			# @returns [String] The formatted absolute URL string.
 			def to_s
 				append
 			end

lib/protocol/url/reference.rb

@@ -17,6 +17,35 @@ module URL
 		class Reference < Relative
 			include Comparable
 
+			# Coerce a value into a {Reference} instance.
+			#
+			# This method provides flexible conversion from various types into a {Reference}.
+			# When given a {String}, it parses the URL-encoded path, query, and fragment components
+			# and unescapes them for internal storage. When given a {Relative}, it converts the
+			# encoded values to unescaped form suitable for {Reference} instances.
+			#
+			# @parameter value [String | Relative | Nil] The value to coerce.
+			# @parameter parameters [Hash | Nil] Optional user-supplied parameters to append to the query string.
+			#
+			# @returns [Reference | Nil] A new reference instance, or `nil` if the input is `nil`.
+			#
+			# @raises [ArgumentError] If the string contains whitespace or control characters.
+			# @raises [ArgumentError] If the value cannot be coerced to a {Reference}.
+			#
+			# @example Coerce a string with path, query, and fragment.
+			# 	reference = Reference["/search?q=ruby#results"]
+			# 	reference.path      # => "/search"
+			# 	reference.query     # => "q=ruby"
+			# 	reference.fragment  # => "results"
+			#
+			# @example Coerce with additional parameters.
+			# 	reference = Reference["/search", {"limit" => "10"}]
+			# 	reference.to_s  # => "/search?limit=10"
+			#
+			# @example Coerce a Relative instance.
+			# 	relative = Relative.new("/path%20with%20spaces", nil, "top")
+			# 	reference = Reference[relative]
+			# 	reference.path  # => "/path with spaces"
 			def self.[](value, parameters = nil)
 				case value
 				when String
@@ -25,7 +54,7 @@ def self.[](value, parameters = nil)
 						query = match[:query]
 						fragment = match[:fragment]
 
-						# Unescape path and fragment for user-friendly internal storage
+						# Unescape path and fragment for user-friendly internal storage:
 						# Query strings are kept as-is since they contain = and & syntax
 						path = Encoding.unescape(path) if path && !path.empty?
 						fragment = Encoding.unescape(fragment) if fragment
@@ -35,7 +64,7 @@ def self.[](value, parameters = nil)
 						raise ArgumentError, "Invalid URL (contains whitespace or control characters): #{value.inspect}"
 					end
 				when Relative
-					# Relative stores encoded values, so we need to unescape them for Reference
+					# Relative stores encoded values, so we need to unescape them for Reference:
 					path = value.path
 					fragment = value.fragment
 

lib/protocol/url/relative.rb

@@ -12,16 +12,29 @@ module URL
 		class Relative
 			include Comparable
 
+			# Initialize a new relative URL.
+			#
+			# @parameter path [String] The path component.
+			# @parameter query [String, nil] The query string.
+			# @parameter fragment [String, nil] The fragment identifier.
 			def initialize(path, query = nil, fragment = nil)
 				@path = path.to_s
 				@query = query
 				@fragment = fragment
 			end
 
+			# @attribute [String] The path component of the URL.
 			attr :path
+			
+			# @attribute [String, nil] The query string component.
 			attr :query
+			
+			# @attribute [String, nil] The fragment identifier.
 			attr :fragment
 
+			# Convert the URL path to a local filesystem path.
+			#
+			# @returns [String] The local filesystem path.
 			def to_local_path
 				Path.to_local_path(@path)
 			end
@@ -131,45 +144,84 @@ def append(buffer = String.new)
 				return buffer
 			end
 
-			def to_ary
-				[@path, @query, @fragment]
-			end
-			
-			def hash
-				to_ary.hash
-			end
-			
-			def equal?(other)
-				to_ary == other.to_ary
-			end
-			
-			def <=>(other)
-				to_ary <=> other.to_ary
-			end
-			
-			def ==(other)
-				to_ary == other.to_ary
-			end
-			
-			def ===(other)
-				to_s === other
-			end
-			
-			def to_s
-				append
-			end
-			
-			def as_json(...)
-				to_s
-			end
-			
-			def to_json(...)
-				as_json.to_json(...)
-			end
-			
-			def inspect
-				"#<#{self.class} #{to_s}>"
-			end
+			return buffer
+		end
+		
+		# Convert the URL to an array representation.
+		#
+		# @returns [Array] An array of `[path, query, fragment]`.
+		def to_ary
+			[@path, @query, @fragment]
+		end
+		
+		# Compute a hash value for the URL based on its components.
+		#
+		# @returns [Integer] The hash value.
+		def hash
+			to_ary.hash
+		end
+		
+		# Check if this URL is equal to another URL by comparing components.
+		#
+		# @parameter other [Relative] The URL to compare with.
+		# @returns [Boolean] True if the URLs have identical components.
+		def equal?(other)
+			to_ary == other.to_ary
+		end
+		
+		# Compare this URL with another for sorting purposes.
+		#
+		# @parameter other [Relative] The URL to compare with.
+		# @returns [Integer] -1, 0, or 1 based on component-wise comparison.
+		def <=>(other)
+			to_ary <=> other.to_ary
+		end
+		
+		# Check structural equality by comparing components.
+		#
+		# @parameter other [Relative] The URL to compare with.
+		# @returns [Boolean] True if the URLs have identical components.
+		def ==(other)
+			to_ary == other.to_ary
+		end
+		
+		# Check string equality, useful for case statements.
+		#
+		# @parameter other [String, Relative] The value to compare with.
+		# @returns [Boolean] True if the string representations match.
+		def ===(other)
+			to_s === other
+		end
+		
+		# Convert the URL to its string representation.
+		#
+		# @returns [String] The formatted URL string.
+		def to_s
+			append
+		end
+		
+		# Convert the URL to a JSON-compatible representation.
+		#
+		# @returns [String] The URL as a string.
+		def as_json(...)
+			to_s
+		end
+		
+		# Convert the URL to JSON.
+		#
+		# @returns [String] The JSON-encoded URL.
+		def to_json(...)
+			as_json.to_json(...)
+		end
+		
+		# Generate a human-readable representation for debugging.
+		#
+		# @returns [String] A string like `#<Protocol::URL::Relative /path?query#fragment>`.
+		def inspect
+			"#<#{self.class} #{to_s}>"
+		end
+	end
+end
 		end
 	end
 end