abachrome 0.1.0 → 0.1.1

data/lib/abachrome/converters/base.rb

@@ -1,39 +1,100 @@
-# frozen_string_literal: true
+# Abachrome::Converters::Base - Abstract base class for color space converters
+#
+# This class provides the foundation for implementing color space conversion functionality
+# within the Abachrome library. It defines the interface that all converter classes must
+# implement and provides common validation and utility methods for color transformations.
+#
+# Key features:
+# - Abstract conversion interface requiring subclasses to implement #convert method
+# - Color model validation to ensure proper conversion compatibility
+# - Converter registration and lookup system for managing conversion mappings
+# - Source and target color space compatibility checking
+# - Base functionality for building specific converter implementations
+#
+# All converter classes in the Abachrome system inherit from this base class and implement
+# the specific mathematical transformations needed to convert colors between different
+# color spaces such as sRGB, OKLAB, OKLCH, and linear RGB. The class follows a naming
+# convention pattern (FromSpaceToSpace) for automatic registration and discovery.
 
 module Abachrome
   module Converters
     class Base
       attr_reader :from_space, :to_space
 
+      # Initialize a new converter between two color spaces.
+      # 
+      # @param from_space [Abachrome::ColorSpace] The source color space to convert from
+      # @param to_space [Abachrome::ColorSpace] The target color space to convert to
+      # @return [Abachrome::Converters::Base] A new converter instance
       def initialize(from_space, to_space)
         @from_space = from_space
         @to_space = to_space
       end
 
+      # Converts a color from one color space to another.
+      # 
+      # @abstract This is an abstract method that must be implemented by subclasses.
+      # @param color [Abachrome::Color] The color to convert
+      # @return [Abachrome::Color] The converted color
+      # @raise [NotImplementedError] If the subclass doesn't implement this method
       def convert(color)
         raise NotImplementedError, "Subclasses must implement #convert"
       end
 
+      # Validates that a color uses the expected color model.
+      # 
+      # @param color [Abachrome::Color] The color object to check
+      # @param model [Symbol, String] The expected color model
+      # @raise [RuntimeError] If the color's model doesn't match the expected model
+      # @return [nil] If the color's model matches the expected model
       def self.raise_unless(color, model)
         return if color.color_space.color_model == model
 
         raise "#{color} is #{color.color_space.color_model}), expecting #{model}"
       end
 
+      # Determines if the converter can handle the given color.
+      # 
+      # This method checks if the color's current color space matches
+      # the converter's source color space.
+      # 
+      # @param color [Abachrome::Color] The color to check
+      # @return [Boolean] true if the converter can convert from the color's current color space,
+      # false otherwise
       def can_convert?(color)
         color.color_space == from_space
       end
 
+      # Register a converter class for transforming colors between two specific color spaces.
+      # 
+      # @param from_space_id [Symbol] The identifier of the source color space
+      # @param to_space_id [Symbol] The identifier of the destination color space
+      # @param converter_class [Class] The converter class that handles the transformation
+      # @return [void]
       def self.register(from_space_id, to_space_id, converter_class)
         @converters ||= {}
         @converters[[from_space_id, to_space_id]] = converter_class
       end
 
+      # Find a converter for converting between color spaces.
+      # 
+      # @param from_space_id [Symbol, String] The identifier of the source color space
+      # @param to_space_id [Symbol, String] The identifier of the destination color space
+      # @return [Converter, nil] The converter instance for the specified color spaces, or nil if no converter is found
       def self.find_converter(from_space_id, to_space_id)
         @converters ||= {}
         @converters[[from_space_id, to_space_id]]
       end
 
+      # Converts a color from its current color space to a target color space.
+      # 
+      # This method finds the appropriate converter class for the given source and
+      # target color spaces and performs the conversion.
+      # 
+      # @param color [Abachrome::Color] The color to convert
+      # @param to_space [Abachrome::ColorSpace] The target color space to convert to
+      # @return [Abachrome::Color] The converted color in the target color space
+      # @raise [ConversionError] If no converter is found for the given color spaces
       def self.convert(color, to_space)
         converter_class = find_converter(color.color_space.id, to_space.id)
         unless converter_class
@@ -47,6 +108,12 @@ module Abachrome
 
       private
 
