100% documentation coverage.

Author: ioquatix

context/index.yaml

@@ -4,6 +4,7 @@
 description: Provides abstractions for working with URLs.
 metadata:
   source_code_uri: https://github.com/socketry/protocol-url.git
+  documentation_uri: https://socketry.github.io/protocol-url/
 files:
 - path: getting-started.md
   title: Getting Started

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,13 +25,22 @@ 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
@@ -93,8 +109,6 @@ def append(buffer = String.new)
 				super(buffer)
 			end
 
-			UNSPECIFIED = Object.new
-			
 			# Create a new Absolute URL with modified components.
 			#
 			# @parameter scheme [String, nil] The scheme to use (nil to remove scheme).
@@ -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,42 +144,76 @@ def append(buffer = String.new)
 				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

protocol-url.gemspec

@@ -17,6 +17,7 @@ Gem::Specification.new do |spec|
 
 	spec.metadata = {
 		"source_code_uri" => "https://github.com/socketry/protocol-url.git",
+		"documentation_uri" => "https://socketry.github.io/protocol-url/",
 	}
 
 	spec.files = Dir.glob(["{lib}/**/*", "*.md"], File::FNM_DOTMATCH, base: __dir__)

readme.md

@@ -6,11 +6,11 @@ Provides abstractions for working with URLs.
 
 ## Usage
 
-Please see the [project documentation](https://github.com/socketry/protocol-url) for more details.
+Please see the [project documentation](https://socketry.github.io/protocol-url/) for more details.
 
-  - [Getting Started](https://github.com/socketry/protocol-urlguides/getting-started/index) - This guide explains how to get started with `protocol-url` for parsing, manipulating, and constructing URLs in Ruby.
+  - [Getting Started](https://socketry.github.io/protocol-url/guides/getting-started/index) - This guide explains how to get started with `protocol-url` for parsing, manipulating, and constructing URLs in Ruby.
 
-  - [Working with References](https://github.com/socketry/protocol-urlguides/working-with-references/index) - This guide explains how to use <code class="language-ruby">Protocol::URL::Reference</code> for managing URLs with query parameters and fragments.
+  - [Working with References](https://socketry.github.io/protocol-url/guides/working-with-references/index) - This guide explains how to use <code class="language-ruby">Protocol::URL::Reference</code> for managing URLs with query parameters and fragments.
 
 ## Contributing
 
@@ -32,7 +32,7 @@ This project is best served by a collaborative and respectful environment. Treat
 
 ## Releases
 
-Please see the [project releases](https://github.com/socketry/protocol-urlreleases/index) for all releases.
+Please see the [project releases](https://socketry.github.io/protocol-url/releases/index) for all releases.
 
 ### v0.4.0