Enhance documentation and error handling in PURL library

- Added API documentation links to README.md
- Improved RDoc task configuration in Rakefile
- Expanded comments and examples in PURL, PackageURL, and errors.rb files
- Enhanced validation error classes with additional context

Author: andrew

README.md

@@ -8,7 +8,7 @@ This library features comprehensive error handling with namespaced error types,
 [![Gem Version](https://badge.fury.io/rb/purl.svg)](https://rubygems.org/gems/purl)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**[Available on RubyGems](https://rubygems.org/gems/purl)**
+**[Available on RubyGems](https://rubygems.org/gems/purl)** | **[API Documentation](https://rdoc.info/github/andrew/purl)**
 
 ## Features
 

Rakefile

@@ -2,9 +2,20 @@
 
 require "bundler/gem_tasks"
 require "minitest/test_task"
+require "rdoc/task"
 
 Minitest::TestTask.create
 
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = "doc"
+  rdoc.title = "PURL - Package URL Library"
+  rdoc.main = "README.md"
+  rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
+  rdoc.options << "--line-numbers"
+  rdoc.options << "--all"
+  rdoc.options << "--charset=UTF-8"
+end
+
 task default: :test
 
 namespace :spec do

lib/purl.rb

@@ -5,7 +5,25 @@
 require_relative "purl/package_url"
 require_relative "purl/registry_url"
 
+# The main PURL (Package URL) module providing functionality to parse,
+# validate, and generate package URLs according to the PURL specification.
+#
+# A Package URL is a mostly universal standard to reference a software package
+# in a uniform way across many tools, programming languages and ecosystems.
+#
+# @example Basic usage
+#   purl = Purl.parse("pkg:gem/[email protected]")
+#   puts purl.type     # "gem"
+#   puts purl.name     # "rails"
+#   puts purl.version  # "7.0.0"
+#
+# @example Registry URL conversion
+#   purl = Purl.from_registry_url("https://rubygems.org/gems/rails")
+#   puts purl.to_s     # "pkg:gem/rails"
+#
+# @see https://github.com/package-url/purl-spec PURL Specification
 module Purl
+  # Base error class for all PURL-related errors
   class Error < StandardError; end
 
   # Load PURL types configuration from JSON file
@@ -21,6 +39,15 @@ def self.load_types_config
   KNOWN_TYPES = load_types_config["types"].keys.sort.freeze
 
   # Convenience method for parsing PURL strings
+  #
+  # @param purl_string [String] a PURL string starting with "pkg:"
+  # @return [PackageURL] parsed package URL object
+  # @raise [InvalidSchemeError] if string doesn't start with "pkg:"
+  # @raise [MalformedUrlError] if string is malformed
+  #
+  # @example
+  #   purl = Purl.parse("pkg:gem/[email protected]")
+  #   puts purl.name  # "rails"
   def self.parse(purl_string)
     PackageURL.parse(purl_string)
   end
@@ -33,26 +60,66 @@ def self.from_registry_url(registry_url, type: nil)
   end
 
   # Returns all known PURL types
+  #
+  # @return [Array<String>] sorted array of known PURL type names
+  #
+  # @example
+  #   types = Purl.known_types
+  #   puts types.include?("gem")  # true
   def self.known_types
     KNOWN_TYPES.dup
   end
 
   # Returns types that have registry URL support
+  #
+  # @return [Array<String>] sorted array of types that can generate registry URLs
+  #
+  # @example
+  #   types = Purl.registry_supported_types
+  #   puts types.include?("npm")  # true if npm has registry support
   def self.registry_supported_types
     RegistryURL.supported_types
   end
 
   # Returns types that support reverse parsing from registry URLs
+  #
+  # @return [Array<String>] sorted array of types that can parse registry URLs back to PURLs
+  #
+  # @example
+  #   types = Purl.reverse_parsing_supported_types
+  #   puts types.include?("gem")  # true if gem has reverse parsing support
   def self.reverse_parsing_supported_types
     RegistryURL.supported_reverse_types
   end
 
   # Check if a type is known/valid
+  #
+  # @param type [String, Symbol] the type to check
+  # @return [Boolean] true if type is known, false otherwise
+  #
+  # @example
+  #   Purl.known_type?("gem")     # true
+  #   Purl.known_type?("unknown") # false
   def self.known_type?(type)
     KNOWN_TYPES.include?(type.to_s.downcase)
   end
 
-  # Get type information including registry support
+  # Get comprehensive type information including registry support
+  #
+  # @param type [String, Symbol] the type to get information for
+  # @return [Hash] hash containing type information with keys:
+  #   - +:type+: normalized type name
+  #   - +:known+: whether type is known
+  #   - +:description+: human-readable description
+  #   - +:default_registry+: default registry URL
+  #   - +:examples+: array of example PURLs
+  #   - +:registry_url_generation+: whether registry URL generation is supported
+  #   - +:reverse_parsing+: whether reverse parsing is supported
+  #   - +:route_patterns+: array of URL patterns for this type
+  #
+  # @example
+  #   info = Purl.type_info("gem")
+  #   puts info[:description]  # "Ruby gems from RubyGems.org"
   def self.type_info(type)
     normalized_type = type.to_s.downcase
     {
@@ -68,6 +135,13 @@ def self.type_info(type)
   end
 
   # Get comprehensive information about all types
+  #
+  # @return [Hash<String, Hash>] hash mapping type names to their information
+  # @see #type_info for structure of individual type information
+  #
+  # @example
+  #   all_info = Purl.all_type_info
+  #   gem_info = all_info["gem"]
   def self.all_type_info
     result = {}
 
@@ -87,20 +161,38 @@ def self.all_type_info
   end
 
   # Get type configuration from JSON
+  #
+  # @param type [String, Symbol] the type to get configuration for
+  # @return [Hash, nil] configuration hash or nil if type not found
+  # @api private
   def self.type_config(type)
     config = load_types_config["types"][type.to_s.downcase]
     return nil unless config
 
     config.dup # Return a copy to prevent modification
   end
 
-  # Get description for a type
+  # Get human-readable description for a type
+  #
+  # @param type [String, Symbol] the type to get description for
+  # @return [String, nil] description string or nil if not available
+  #
+  # @example
+  #   desc = Purl.type_description("gem")
+  #   puts desc  # "Ruby gems from RubyGems.org"
   def self.type_description(type)
     config = type_config(type)
     config ? config["description"] : nil
   end
 
-  # Get examples for a type
+  # Get example PURLs for a type
+  #
+  # @param type [String, Symbol] the type to get examples for
+  # @return [Array<String>] array of example PURL strings
+  #
+  # @example
+  #   examples = Purl.type_examples("gem")
+  #   puts examples.first  # "pkg:gem/[email protected]"
   def self.type_examples(type)
     config = type_config(type)
     return [] unless config
@@ -109,6 +201,10 @@ def self.type_examples(type)
   end
 
   # Get registry configuration for a type
+  #
+  # @param type [String, Symbol] the type to get registry config for
+  # @return [Hash, nil] registry configuration hash or nil if not available
+  # @api private
   def self.registry_config(type)
     config = type_config(type)
     return nil unless config
@@ -117,6 +213,13 @@ def self.registry_config(type)
   end
 
   # Get default registry URL for a type
+  #
+  # @param type [String, Symbol] the type to get default registry for
+  # @return [String, nil] default registry URL or nil if not available
+  #
+  # @example
+  #   registry = Purl.default_registry("gem")
+  #   puts registry  # "https://rubygems.org"
   def self.default_registry(type)
     config = type_config(type)
     return nil unless config
@@ -125,6 +228,19 @@ def self.default_registry(type)
   end
 
   # Get metadata about the types configuration
+  #
+  # @return [Hash] metadata hash with keys:
+  #   - +:version+: configuration version
+  #   - +:description+: configuration description
+  #   - +:source+: source of the configuration
+  #   - +:last_updated+: when configuration was last updated
+  #   - +:total_types+: total number of types
+  #   - +:registry_supported_types+: number of types with registry support
+  #   - +:types_with_default_registry+: number of types with default registry
+  #
+  # @example
+  #   metadata = Purl.types_config_metadata
+  #   puts "Total types: #{metadata[:total_types]}"
   def self.types_config_metadata
     config = load_types_config
     {

lib/purl/errors.rb

@@ -5,9 +5,31 @@ module Purl
   class Error < StandardError; end
 
   # Validation errors for PURL components
+  #
+  # Contains additional context about which component failed validation
+  # and what rule was violated.
+  #
+  # @example
+  #   begin
+  #     PackageURL.new(type: "123invalid", name: "test")
+  #   rescue ValidationError => e
+  #     puts e.component  # :type
+  #     puts e.rule       # "cannot start with number" 
+  #   end
   class ValidationError < Error
-    attr_reader :component, :value, :rule
+    # @return [Symbol, nil] the PURL component that failed validation
+    attr_reader :component
+    
+    # @return [Object, nil] the value that failed validation
+    attr_reader :value
+    
+    # @return [String, nil] the validation rule that was violated
+    attr_reader :rule
 
+    # @param message [String] error message
+    # @param component [Symbol, nil] component that failed validation
+    # @param value [Object, nil] value that failed validation  
+    # @param rule [String, nil] validation rule that was violated
     def initialize(message, component: nil, value: nil, rule: nil)
       super(message)
       @component = component
@@ -19,46 +41,78 @@ def initialize(message, component: nil, value: nil, rule: nil)
   # Parsing errors for malformed PURL strings
   class ParseError < Error; end
 
-  # Specific validation errors
+  # Specific validation errors for PURL components
+  
+  # Raised when a PURL type is invalid
   class InvalidTypeError < ValidationError; end
+  
+  # Raised when a PURL name is invalid
   class InvalidNameError < ValidationError; end
+  
+  # Raised when a PURL namespace is invalid
   class InvalidNamespaceError < ValidationError; end
+  
+  # Raised when a PURL qualifier is invalid
   class InvalidQualifierError < ValidationError; end
+  
+  # Raised when a PURL version is invalid
   class InvalidVersionError < ValidationError; end
+  
+  # Raised when a PURL subpath is invalid
   class InvalidSubpathError < ValidationError; end
 
   # Parsing-specific errors
+  
+  # Raised when a PURL string doesn't start with "pkg:"
   class InvalidSchemeError < ParseError; end
+  
+  # Raised when a PURL string is malformed
   class MalformedUrlError < ParseError; end
 
   # Registry URL generation errors
+  #
+  # Contains additional context about which type caused the error.
   class RegistryError < Error
+    # @return [String, nil] the PURL type that caused the error
     attr_reader :type
 
+    # @param message [String] error message
+    # @param type [String, nil] PURL type that caused the error
     def initialize(message, type: nil)
       super(message)
       @type = type
     end
   end
 
+  # Raised when trying to generate registry URLs for unsupported types
   class UnsupportedTypeError < RegistryError
+    # @return [Array<String>] list of supported types
     attr_reader :supported_types
 
+    # @param message [String] error message
+    # @param type [String, nil] unsupported type
+    # @param supported_types [Array<String>] list of supported types
     def initialize(message, type: nil, supported_types: [])
       super(message, type: type)
       @supported_types = supported_types
     end
   end
 
+  # Raised when required registry information is missing
   class MissingRegistryInfoError < RegistryError
+    # @return [String, nil] the missing information (e.g., "namespace")
     attr_reader :missing
 
+    # @param message [String] error message
+    # @param type [String, nil] PURL type
+    # @param missing [String, nil] what information is missing
     def initialize(message, type: nil, missing: nil)
       super(message, type: type)
       @missing = missing
     end
   end
 
   # Legacy compatibility - matches packageurl-ruby's exception name
+  # @deprecated Use {ParseError} instead
   InvalidPackageURL = ParseError
 end