+      # Validates if a color can be converted from its current color space.
+      # Raises an ArgumentError if the color's space doesn't match the expected source space.
+      # 
+      # @param color [Abachrome::Color] The color object to validate
+      # @raise [ArgumentError] If the color cannot be converted from its current color space
+      # @return [nil] Returns nil if the color is valid for conversion
       def validate_color!(color)
         return if can_convert?(color)
 
@@ -54,4 +121,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/converters/lrgb_to_oklab.rb

@@ -1,8 +1,34 @@
-# frozen_string_literal: true
+# Abachrome::Converters::LrgbToOklab - Linear RGB to OKLAB color space converter
+#
+# This converter transforms colors from the linear RGB (LRGB) color space to the OKLAB color space
+# using the standard OKLAB transformation matrices. The conversion process applies a series of
+# matrix transformations and non-linear operations to accurately map linear RGB coordinates to
+# the perceptually uniform OKLAB color space.
+#
+# Key features:
+# - Implements the official OKLAB transformation algorithm with high-precision matrices
+# - Converts linear RGB values through intermediate LMS color space representation
+# - Applies cube root transformation for perceptual uniformity in the OKLAB space
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper linear RGB source data
+#
+# The OKLAB color space provides better perceptual uniformity compared to traditional RGB spaces,
+# making it ideal for color manipulation operations like blending, lightness adjustments, and
+# gamut mapping where human visual perception accuracy is important.
 
 module Abachrome
   module Converters
     class LrgbToOklab < Abachrome::Converters::Base
+      # Converts a color from linear RGB (LRGB) color space to OKLAB color space.
+      # 
+      # This conversion applies a matrix transformation to the linear RGB values,
+      # followed by a non-linear transformation, then another matrix transformation
+      # to produce OKLAB coordinates.
+      # 
+      # @param rgb_color [Abachrome::Color] A color in linear RGB (LRGB) color space
+      # @raise [ArgumentError] If the provided color is not in LRGB color space
+      # @return [Abachrome::Color] The converted color in OKLAB color space with the same alpha value as the input
       def self.convert(rgb_color)
         raise_unless rgb_color, :lrgb
 
@@ -24,4 +50,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/converters/lrgb_to_srgb.rb

@@ -1,8 +1,25 @@
-# frozen_string_literal: true
+# Abachrome::Converters::LrgbToSrgb - Linear RGB to sRGB color space converter
+#
+# This converter transforms colors from the linear RGB (LRGB) color space to the standard RGB (sRGB) color space by applying gamma correction. The conversion process applies the sRGB transfer function which uses different formulas for small and large values to match the non-linear response characteristics of typical display devices.
+#
+# Key features:
+# - Implements the standard sRGB gamma correction algorithm with precise threshold handling
+# - Converts linear RGB values to gamma-corrected sRGB values for proper display representation
+# - Applies different transformation functions based on value magnitude (linear vs power function)
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper linear RGB source data
+#
+# The sRGB color space is the standard RGB color space for web content and most consumer displays, providing gamma correction that better matches human visual perception and display device characteristics compared to linear RGB values.
 
 module Abachrome
   module Converters
     class LrgbToSrgb < Abachrome::Converters::Base
+      # Converts a color from linear RGB to sRGB color space.
+      # 
+      # @param lrgb_color [Abachrome::Color] The color in linear RGB color space to convert
+      # @return [Abachrome::Color] A new Color object in sRGB color space with the converted coordinates
+      # @raise [TypeError] If the provided color is not in linear RGB color space
       def self.convert(lrgb_color)
         raise_unless lrgb_color, :lrgb
         r, g, b = lrgb_color.coordinates.map { |c| to_srgb(AbcDecimal(c)) }
@@ -16,6 +33,14 @@ module Abachrome
         )
       end
 
+      # Converts a linear RGB value to standard RGB color space (sRGB) value.
+      # 
+      # This method implements the standard linearization function used in the sRGB color space.
+      # For small values (≤ 0.0031308), a simple linear transformation is applied.
+      # For larger values, a power function with gamma correction is used.
+      # 
+      # @param v [AbcDecimal] The linear RGB value to convert
+      # @return [AbcDecimal] The corresponding sRGB value, preserving the sign of the input
       def self.to_srgb(v)
         v_abs = v.abs
         v_sign = v.negative? ? -1 : 1
@@ -27,4 +52,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/converters/oklab_to_lrgb.rb

