abachrome 0.1.0 → 0.1.2

data/lib/abachrome/color.rb

@@ -1,4 +1,22 @@
-# frozen_string_literal: true
+# Abachrome::Color - Core color representation class
+#
+# This is the central color class that represents colors across multiple color spaces
+# including sRGB, OKLAB, OKLCH, and linear RGB. The Color class encapsulates color
+# coordinates, alpha values, and color space information while providing methods
+# for color creation, conversion, and manipulation.
+#
+# Key features:
+# - Create colors from RGB, OKLAB, OKLCH values with factory methods
+# - Automatic coordinate validation against color space definitions
+# - Immutable color objects with equality and hash support
+# - Extensible through mixins for color space conversions and operations
+# - High-precision decimal arithmetic using AbcDecimal for accurate calculations
+# - Support for alpha (opacity) values with proper handling in conversions
+#
+# The class uses a mixin system to dynamically include functionality for converting
+# between color spaces, blending operations, and lightness adjustments. All coordinate
+# values are stored as AbcDecimal objects to maintain precision during color science
+# calculations and transformations.
 
 require "dry-inflector"
 require_relative "abc_decimal"
@@ -8,6 +26,13 @@ module Abachrome
   class Color
     attr_reader :color_space, :coordinates, :alpha
 
+    # Initializes a new Color object with the specified color space, coordinates, and alpha value.
+    # 
+    # @param color_space [ColorSpace] The color space for this color instance
+    # @param coordinates [Array<Numeric, String>] The color coordinates in the specified color space
+    # @param alpha [Numeric, String] The alpha (opacity) value, between 0.0 and 1.0 (default: 1.0)
+    # @raise [ArgumentError] If the coordinates are invalid for the specified color space
+    # @return [Color] A new Color instance
     def initialize(color_space, coordinates, alpha = AbcDecimal("1.0"))
       @color_space = color_space
       @coordinates = coordinates.map { |c| AbcDecimal(c.to_s) }
@@ -25,21 +50,61 @@ module Abachrome
       include mixin_module
     end
 
+    # Creates a new Color instance from RGB values
+    # 
+    # @param r [Numeric] The red component value (typically 0-1)
+    # @param g [Numeric] The green component value (typically 0-1)
+    # @param b [Numeric] The blue component value (typically 0-1)
+    # @param a [Numeric] The alpha (opacity) component value (0-1), defaults to 1.0 (fully opaque)
+    # @return [Abachrome::Color] A new Color instance in the sRGB color space
     def self.from_rgb(r, g, b, a = 1.0)
       space = ColorSpace.find(:srgb)
       new(space, [r, g, b], a)
     end
 
+    # Creates a new Color instance from LRGB values
+    # 
+    # @param r [Numeric] The red component value (typically 0-1)
+    # @param g [Numeric] The green component value (typically 0-1)
+    # @param b [Numeric] The blue component value (typically 0-1)
+    # @param a [Numeric] The alpha (opacity) component value (0-1), defaults to 1.0 (fully opaque)
+    # @return [Abachrome::Color] A new Color instance in the sRGB color space
+    def self.from_lrgb(r, g, b, a = 1.0)
+      space = ColorSpace.find(:lrgb)
+      new(space, [r, g, b], a)
+    end
+
+    # Creates a new Color object with OKLAB values.
+    # 
+    # @param l [Float] The lightness component (L) of the OKLAB color space
+    # @param a [Float] The green-red component (a) of the OKLAB color space
+    # @param b [Float] The blue-yellow component (b) of the OKLAB color space
+    # @param alpha [Float] The alpha (opacity) value, from 0.0 to 1.0
+    # @return [Abachrome::Color] A new Color object in the OKLAB color space
     def self.from_oklab(l, a, b, alpha = 1.0)
       space = ColorSpace.find(:oklab)
       new(space, [l, a, b], alpha)
     end
 
+    # Creates a new color instance in the OKLCH color space.
+    # 
+    # @param l [Numeric] The lightness component (L), typically in range 0..1
+    # @param c [Numeric] The chroma component (C), typically starting from 0 with no upper bound
+    # @param h [Numeric] The hue component (H) in degrees, typically in range 0..360
+    # @param alpha [Float] The alpha (opacity) component, in range 0..1, defaults to 1.0 (fully opaque)
+    # @return [Abachrome::Color] A new Color instance in the OKLCH color space
     def self.from_oklch(l, c, h, alpha = 1.0)
       space = ColorSpace.find(:oklch)
       new(space, [l, c, h], alpha)
     end
 
