Add API docs with YARD (jfairbank#4)

Author: jfairbank

.yardopts

@@ -0,0 +1 @@
+--markup=markdown

lib/chroma.rb

@@ -38,20 +38,75 @@
 # Extensions
 require 'chroma/extensions/string'
 
+# The main module.
 module Chroma
   class << self
+    # Returns a new instance of color. Supports hexadecimal, rgb, rgba, hsl,
+    # hsla, hsv, hsva, and named color formats.
+    #
+    # @api public
+    #
+    # @example
+    #   Chroma.paint('red')
+    #   Chroma.paint('#f00')
+    #   Chroma.paint('#ff0000')
+    #   Chroma.paint('rgb(255, 0, 0)')
+    #   Chroma.paint('hsl(0, 100%, 50%)')
+    #   Chroma.paint('hsv(0, 100%, 100%)')
+    #
+    # @param input [String] the color
+    # @return      [Color]  an instance of {Color}
     def paint(input)
       Color.new(input)
     end
 
+    # Returns the hexadecimal string representation of a named color and nil
+    # if no match is found. Favors 3-character hexadecimal if possible.
+    #
+    # @example
+    #   Chroma.hex_from_name('red')       #=> 'f00'
+    #   Chroma.hex_from_name('aliceblue') #=> 'f0f8ff'
+    #   Chroma.hex_from_name('foo')       #=> nil
+    #
+    # @param name [String]      the color name
+    # @return     [String, nil] the color as a string hexadecimal or nil
     def hex_from_name(name)
       named_colors_map[name]
     end
 
+    # Returns the color name of a hexadecimal color if available and nil if no
+    # match is found. Requires 3-character hexadecimal input for applicable
+    # colors.
+    #
+    # @example
+    #   Chroma.name_from_hex('f00')    #=> 'red'
+    #   Chroma.name_from_hex('f0f8ff') #=> 'aliceblue'
+    #   Chroma.name_from_hex('123123') #=> nil
+    #
+    # @param hex [String]      the hexadecimal color
+    # @return    [String, nil] the color name or nil
     def name_from_hex(hex)
       hex_named_colors_map[hex]
     end
 
+    # Defines a custom palette for use by {Color#palette}. Uses a DSL inside
+    # `block` that mirrors the methods in {Color::Modifiers}.
+    #
+    # @example
+    #   'red'.paint.palette.respond_to? :my_palette #=> false
+    #
+    #   Chroma.define_palette :my_palette do
+    #     spin 60
+    #     spin 120
+    #     spin 240
+    #   end
+    #
+    #   'red'.paint.palette.respond_to? :my_palette #=> true
+    #
+    # @param name  [Symbol, String]              the name of the custom palette
+    # @param block [Proc]                        the palette definition block
+    # @raise       [Errors::PaletteDefinedError] if the palette is already defined
+    # @return      [Symbol, String]              the name of the custom palette
     def define_palette(name, &block)
       if Harmonies.method_defined? name
         raise Errors::PaletteDefinedError, "Palette `#{name}' already exists"

lib/chroma/color.rb

@@ -1,34 +1,83 @@
 module Chroma
+  # The main class to represent colors.
   class Color
     include Attributes
     include Serializers
     include Modifiers
     include Helpers::Bounders
 
+    # @param input  [String, ColorModes::Rgb, ColorModes::Hsl, ColorModes::Hsv]
+    # @param format [Symbol] the color mode format
     def initialize(input, format = nil)
       @input = input
       @rgb, gen_format = generate_rgb_and_format(input)
       @format = format || gen_format
     end
 
+    # Returns self. Useful for ducktyping situations with {String#paint}.
+    #
+    # @example
+    #   red = 'red'.paint
+    #
+    #   red.paint            #=> red
+    #   red.paint.equal? red #=> true
+    #
+    # @return [self]
     def paint
       self
     end
 
+    # Returns true if `self` is equal to `other` and they're both instances of
+    # {Color}.
+    #
+    # @example
+    #   red = 'red'.paint
+    #   blue = 'blue'.paint
+    #
+    #   red.eql? red          #=> true
+    #   red.eql? blue         #=> false
+    #   red.eql? '#f00'.paint #=> true
+    #
+    # @param other [Color]
+    # @return      [true, false]
     def eql?(other)
       self.class == other.class && self == other
     end
 
+    # Returns true if both are equal in value.
+    #
+    # @example
+    #   red = 'red'.paint
+    #   blue = 'blue'.paint
+    #
+    #   red == red          #=> true
+    #   red == blue         #=> false
+    #   red == '#f00'.paint #=> true
+    #
+    # @param other [Color]
+    # @return      [true, false]
     def ==(other)
       to_hex == other.to_hex
     end
 
+    # Returns the complementary color.
+    #
+    # @example
+    #   'red'.paint.complement #=> cyan
+    #
+    # @return [Color] the complementary color
     def complement
       hsl = self.hsl
       hsl.h = (hsl.h + 180) % 360
       self.class.new(hsl, @format)
     end
 
+    # Returns an instance of {Harmonies} from which to call a palette method.
+    #
+    # @example
+    #   'red'.paint.palette #=> #<Chroma::Harmonies:0x007faf6b9f9148 @color=red>
+    #
+    # @return [Harmonies]
     def palette
       Harmonies.new(self)
     end

lib/chroma/color/attributes.rb

@@ -1,20 +1,49 @@
 module Chroma
   class Color
+    # Attribute methods for {Color}.
     module Attributes
       attr_reader :format
 
+      # Determines if the color is dark.
+      #
+      # @example
+      #   'red'.paint.dark?    #=> true
+      #   'yellow'.paint.dark? #=> false
+      #
+      # @return [true, false]
       def dark?
         brightness < 128
       end
 
+      # Determines if the color is light.
+      #
+      # @example
+      #   'red'.paint.light?    #=> false
+      #   'yellow'.paint.light? #=> true
+      #
+      # @return [true, false]
       def light?
         !dark?
       end
 
+      # Returns the alpha channel value.
+      #
+      # @example
+      #   'red'.paint.alpha                #=> 1.0
+      #   'rgba(0, 0, 0, 0.5)'.paint.alpha #=> 0.5
+      #
+      # @return [Float]
       def alpha
         @rgb.a
       end
 
+      # Calculates the brightness.
+      #
+      # @example
+      #   'red'.paint.brightness    #=> 76.245
+      #   'yellow'.paint.brightness #=> 225.93
+      #
+      # @return [Float]
       def brightness
         (@rgb.r * 299 + @rgb.g * 587 + @rgb.b * 114) / 1000.0
       end

lib/chroma/color/modifiers.rb

@@ -1,12 +1,29 @@
 module Chroma
   class Color
+    # Methods that return a new modified {Color}.
     module Modifiers
+      # Lightens the color by the given `amount`.
+      #
+      # @example
+      #   'red'.paint.lighten     #=> #ff3333
+      #   'red'.paint.lighten(20) #=> #ff6666
+      #
+      # @param amount [Fixnum]
+      # @return       [Color]
       def lighten(amount = 10)
         hsl = self.hsl
         hsl.l = clamp01(hsl.l + amount / 100.0)
         self.class.new(hsl, @format)
       end
 
+      # Brightens the color by the given `amount`.
+      #
+      # @example
+      #   'red'.paint.brighten     #=> #ff1919
+      #   'red'.paint.brighten(20) #=> #ff3333
+      #
+      # @param amount [Fixnum]
+      # @return       [Color]
       def brighten(amount = 10)
         # Don't include alpha
         rgb = @rgb.to_a[0..2].map(&:round)
@@ -19,30 +36,69 @@ def brighten(amount = 10)
         self.class.new(ColorModes::Rgb.new(*rgb), @format)
       end
 
+      # Darkens the color by the given `amount`.
+      #
+      # @example
+      #   'red'.paint.darken     #=> #cc0000
+      #   'red'.paint.darken(20) #=> #990000
+      #
+      # @param amount [Fixnum]
+      # @return       [Color]
       def darken(amount = 10)
         hsl = self.hsl
         hsl.l = clamp01(hsl.l - amount / 100.0)
         self.class.new(hsl, @format)
       end
 
+      # Desaturates the color by the given `amount`.
+      #
+      # @example
+      #   'red'.paint.desaturate     #=> #f20d0d
+      #   'red'.paint.desaturate(20) #=> #e61919
+      #
+      # @param amount [Fixnum]
+      # @return       [Color]
       def desaturate(amount = 10)
         hsl = self.hsl
         hsl.s = clamp01(hsl.s - amount / 100.0)
         self.class.new(hsl, @format)
       end
 
+      # Saturates the color by the given `amount`.
+      #
+      # @example
+      #   '#123'.paint.saturate     #=> #0e2236
+      #   '#123'.paint.saturate(20) #=> #0a223a
+      #
+      # @param amount [Fixnum]
+      # @return       [Color]
       def saturate(amount = 10)
         hsl = self.hsl
         hsl.s = clamp01(hsl.s + amount / 100.0)
         self.class.new(hsl, @format)
       end
 
+      # Converts the color to grayscale.
+      #
+      # @example
+      #   'green'.paint.greyscale #=> #404040
+      #
+      # @return [Color]
       def grayscale
         desaturate(100)
       end
 
       alias_method :greyscale, :grayscale
 
+      # Spins around the hue color wheel by `amount` in degrees.
+      #
+      # @example
+      #   'red'.paint.spin(30) #=> #ff80000
+      #   'red'.paint.spin(60) #=> yellow
+      #   'red'.paint.spin(90) #=> #80ff00
+      #
+      # @param amount [Fixnum]
+      # @return       [Color]
       def spin(amount)
         hsl = self.hsl
         hue = (hsl.h.round + amount) % 360