@@ -1,8 +1,40 @@
-# frozen_string_literal: true
+# Abachrome::Converters::OklabToLrgb - OKLAB to Linear RGB color space converter
+#
+# This converter transforms colors from the OKLAB color space to the linear RGB (LRGB) color space
+# using the standard OKLAB inverse transformation matrices. The conversion process applies a series of
+# matrix transformations and cubic operations to accurately map OKLAB coordinates back to the
+# linear RGB color space, which represents colors with a linear relationship to light intensity.
+#
+# Key features:
+# - Implements the official OKLAB to linear RGB inverse transformation algorithm with high-precision matrices
+# - Converts OKLAB values through intermediate L'M'S' and LMS color space representations
+# - Applies cubic operations to reverse the perceptual uniformity transformations
+# - Clamps negative RGB values to zero to ensure valid linear RGB output
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper OKLAB source data
+#
+# The linear RGB color space provides the foundation for further conversions to display-ready
+# color spaces like sRGB, making this converter essential for the color transformation pipeline
+# when working with perceptually uniform OKLAB color manipulations.
 
 module Abachrome
   module Converters
     class OklabToLrgb < Abachrome::Converters::Base
+      # Converts a color from OKLAB color space to linear RGB color space.
+      # 
+      # The method implements the OKLAB to linear RGB transformation matrix based on
+      # standard color science algorithms. It first confirms the input is in OKLAB
+      # space, then applies the transformation through several steps:
+      # 1. Converts OKLAB coordinates to intermediate L'M'S' values
+      # 2. Applies a cubic operation to get LMS values
+      # 3. Transforms LMS to linear RGB
+      # 4. Clamps negative values to zero
+      # 
+      # @param oklab_color [Abachrome::Color] The color in OKLAB color space
+      # @raise [ArgumentError] If the input color is not in OKLAB color space
+      # @return [Abachrome::Color] The resulting color in linear RGB color space with
+      # the same alpha as the input color
       def self.convert(oklab_color)
         raise_unless oklab_color, :oklab
 
@@ -39,4 +71,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/converters/oklab_to_oklch.rb

@@ -1,8 +1,37 @@
-# frozen_string_literal: true
+# Abachrome::Converters::OklabToOklch - OKLAB to OKLCH color space converter
+#
+# This converter transforms colors from the OKLAB color space to the OKLCH color space
+# using cylindrical coordinate conversion. The transformation converts the rectangular
+# coordinates (L, a, b) to cylindrical coordinates (L, C, h) where lightness remains
+# unchanged, chroma is calculated as the Euclidean distance in the a-b plane, and hue
+# is calculated as the angle in the a-b plane expressed in degrees.
+#
+# Key features:
+# - Converts OKLAB rectangular coordinates to OKLCH cylindrical coordinates
+# - Preserves lightness component unchanged during conversion
+# - Calculates chroma as sqrt(a² + b²) for colorfulness representation
+# - Computes hue angle using atan2 function and normalizes to 0-360 degree range
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper OKLAB source data
+#
+# The OKLCH color space provides an intuitive interface for color manipulation through
+# its cylindrical coordinate system, making it ideal for hue adjustments, saturation
+# modifications, and other color operations that benefit from polar coordinates.
 
 module Abachrome
   module Converters
     class OklabToOklch < Abachrome::Converters::Base
+      # Converts a color from OKLAB color space to OKLCH color space.
+      # The method performs a mathematical transformation from the rectangular
+      # coordinates (L, a, b) to cylindrical coordinates (L, C, h), where:
+      # - L (lightness) remains the same
+      # - C (chroma) is calculated as the Euclidean distance from the origin in the a-b plane
+      # - h (hue) is calculated as the angle in the a-b plane
+      # 
+      # @param oklab_color [Abachrome::Color] A color in the OKLAB color space
+      # @raise [ArgumentError] If the provided color is not in OKLAB color space
+      # @return [Abachrome::Color] The equivalent color in OKLCH color space with the same alpha value
       def self.convert(oklab_color)
         raise_unless oklab_color, :oklab
 
@@ -20,4 +49,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/converters/oklab_to_srgb.rb