+    # Compares this color instance with another for equality.
+    # 
+    # Two colors are considered equal if they have the same color space,
+    # coordinates, and alpha value.
+    # 
+    # @param other [Object] The object to compare with
+    # @return [Boolean] true if the colors are equal, false otherwise
     def ==(other)
       return false unless other.is_a?(Color)
 
@@ -48,14 +113,31 @@ module Abachrome
         alpha == other.alpha
     end
 
+    # Checks if this color is equal to another color object.
+    # 
+    # @param other [Object] The object to compare with
+    # @return [Boolean] true if the two colors are equal, false otherwise
+    # @see ==
     def eql?(other)
       self == other
     end
 
+    # Generates a hash code for this color instance
+    # based on its color space, coordinates, and alpha value.
+    # The method first converts these components to strings,
+    # then computes a hash of the resulting array.
+    # 
+    # @return [Integer] a hash code that can be used for equality comparison
+    # and as a hash key in Hash objects
     def hash
       [color_space, coordinates, alpha].map(&:to_s).hash
     end
 
+    # Returns a string representation of the color in the format "ColorSpaceName(coord1, coord2, coord3, alpha)"
+    # 
+    # @return [String] A human-readable string representation of the color showing its
+    # color space name, coordinate values rounded to 3 decimal places, and alpha value
+    # (if not 1.0)
     def to_s
       coord_str = coordinates.map { |c| c.to_f.round(3) }.join(", ")
       alpha_str = alpha == AbcDecimal.new("1.0") ? "" : ", #{alpha.to_f.round(3)}"
@@ -64,6 +146,11 @@ module Abachrome
 
     private
 
+    # Validates that the number of coordinates matches the expected number for the color space.
+    # Compares the size of the coordinates array with the number of coordinates
+    # defined in the associated color space.
+    # @raise [ArgumentError] when the number of coordinates doesn't match the color space definition
+    # @return [nil] if validation passes
     def validate_coordinates!
       return if coordinates.size == color_space.coordinates.size
 

data/lib/abachrome/color_mixins/blend.rb

@@ -1,8 +1,38 @@
-# frozen_string_literal: true
+# Abachrome::ColorMixins::Blend - Color blending and mixing functionality
+#
+# This mixin provides methods for blending and mixing colors together in various color spaces.
+# The blend operation interpolates between two colors by a specified amount, creating smooth
+# color transitions. All blending operations preserve alpha values and can be performed in
+# the current color space or a specified target color space for optimal results.
+#
+# Key features:
+# - Linear interpolation between colors with configurable blend amounts
+# - Support for blending in different color spaces (sRGB, OKLAB, OKLCH)
+# - Both non-destructive (blend/mix) and destructive (blend!/mix!) variants
+# - Automatic color space conversion when blending colors from different spaces
+# - High-precision decimal arithmetic for accurate color calculations
+#
+# The mixin includes both immutable methods that return new color instances and mutable
+# methods that modify the current color object in place, providing flexibility for
+# different use cases and performance requirements.
 
 module Abachrome
   module ColorMixins
     module Blend
+      # @method blend
+      # Interpolates between two colors, creating a new color that is a blend of the two.
+      # The blend happens in the specified color space or the current color space if none is provided.
+      # #
+      # @param [Abachrome::Color] other The color to blend with
+      # @param [Float, Integer, #to_d] amount The blend amount between 0 and 1, where 0 returns the original color and 1 returns the other color. Defaults to 0.5 (midpoint)
+      # @param [Symbol, nil] target_color_space The color space to perform the blend in (optional)
+      # @return [Abachrome::Color] A new color representing the blend of the two colors
+      # @example Blend two colors equally
+      #   red.blend(blue, 0.5)
+      # @example Blend with 25% of another color
+      #   red.blend(blue, 0.25)
+      # @example Blend in a specific color space
+      #   red.blend(blue, 0.5, target_color_space: :oklab)
       def blend(other, amount = 0.5, target_color_space: nil)
         amount = AbcDecimal(amount)
 
@@ -25,6 +55,14 @@ module Abachrome
         )
       end
 