@@ -1,8 +1,33 @@
-# frozen_string_literal: true
+# Abachrome::Converters::OklabToSrgb - OKLAB to sRGB color space converter
+#
+# This converter transforms colors from the OKLAB color space to the standard RGB (sRGB) color space
+# through a two-step conversion process. The transformation first converts OKLAB coordinates to
+# linear RGB as an intermediate step, then applies gamma correction to produce the final sRGB
+# values suitable for display on standard monitors and web applications.
+#
+# Key features:
+# - Two-stage conversion pipeline: OKLAB → Linear RGB → sRGB
+# - Leverages existing OklabToLrgb and LrgbToSrgb converters for modular transformation
+# - Maintains alpha channel transparency values during conversion
+# - Applies proper gamma correction for display-ready color values
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper OKLAB source data
+#
+# The sRGB color space is the standard RGB color space for web content and most consumer
+# displays, providing gamma-corrected values that properly represent colors on typical
+# display devices while maintaining compatibility with web standards and digital media formats.
 
 module Abachrome
   module Converters
     class OklabToSrgb < Abachrome::Converters::Base
+      # Converts a color from the Oklab color space to the sRGB color space.
+      # This conversion is performed in two steps:
+      # 1. First converts from Oklab to linear RGB
+      # 2. Then converts from linear RGB to sRGB
+      # 
+      # @param oklab_color [Color] A color in the Oklab color space
+      # @raise [ArgumentError] If the provided color is not in the Oklab color space
+      # @return [Color] The converted color in the sRGB color space
       def self.convert(oklab_color)
         raise_unless oklab_color, :oklab
 
@@ -14,4 +39,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/converters/oklch_to_lrgb.rb

@@ -1,4 +1,21 @@
-# frozen_string_literal: true
+# Abachrome::Converters::OklchToLrgb - OKLCH to Linear RGB color space converter
+#
+# This converter transforms colors from the OKLCH color space to the linear RGB (LRGB) color space
+# through a two-step conversion process. The transformation first converts OKLCH cylindrical
+# coordinates to OKLAB rectangular coordinates, then applies the standard OKLAB to linear RGB
+# transformation matrices to produce the final linear RGB values.
+#
+# Key features:
+# - Two-stage conversion pipeline: OKLCH → OKLAB → Linear RGB
+# - Leverages existing OklchToOklab and OklabToLrgb converters for modular transformation
+# - Converts cylindrical coordinates (lightness, chroma, hue) to linear light intensity values
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper OKLCH source data
+#
+# The linear RGB color space provides the foundation for further conversions to display-ready
+# color spaces like sRGB, making this converter essential for the color transformation pipeline
+# when working with OKLCH color manipulations that need to be rendered on standard displays.
 
 require_relative "oklab_to_lrgb"
 require_relative "oklch_to_oklab"
@@ -6,10 +23,16 @@ require_relative "oklch_to_oklab"
 module Abachrome
   module Converters
     class OklchToLrgb < Abachrome::Converters::Base
+      # Converts a color from OKLCH color space to linear RGB color space.
+      # This is a two-step conversion process that first converts from OKLCH to OKLAB,
+      # then from OKLAB to linear RGB.
+      # 
+      # @param oklch_color [Abachrome::Color] A color in the OKLCH color space
+      # @return [Abachrome::Color] The resulting color in linear RGB color space
       def self.convert(oklch_color)
         oklab_color = OklchToOklab.convert(oklch_color)
         OklabToLrgb.convert(oklab_color)
       end
     end
   end
-end
+end

data/lib/abachrome/converters/oklch_to_oklab.rb

@@ -1,8 +1,33 @@
-# frozen_string_literal: true
+# Abachrome::Converters::OklchToOklab - OKLCH to OKLAB color space converter
+#
+# This converter transforms colors from the OKLCH color space to the OKLAB color space
+# using cylindrical to rectangular coordinate conversion. The transformation converts the
+# cylindrical coordinates (L, C, h) to rectangular coordinates (L, a, b) where lightness
+# remains unchanged, and the a and b components are calculated from chroma and hue using
+# trigonometric functions (cosine and sine respectively).
+#
+# Key features:
+# - Converts OKLCH cylindrical coordinates to OKLAB rectangular coordinates
+# - Preserves lightness component unchanged during conversion
+# - Calculates a component as chroma × cos(hue) for green-red axis positioning
+# - Calculates b component as chroma × sin(hue) for blue-yellow axis positioning
+# - Converts hue angle from degrees to radians for trigonometric calculations
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper OKLCH source data
+#
+# The OKLAB color space provides the foundation for further conversions to other color
+# spaces and serves as an intermediate step in the color transformation pipeline when
+# working with OKLCH color manipulations that need to be converted to display-ready formats.
 
 module Abachrome
   module Converters
     class OklchToOklab < Abachrome::Converters::Base