+      # Blends this color with another color by the specified amount.
+      # This is a destructive version of the blend method, modifying the current
+      # color in place.
+      # 
+      # @param other [Abachrome::Color] The color to blend with
+      # @param amount [Float] The blend amount, between 0.0 and 1.0, where 0.0 is
+      # this color and 1.0 is the other color (default: 0.5)
+      # @return [Abachrome::Color] Returns self after modification
       def blend!(other, amount = 0.5)
         blended = blend(other, amount)
         @color_space = blended.color_space
@@ -33,13 +71,26 @@ module Abachrome
         self
       end
 
+      # Alias for the blend method that mixes two colors together.
+      # 
+      # @param other [Abachrome::Color] The color to mix with
+      # @param amount [Float] The amount to mix, between 0.0 and 1.0, where 0.0 returns the original color and 1.0 returns the other color (default: 0.5)
+      # @return [Abachrome::Color] A new color resulting from the mix of the two colors
       def mix(other, amount = 0.5)
         blend(other, amount)
       end
 
+      # Mix the current color with another color.
+      # 
+      # This method is an alias for blend!. It combines the current color with
+      # the provided color at the specified amount.
+      # 
+      # @param other [Abachrome::Color] The color to mix with the current color
+      # @param amount [Numeric] The amount of the other color to mix in, from 0 to 1 (default: 0.5)
+      # @return [self] Returns the modified color object
       def mix!(other, amount = 0.5)
         blend!(other, amount)
       end
     end
   end
-end
+end

data/lib/abachrome/color_mixins/lighten.rb

@@ -1,8 +1,32 @@
-# frozen_string_literal: true
+# Abachrome::ColorMixins::Lighten - Color lightness adjustment functionality
+#
+# This mixin provides methods for adjusting the lightness of colors by manipulating
+# the L (lightness) component in the OKLAB color space. The OKLAB color space is used
+# because it provides perceptually uniform lightness adjustments that appear more
+# natural to the human eye compared to adjustments in other color spaces.
+#
+# Key features:
+# - Lighten and darken colors with configurable amounts
+# - Both non-destructive (lighten/darken) and destructive (lighten!/darken!) variants
+# - Automatic clamping to valid lightness ranges [0, 1]
+# - High-precision decimal arithmetic for accurate color calculations
+# - Conversion to OKLAB color space for perceptually uniform adjustments
+#
+# The mixin includes both immutable methods that return new color instances and mutable
+# methods that modify the current color object in place, providing flexibility for
+# different use cases and performance requirements.
 
 module Abachrome
   module ColorMixins
     module Lighten
+      # Increases the lightness of a color by the specified amount in the OKLab color space.
+      # This method works by extracting the L (lightness) component from the OKLab
+      # representation of the color and increasing it by the given amount, ensuring
+      # the result stays within the valid range of [0, 1].
+      # 
+      # @param amount [Numeric] The amount to increase the lightness by, as a decimal
+      # value between 0 and 1. Defaults to 0.1 (10% increase).
+      # @return [Abachrome::Color] A new Color instance with increased lightness.
       def lighten(amount = 0.1)
         amount = AbcDecimal(amount)
         oklab = to_oklab
@@ -19,6 +43,13 @@ module Abachrome
         )
       end
 
+      # Increases the lightness of the color by the specified amount and modifies the current color object.
+      # This method changes the color in-place, mutating the current object. The color
+      # is converted to a lightness-based color space if needed to perform the operation.
+      # 
+      # @param amount [Float] The amount to increase the lightness by, as a decimal value
+      # between 0 and 1. Default is 0.1 (10% increase).
+      # @return [Abachrome::Color] Returns self for method chaining.
       def lighten!(amount = 0.1)
         lightened = lighten(amount)
         @color_space = lightened.color_space
@@ -27,13 +58,29 @@ module Abachrome
         self
       end
 
+      # Darkens a color by decreasing its lightness value.
+      # 
+      # This method is effectively a convenience wrapper around the {#lighten} method,
+      # passing a negative amount value to decrease the lightness instead of increasing it.
+      # 
+      # @param amount [Float] The amount to darken the color by, between 0 and 1.
+      # Defaults to 0.1 (10% darker).
+      # @return [Color] A new color instance with decreased lightness.
+      # @see #lighten
       def darken(amount = 0.1)
         lighten(-amount)
       end
 
+      # Decreases the lightness value of the color by the specified amount.
+      # Modifies the color in place.
+      # 
+      # @param amount [Float] The amount to darken the color by, as a value between 0 and 1.
+      # Defaults to 0.1 (10% darker).
+      # @return [Abachrome::Color] Returns self with the modified lightness value.
+      # @see #lighten!
       def darken!(amount = 0.1)
         lighten!(-amount)
       end
     end
   end