+      # Converts a color from OKLCH color space to OKLAB color space.
+      # 
+      # @param oklch_color [Abachrome::Color] The color in OKLCH format to convert
+      # @return [Abachrome::Color] The converted color in OKLAB format
+      # @raise [StandardError] If the provided color is not in OKLCH color space
       def self.convert(oklch_color)
         raise_unless oklch_color, :oklch
 
@@ -20,4 +45,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/converters/oklch_to_srgb.rb

@@ -1,4 +1,22 @@
-# frozen_string_literal: true
+# Abachrome::Converters::OklchToSrgb - OKLCH to sRGB color space converter
+#
+# This converter transforms colors from the OKLCH color space to the standard RGB (sRGB) color space
+# through a two-step conversion process. The transformation first converts OKLCH cylindrical
+# coordinates to OKLAB rectangular coordinates, then applies the standard OKLAB to sRGB
+# transformation pipeline to produce the final gamma-corrected sRGB values.
+#
+# Key features:
+# - Two-stage conversion pipeline: OKLCH → OKLAB → sRGB
+# - Leverages existing OklchToOklab and OklabToSrgb converters for modular transformation
+# - Converts cylindrical coordinates (lightness, chroma, hue) to display-ready RGB values
+# - Maintains alpha channel transparency values during conversion
+# - Applies proper gamma correction for display on standard monitors and web applications
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper OKLCH source data
+#
+# The sRGB color space is the standard RGB color space for web content and most consumer
+# displays, providing gamma-corrected values that properly represent colors on typical
+# display devices while maintaining compatibility with web standards and digital media formats.
 
 require_relative "oklch_to_oklab"
 require_relative "oklab_to_srgb"
@@ -6,6 +24,12 @@ require_relative "oklab_to_srgb"
 module Abachrome
   module Converters
     class OklchToSrgb < Abachrome::Converters::Base
+      # Converts a color from OKLCH color space to sRGB color space.
+      # This is done by first converting from OKLCH to OKLAB,
+      # then from OKLAB to sRGB.
+      # 
+      # @param oklch_color [Abachrome::Color] Color in OKLCH color space
+      # @return [Abachrome::Color] The converted color in sRGB color space
       def self.convert(oklch_color)
         # Convert OKLCh to OKLab first
         oklab_color = OklchToOklab.convert(oklch_color)
@@ -15,4 +39,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/converters/srgb_to_lrgb.rb

@@ -1,8 +1,26 @@
-# frozen_string_literal: true
+# Abachrome::Converters::SrgbToLrgb - sRGB to Linear RGB color space converter
+#
+# This converter transforms colors from the standard RGB (sRGB) color space to the linear RGB (LRGB) color space by removing gamma correction. The conversion process applies the inverse sRGB transfer function which uses different formulas for small and large values to convert from the gamma-corrected sRGB representation to linear light intensity values.
+#
+# Key features:
+# - Implements the standard sRGB to linear RGB conversion algorithm with precise threshold handling
+# - Converts gamma-corrected sRGB values to linear RGB values for accurate color calculations
+# - Applies different transformation functions based on value magnitude (linear vs power function)
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper sRGB source data
+#
+# The linear RGB color space provides a linear relationship between stored numeric values and actual light intensity, making it essential for accurate color calculations and serving as an intermediate color space for many color transformations, particularly when converting between different color models.
 
 module Abachrome
   module Converters
     class SrgbToLrgb
+      # Converts a color from sRGB color space to linear RGB color space.
+      # This method performs gamma correction by linearizing each sRGB coordinate.
+      # 
+      # @param srgb_color [Abachrome::Color] A color object in the sRGB color space
+      # @return [Abachrome::Color] A new color object in the linear RGB (LRGB) color space
+      # with the same alpha value as the input color
       def self.convert(srgb_color)
         r, g, b = srgb_color.coordinates.map { |c| to_linear(AbcDecimal(c)) }
 
@@ -13,6 +31,12 @@ module Abachrome
         )
       end
 
+      # Converts a sRGB component to its linear RGB equivalent.
+      # This conversion applies the appropriate gamma correction to transform an sRGB value
+      # into a linear RGB value.
+      # 
+      # @param v [AbcDecimal, Numeric] The sRGB component value to convert (typically in range 0-1)
+      # @return [AbcDecimal] The corresponding linear RGB component value
       def self.to_linear(v)
         v_abs = v.abs
         v_sign = v.negative? ? -1 : 1
@@ -24,4 +48,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/converters/srgb_to_oklab.rb

@@ -1,8 +1,34 @@
-# frozen_string_literal: true
+# Abachrome::Converters::SrgbToOklab - sRGB to OKLAB color space converter
+#
+# This converter transforms colors from the standard RGB (sRGB) color space to the OKLAB color space
+# through a two-step conversion process. The transformation first converts sRGB gamma-corrected
+# values to linear RGB as an intermediate step, then applies the standard OKLAB transformation
+# matrices to produce the final perceptually uniform OKLAB coordinates.
+#
+# Key features:
+# - Two-stage conversion pipeline: sRGB → Linear RGB → OKLAB
+# - Leverages existing SrgbToLrgb and LrgbToOklab converters for modular transformation
+# - Removes gamma correction and applies perceptual uniformity transformations
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper sRGB source data
+#
+# The OKLAB color space provides better perceptual uniformity compared to traditional RGB spaces,
+# making it ideal for color manipulation operations like blending, lightness adjustments, and
+# gamut mapping where human visual perception accuracy is important. This converter enables
+# seamless transformation from display-ready sRGB values to the scientifically accurate OKLAB
+# representation for advanced color processing workflows.
 
 module Abachrome
   module Converters
     class SrgbToOklab
+      # Converts a color from sRGB color space to Oklab color space.
+      # The conversion happens in two steps:
+      # 1. sRGB is first converted to linear RGB
+      # 2. Linear RGB is then converted to Oklab
+      # 
+      # @param srgb_color [Abachrome::Color] The color in sRGB color space to convert
+      # @return [Abachrome::Color] The converted color in Oklab color space
       def self.convert(srgb_color)
         # First convert sRGB to linear RGB
         lrgb_color = SrgbToLrgb.convert(srgb_color)
@@ -12,4 +38,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/converters/srgb_to_oklch.rb

@@ -1,4 +1,22 @@
-# frozen_string_literal: true
+# Abachrome::Converters::SrgbToOklch - sRGB to OKLCH color space converter
+#
+# This converter transforms colors from the standard RGB (sRGB) color space to the OKLCH color space
+# through a two-step conversion process. The transformation first converts sRGB gamma-corrected
+# values to OKLAB rectangular coordinates as an intermediate step, then applies cylindrical coordinate
+# conversion to produce the final OKLCH values with lightness, chroma, and hue components.
+#
+# Key features:
+# - Two-stage conversion pipeline: sRGB → OKLAB → OKLCH
+# - Leverages existing SrgbToOklab and OklabToOklch converters for modular transformation
+# - Converts display-ready RGB values to perceptually uniform cylindrical coordinates
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper sRGB source data
+#
+# The OKLCH color space provides an intuitive interface for color manipulation through its
+# cylindrical coordinate system, making it ideal for hue adjustments, saturation modifications,
+# and other color operations that benefit from polar coordinates while maintaining perceptual
+# uniformity for natural-looking color transformations.
 
 require_relative "srgb_to_oklab"
 require_relative "oklab_to_oklch"
@@ -6,6 +24,13 @@ require_relative "oklab_to_oklch"
 module Abachrome
   module Converters
     class SrgbToOklch < Abachrome::Converters::Base
+      # Converts an sRGB color to OKLCH color space
+      # 
+      # @param srgb_color [Abachrome::Color] The color in sRGB color space to convert
+      # @return [Abachrome::Color] The converted color in OKLCH color space
+      # @note This is a two-step conversion process: first from sRGB to OKLab, then from OKLab to OKLCH
+      # @see SrgbToOklab
+      # @see OklabToOklch
       def self.convert(srgb_color)
         # First convert sRGB to OKLab
         oklab_color = SrgbToOklab.convert(srgb_color)
@@ -15,4 +40,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/gamut/base.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: true
+#
 
 module Abachrome
   module Gamut
@@ -69,4 +69,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/gamut/p3.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: true
+#
 
 module Abachrome
   module Gamut
@@ -22,4 +22,4 @@ module Abachrome
 
     register(P3.new)
   end
-end
+end

data/lib/abachrome/gamut/rec2020.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: true
+#
 
 lib
 abachrome
@@ -20,4 +20,4 @@ module Abachrome
 
     register(Rec2020.new)
   end
-end
+end