-end
+end

data/lib/abachrome/color_mixins/to_colorspace.rb

@@ -1,14 +1,46 @@
-# frozen_string_literal: true
+# Abachrome::ColorMixins::ToColorspace - Color space conversion functionality
+#
+# This mixin provides methods for converting colors between different color spaces within
+# the Abachrome library. It includes both immutable and mutable conversion methods that
+# allow colors to be transformed from their current color space to any registered target
+# color space, such as sRGB, OKLAB, OKLCH, or linear RGB.
+#
+# Key features:
+# - Convert colors to any registered color space with automatic converter lookup
+# - Both non-destructive (to_color_space/convert_to/in_color_space) and destructive variants
+# - Optimized to return the same object when no conversion is needed
+# - Flexible API with multiple method names for different use cases and preferences
+# - Integration with the Converter system for extensible color space transformations
+#
+# The mixin provides a consistent interface for color space conversions while maintaining
+# the precision and accuracy required for color science calculations through the use of
+# the underlying converter infrastructure.
 
 module Abachrome
   module ColorMixins
     module ToColorspace
+      # Converts the current color to the specified target color space.
+      # 
+      # This method transforms the current color into an equivalent color in a different
+      # color space. If the target space is the same as the current color space, no
+      # conversion is performed and the current color is returned.
+      # 
+      # @param target_space [Abachrome::ColorSpace] The target color space to convert to
+      # @return [Abachrome::Color] A new color object in the target color space, or self
+      # if the target space is the same as the current color space
       def to_color_space(target_space)
         return self if color_space == target_space
 
         Converter.convert(self, target_space.name)
       end
 
+      # Converts the color object to the specified target color space in-place.
+      # This method modifies the current object by changing its color space and
+      # coordinates to match the target color space.
+      # 
+      # @param target_space [Abachrome::ColorSpace] The color space to convert to
+      # @return [Abachrome::Color] Returns self with modified color space and coordinates
+      # @see #to_color_space The non-destructive version that returns a new color object
       def to_color_space!(target_space)
         unless color_space == target_space
           converted = to_color_space(target_space)
@@ -18,21 +50,54 @@ module Abachrome
         self
       end
 
+      # Convert this color to a different color space.
+      # 
+      # @param space_name [String, Symbol] The name of the target color space to convert to.
+      # @return [Abachrome::Color] A new Color object in the specified color space.
+      # @example
+      # # Convert a color from sRGB to OKLCH
+      # rgb_color.convert_to(:oklch)
+      # @see Abachrome::ColorSpace.find
+      # @see #to_color_space
       def convert_to(space_name)
         to_color_space(ColorSpace.find(space_name))
       end
 
+      # Converts this color to the specified color space in place.
+      # 
+      # @param space_name [String, Symbol] The name or identifier of the target color space to convert to.
+      # @return [Abachrome::Color] Returns self with its values converted to the specified color space.
+      # @raise [Abachrome::ColorSpaceNotFoundError] If the specified color space is not registered.
+      # @see Abachrome::ColorSpace.find
+      # @example
+      # red = Abachrome::Color.new(1, 0, 0, color_space: :srgb)
+      # red.convert_to!(:oklch) # Converts the red color to OKLCH space in place
       def convert_to!(space_name)
         to_color_space!(ColorSpace.find(space_name))
       end
 
+      # Convert a color to a specified color space.
+      # 
+      # @param space_name [Symbol, String] The name of the color space to convert to.
+      # @return [Abachrome::Color] A new Color instance in the specified color space.
+      # @example
+      # red_rgb = Abachrome::Color.new(:srgb, [1, 0, 0])
+      # red_lch = red_rgb.in_color_space(:oklch)
       def in_color_space(space_name)
         convert_to(space_name)
       end
 
+      # Converts the color to the specified color space and mutates the current object.
+      # 
+      # @param space_name [Symbol, String] The target color space to convert to (e.g., :oklch, :rgb, :lab)
+      # @return [Abachrome::Color] Returns self after conversion
+      # @see #convert_to!
+      # @example
+      # color = Abachrome::Color.new([255, 0, 0], :rgb)
+      # color.in_color_space!(:oklch) # Color is now in OKLCH space
       def in_color_space!(space_name)
         convert_to!(space_name)
       end
     end
   end
-end
+end

data/lib/abachrome/color_mixins/to_lrgb.rb

@@ -1,16 +1,49 @@
-# frozen_string_literal: true
+# Abachrome::ColorMixins::ToLrgb - Linear RGB color space conversion functionality
+#
+# This mixin provides methods for converting colors to the linear RGB (LRGB) color space,
+# which uses a linear relationship between stored numeric values and actual light intensity.
+# Linear RGB is essential for accurate color calculations and serves as an intermediate
+# color space for many color transformations, particularly when converting between
+# different color models.
+#
+# Key features:
+# - Convert colors to linear RGB with automatic converter lookup
+# - Both non-destructive (to_lrgb) and destructive (to_lrgb!) conversion methods
+# - Direct access to linear RGB components (lred, lgreen, lblue)
+# - Utility methods for RGB array and hex string output
+# - Optimized to return the same object when no conversion is needed
+# - High-precision decimal arithmetic for accurate color science calculations
+#
+# The linear RGB color space differs from standard sRGB by removing gamma correction,
+# making it suitable for mathematical operations like blending, lighting calculations,
+# and color space transformations that require linear light behavior.
 
 require_relative "../converter"
 
 module Abachrome
   module ColorMixins
     module ToLrgb
+      # Converts this color to the Linear RGB (LRGB) color space.
+      # This method transforms the current color to the linear RGB color space,
+      # which uses a linear relationship between the stored numeric value and
+      # the actual light intensity. If the color is already in the LRGB space,
+      # it returns the current object without conversion.
+      # 
+      # @return [Abachrome::Color] A new color object in the LRGB color space,
+      # or the original object if already in LRGB space
       def to_lrgb
         return self if color_space.name == :lrgb
 
         Converter.convert(self, :lrgb)
       end
 
+      # Converts the current color to the linear RGB (LRGB) color space and updates
+      # the receiver's state. If the color is already in LRGB space, this is a no-op.
+      # 
+      # Unlike #to_lrgb which returns a new color instance, this method modifies the
+      # current object by changing its color space and coordinates to the LRGB equivalent.
+      # 
+      # @return [Abachrome::Color] the receiver itself, now in LRGB color space
       def to_lrgb!
         unless color_space.name == :lrgb
           lrgb_color = to_lrgb
@@ -20,30 +53,65 @@ module Abachrome
         self
       end
 
+      # Returns the linear red component value of the color.
+      # 
+      # This method accesses the first coordinate from the color in linear RGB space.
+      # Linear RGB values differ from standard RGB by using a non-gamma-corrected
+      # linear representation of luminance.
+      # 
+      # @return [AbcDecimal] The linear red component value, typically in range [0, 1]
       def lred
         to_lrgb.coordinates[0]
       end
 
+      # Retrieves the linear green (lgreen) coordinate from a color by converting it to
+      # linear RGB color space first. Linear RGB uses a different scale than standard
+      # sRGB, with values representing linear light energy rather than gamma-corrected
+      # values.
+      # 
+      # @return [AbcDecimal] The linear green component value from the color's linear
+      # RGB representation
       def lgreen
         to_lrgb.coordinates[1]
       end
 
+      # Returns the linear blue channel value of this color after conversion to linear RGB color space.
+      # 
+      # This method converts the current color to the linear RGB color space and extracts the blue
+      # component (the third coordinate).
+      # 
+      # @return [AbcDecimal] The linear blue component value, typically in the range [0, 1]
       def lblue
         to_lrgb.coordinates[2]
       end
 
+      # Returns the coordinates of the color in the linear RGB color space.
+      # 
+      # @return [Array<AbcDecimal>] An array of three AbcDecimal values representing
+      # the red, green, and blue components in linear RGB color space.
       def lrgb_values
         to_lrgb.coordinates
       end
 
+      # Returns an array of sRGB values as integers in the 0-255 range.
+      # This method converts the color to RGB, scales the values to the 0-255 range,
+      # rounds to integers, and ensures they are clamped within the valid range.
+      # 
+      # @return [Array<Integer>] An array of three RGB integer values between 0-255
       def rgb_array
         to_rgb.coordinates.map { |c| (c * 255).round.clamp(0, 255) }
       end
 
+      # Returns a hexadecimal string representation of the color in RGB format.
+      # 
+      # @return [String] A hexadecimal color code in the format '#RRGGBB' where RR, GG, and BB
+      # are two-digit hexadecimal values for the red, green, and blue components respectively.
+      # @example
+      # color.rgb_hex  # => "#1a2b3c"
       def rgb_hex
         r, g, b = rgb_array
         format("#%02x%02x%02x", r, g, b)
       end
     end
   end
-end
+end

data/lib/abachrome/color_mixins/to_oklab.rb

@@ -1,16 +1,49 @@
-# frozen_string_literal: true
+# Abachrome::ColorMixins::ToOklab - OKLAB color space conversion functionality
+#
+# This mixin provides methods for converting colors to the OKLAB color space, which is a
+# perceptually uniform color space designed for better color manipulation and comparison.
+# OKLAB provides more intuitive lightness adjustments and color blending compared to
+# traditional RGB color spaces, making it ideal for color science applications.
+#
+# Key features:
+# - Convert colors to OKLAB with automatic converter lookup
+# - Both non-destructive (to_oklab) and destructive (to_oklab!) conversion methods
+# - Direct access to OKLAB components (lightness, a, b)
+# - Utility methods for OKLAB array and value extraction
+# - Optimized to return the same object when no conversion is needed
+# - High-precision decimal arithmetic for accurate color science calculations
+#
+# The OKLAB color space uses three components: L (lightness), a (green-red axis), and
+# b (blue-yellow axis), providing a more perceptually uniform representation of colors
+# that better matches human visual perception compared to traditional color spaces.
 
 require_relative "../converter"
 
 module Abachrome
   module ColorMixins
     module ToOklab
+      # Converts the current color to the OKLAB color space.
+      # 
+      # If the color is already in OKLAB, it returns the color unchanged.
+      # Otherwise, it uses the Converter to transform the color to OKLAB.
+      # 
+      # @return [Abachrome::Color] A new Color object in the OKLAB color space
       def to_oklab
         return self if color_space.name == :oklab
 
         Converter.convert(self, :oklab)
       end
 
+      # Converts the color to the OKLAB color space in place.
+      # This method transforms the current color into OKLAB space,
+      # modifying the original object by updating its color space
+      # and coordinates if not already in OKLAB.
+      # 
+      # @example
+      # color = Abachrome::Color.from_hex("#ff5500")
+      # color.to_oklab!  # Color now uses OKLAB color space
+      # 
+      # @return [Abachrome::Color] self, with updated color space and coordinates
       def to_oklab!
         unless color_space.name == :oklab
           oklab_color = to_oklab
@@ -20,29 +53,61 @@ module Abachrome
         self
       end
 
+      # Returns the lightness component (L) of the color in the OKLAB color space.
+      # The lightness value ranges from 0 (black) to 1 (white) and represents
+      # the perceived lightness of the color.
+      # 
+      # @return [AbcDecimal] The lightness (L) value from the OKLAB color space
       def lightness
         to_oklab.coordinates[0]
       end
 
+      # Returns the L (Lightness) component from the OKLAB color space.
+      # 
+      # The L value represents perceptual lightness in the OKLAB color space,
+      # typically ranging from 0 (black) to 1 (white).
+      # 
+      # @return [AbcDecimal] The L (Lightness) component from the OKLAB color space
       def l
         to_oklab.coordinates[0]
       end
 
+      # Returns the 'a' component from the OKLAB color space (green-red axis).
+      # 
+      # The 'a' component in OKLAB represents the position on the green-red axis,
+      # with negative values being more green and positive values being more red.
+      # 
+      # @return [AbcDecimal] The 'a' component value from the OKLAB color space.
+      # @see #to_oklab For the full conversion to OKLAB color space
       def a
         to_oklab.coordinates[1]
       end
 
+      # Returns the B value of the color in OKLAB color space.
+      # 
+      # This method first converts the color to OKLAB color space if needed,
+      # then extracts the B component (blue-yellow axis), which is the third
+      # coordinate in the OKLAB model.
+      # 
+      # @return [AbcDecimal] The B component value in OKLAB color space
       def b
         to_oklab.coordinates[2]
       end
 
+      # Returns the OKLAB color space coordinates for this color.
+      # 
+      # @return [Array] An array of OKLAB coordinates [L, a, b] representing the color in OKLAB color space
       def oklab_values
         to_oklab.coordinates
       end
 
+      # Returns an array representation of the color's coordinates in the OKLAB color space.
+      # 
+      # @return [Array<AbcDecimal>] An array containing the coordinates of the color
+      # in the OKLAB color space in the order [L, a, b]
       def oklab_array
         to_oklab.coordinates
       end
     end
   end
-end
+end