sass 3.3.0.alpha.196 → 3.3.0.alpha.198

data/REVISION

@@ -1 +1 @@
-3815575f97174247159cff208be7ef0d7feed874
+be5f2f981c18818dbb8dd8b08f13262bbf112ef1

data/VERSION

@@ -1 +1 @@
-3.3.0.alpha.196
+3.3.0.alpha.198

data/VERSION_DATE

@@ -1 +1 @@
-02 July 2013 23:14:47 GMT
+03 July 2013 00:40:44 GMT

data/lib/sass/script/functions.rb

@@ -2,7 +2,7 @@ module Sass::Script
   # Methods in this module are accessible from the SassScript context.
   # For example, you can write
   #
-  #     $color = hsl(120deg, 100%, 50%)
+  #     $color: hsl(120deg, 100%, 50%)
   #
   # and it will call {Functions#hsl}.
   #
@@ -13,13 +13,12 @@ module Sass::Script
   # ## RGB Functions
   #
   # \{#rgb rgb($red, $green, $blue)}
-  # : Converts an `rgb(red, green, blue)` triplet into a color.
+  # : Creates a {Sass::Script::Value::Color Color} from red, green, and blue
+  #   values.
   #
   # \{#rgba rgba($red, $green, $blue, $alpha)}
-  # : Converts an `rgba(red, green, blue, alpha)` quadruplet into a color.
-  #
-  # \{#rgba rgba($color, $alpha)}
-  # : Adds an alpha layer to any color value.
+  # : Creates a {Sass::Script::Value::Color Color} from red, green, blue, and
+  #   alpha values.
   #
   # \{#red red($color)}
   # : Gets the red component of a color.
@@ -36,10 +35,12 @@ module Sass::Script
   # ## HSL Functions
   #
   # \{#hsl hsl($hue, $saturation, $lightness)}
-  # : Converts an `hsl(hue, saturation, lightness)` triplet into a color.
+  # : Creates a {Sass::Script::Value::Color Color} from hue, saturation, and
+  #   lightness values.
   #
   # \{#hsla hsla($hue, $saturation, $lightness, $alpha)}
-  # : Converts an `hsla(hue, saturation, lightness, alpha)` quadruplet into a color.
+  # : Creates a {Sass::Script::Value::Color Color} from hue, saturation,
+  #   lightness, lightness, and alpha values.
   #
   # \{#hue hue($color)}
   # : Gets the hue component of a color.
@@ -80,7 +81,7 @@ module Sass::Script
   # : Gets the alpha component (opacity) of a color.
   #
   # \{#rgba rgba($color, $alpha)}
-  # : Add or change an alpha layer for any color value.
+  # : Changes the alpha component for a color.
   #
   # \{#opacify opacify($color, $amount)} / \{#fade_in fade-in($color, $amount)}
   # : Makes a color more opaque.
@@ -91,10 +92,10 @@ module Sass::Script
   # ## Other Color Functions
   #
   # \{#adjust_color adjust-color($color, \[$red\], \[$green\], \[$blue\], \[$hue\], \[$saturation\], \[$lightness\], \[$alpha\])}
-  # : Increase or decrease any of the components of a color.
+  # : Increases or decreases one or more components of a color.
   #
   # \{#scale_color scale-color($color, \[$red\], \[$green\], \[$blue\], \[$saturation\], \[$lightness\], \[$alpha\])}
-  # : Fluidly scale one or more components of a color.
+  # : Fluidly scales one or more properties of a color.
   #
   # \{#change_color change-color($color, \[$red\], \[$green\], \[$blue\], \[$hue\], \[$saturation\], \[$lightness\], \[$alpha\])}
   # : Changes one or more properties of a color.
@@ -105,7 +106,7 @@ module Sass::Script
   # ## String Functions
   #
   # \{#unquote unquote($string)}
-  # : Removes the quotes from a string.
+  # : Removes quotes from a string.
   #
   # \{#quote quote($string)}
   # : Adds quotes to a string.
@@ -114,13 +115,13 @@ module Sass::Script
   # : Returns the number of characters in a string.
   #
   # \{#str_insert str-insert($string, $insert, $index)}
-  # : Inserts the second string into the first string at the specified index.
+  # : Inserts `$insert` into `$string` at `$index`.
   #
   # \{#str_index str-index($string, $substring)}
-  # : Returns the index where a substring is found in another string or 0 if not found.
+  # : Returns the index of the first occurance of `$substring` in `$string`.
   #
-  # \{#str_slice str-slice($string, $start, $end)}
-  # : Extracts a substring of characters from $string
+  # \{#str_slice str-slice($string, $start-at, [$end-at])}
+  # : Extracts a substring from `$string`.
   #
   # \{#to_upper_case to-upper-case($string)}
   # : Converts a string to upper case.
@@ -137,19 +138,19 @@ module Sass::Script
   # : Rounds a number to the nearest whole number.
   #
   # \{#ceil ceil($value)}
-  # : Rounds a number up to the nearest whole number.
+  # : Rounds a number up to the next whole number.
   #
   # \{#floor floor($value)}
-  # : Rounds a number down to the nearest whole number.
+  # : Rounds a number down to the previous whole number.
   #
   # \{#abs abs($value)}
   # : Returns the absolute value of a number.
   #
-  # \{#min min($x1, $x2, ...)\}
-  # : Finds the minimum of several values.
+  # \{#min min($numbers...)\}
+  # : Finds the minimum of several numbers.
   #
-  # \{#max max($x1, $x2, ...)\}
-  # : Finds the maximum of several values.
+  # \{#max max($numbers...)\}
+  # : Finds the maximum of several numbers.
   #
   # ## List Functions {#list-functions}
   #
@@ -165,11 +166,11 @@ module Sass::Script
   # \{#append append($list1, $val, \[$separator\])}
   # : Appends a single value onto the end of a list.
   #
-  # \{#zip zip($list1, $list2, ...)}
+  # \{#zip zip($lists...)}
   # : Combines several lists into a single multidimensional list.
   #
   # \{#index index($list, $value)}
-  # : Returns the position of a value within a list, or false.
+  # : Returns the position of a value within a list.
   #
   # \{#list_separator list-separator(#list)}
   # : Returns the separator of a list.
@@ -177,24 +178,25 @@ module Sass::Script
   # ## Introspection Functions
   #
   # \{#feature_exists feature-exists($feature)}
-  # : Returns whether the named feature exists in the current sass runtime.
+  # : Returns whether a feature exists in the current Sass runtime.
   #
   # \{#type_of type-of($value)}
   # : Returns the type of a value.
   #
   # \{#unit unit($number)}
-  # : Returns the units associated with a number.
+  # : Returns the unit(s) associated with a number.
   #
   # \{#unitless unitless($number)}
-  # : Returns whether a number has units or not.
+  # : Returns whether a number has units.
   #
   # \{#comparable comparable($number-1, $number-2)}
-  # : Returns whether two numbers can be added or compared.
+  # : Returns whether two numbers can be added, subtracted, or compared.
   #
   # ## Miscellaneous Functions
   #
   # \{#if if($condition, $if-true, $if-false)}
-  # : Returns one of two values, depending on whether or not a condition is true.
+  # : Returns one of two values, depending on whether or not `$condition` is
+  #   true.
   #
   # \{#unique_id unique-id()}
   # : Returns a unique CSS identifier.
@@ -274,6 +276,12 @@ module Sass::Script
     # but none of them but the first will be used
     # unless the user uses keyword arguments.
     #
+    # @example
+    #   declare :rgba, [:hex, :alpha]
+    #   declare :rgba, [:red, :green, :blue, :alpha]
+    #   declare :accepts_anything, [], :var_args => true, :var_kwargs => true
+    #   declare :some_func, [:foo, :bar, :baz], :var_kwargs => true
+    #
     # @param method_name [Symbol] The name of the method
     #   whose signature is being declared.
     # @param args [Array<Symbol>] The names of the arguments for the function signature.
@@ -287,12 +295,6 @@ module Sass::Script
     #   to {Value}s as the last argument.
     #   In addition, if this is true and `:var_args` is not,
     #   Sass will ensure that the last argument passed is a hash.
-    #
-    # @example
-    #   declare :rgba, [:hex, :alpha]
-    #   declare :rgba, [:red, :green, :blue, :alpha]
-    #   declare :accepts_anything, [], :var_args => true, :var_kwargs => true
-    #   declare :some_func, [:foo, :bar, :baz], :var_kwargs => true
     def self.declare(method_name, args, options = {})
       @signatures[method_name] ||= []
       @signatures[method_name] << Signature.new(
@@ -370,14 +372,14 @@ module Sass::Script
       # @example
       #   assert_type value, :String
       #   assert_type value, :Number
-      # @param value [Value] A SassScript value
+      # @param value [Sass::Script::Value::Base] A SassScript value
       # @param type [Symbol] The name of the type the value is expected to be
-      # @param name [String, nil] The name of the argument.
+      # @param name [String, Symbol, nil] The name of the argument.
       # @raise [ArgumentError] if value is not of the correct type.
       def assert_type(value, type, name = nil)
         return if value.is_a?(Sass::Script::Value.const_get(type))
         err = "#{value.inspect} is not a #{type.to_s.downcase}"
-        err = "$#{name}: " + err if name
+        err = "$#{name.to_s.gsub('_', '-')}: " + err if name
         raise ArgumentError.new(err)
       end
 
@@ -442,29 +444,31 @@ module Sass::Script
     # Creates a {Sass::Script::Value::Color Color} object from red, green, and
     # blue values.
     #
-    # @param red [Sass::Script::Value::Number]
-    #   A number between 0 and 255 inclusive,
-    #   or between 0% and 100% inclusive
-    # @param green [Sass::Script::Value::Number]
-    #   A number between 0 and 255 inclusive,
-    #   or between 0% and 100% inclusive
-    # @param blue [Sass::Script::Value::Number]
-    #   A number between 0 and 255 inclusive,
-    #   or between 0% and 100% inclusive
     # @see #rgba
+    # @overload rgb($red, $green, $blue)
+    # @param $red [Sass::Script::Value::Number] The amount of red in the color.
+    #   Must be between 0 and 255 inclusive, or between `0%` and `100%`
+    #   inclusive
+    # @param $green [Sass::Script::Value::Number] The amount of green in the
+    #   color. Must be between 0 and 255 inclusive, or between `0%` and `100%`
+    #   inclusive
+    # @param $blue [Sass::Script::Value::Number] The amount of blue in the
+    #   color. Must be between 0 and 255 inclusive, or between `0%` and `100%`
+    #   inclusive
     # @return [Sass::Script::Value::Color]
+    # @raise [ArgumentError] if any parameter is the wrong type or out of bounds
     def rgb(red, green, blue)
-      assert_type red, :Number
-      assert_type green, :Number
-      assert_type blue, :Number
+      assert_type red, :Number, :red
+      assert_type green, :Number, :green
+      assert_type blue, :Number, :blue
 
-      Sass::Script::Value::Color.new([red, green, blue].map do |c|
+      Sass::Script::Value::Color.new([[red, :red], [green, :green], [blue, :blue]].map do |(c, name)|
           v = c.value
           if c.is_unit?("%")
-            v = Sass::Util.check_range("Color value", 0..100, c, '%')
+            v = Sass::Util.check_range("$#{name}: Color value", 0..100, c, '%')
             v * 255 / 100.0
           elsif c.unitless?
-            Sass::Util.check_range("Color value", 0..255, c)
+            Sass::Util.check_range("$#{name}: Color value", 0..255, c)
           else
             raise ArgumentError.new("Expected #{c} to be unitless or have a unit of % but got #{c}")
           end
@@ -472,39 +476,44 @@ module Sass::Script
     end
     declare :rgb, [:red, :green, :blue]
 
+    # Creates a {Sass::Script::Value::Color Color} from red, green, blue, and
+    # alpha values.
     # @see #rgb
-    # @overload rgba(red, green, blue, alpha)
-    #   Creates a {Sass::Script::Value::Color Color} object from red, green, and
-    #   blue values, as well as an alpha channel indicating opacity.
-    #
-    #   @param red [Sass::Script::Value::Number]
-    #     A number between 0 and 255 inclusive
-    #   @param green [Sass::Script::Value::Number]
-    #     A number between 0 and 255 inclusive
-    #   @param blue [Sass::Script::Value::Number]
-    #     A number between 0 and 255 inclusive
-    #   @param alpha [Sass::Script::Value::Number]
-    #     A number between 0 and 1
+    #
+    # @overload rgba($red, $green, $blue, $alpha)
+    #   @param $red [Sass::Script::Value::Number] The amount of red in the
+    #     color. Must be between 0 and 255 inclusive
+    #   @param $green [Sass::Script::Value::Number] The amount of green in the
+    #     color. Must be between 0 and 255 inclusive
+    #   @param $blue [Sass::Script::Value::Number] The amount of blue in the
+    #     color. Must be between 0 and 255 inclusive
+    #   @param $alpha [Sass::Script::Value::Number] The opacity of the color.
+    #     Must be between 0 and 1 inclusive
     #   @return [Sass::Script::Value::Color]
+    #   @raise [ArgumentError] if any parameter is the wrong type or out of
+    #     bounds
     #
-    # @overload rgba(color, alpha)
-    #   Sets the opacity of a color.
+    # @overload rgba($color, $alpha)
+    #   Sets the opacity of an existing color.
     #
     #   @example
     #     rgba(#102030, 0.5) => rgba(16, 32, 48, 0.5)
     #     rgba(blue, 0.2)    => rgba(0, 0, 255, 0.2)
     #
-    #   @param color [Sass::Script::Value::Color]
-    #   @param alpha [Sass::Script::Value::Number]
-    #     A number between 0 and 1
+    #   @param $color [Sass::Script::Value::Color] The color whose opacity will
+    #     be changed.
+    #   @param $alpha [Sass::Script::Value::Number] The new opacity of the
+    #     color. Must be between 0 and 1 inclusive
     #   @return [Sass::Script::Value::Color]
+    #   @raise [ArgumentError] if `$alpha` is out of bounds or either parameter
+    #     is the wrong type
     def rgba(*args)
       case args.size
       when 2
         color, alpha = args
 
-        assert_type color, :Color
-        assert_type alpha, :Number
+        assert_type color, :Color, :color
+        assert_type alpha, :Number, :alpha
 
         Sass::Util.check_range('Alpha channel', 0..1, alpha)
         color.with(:alpha => alpha.value)
@@ -518,43 +527,51 @@ module Sass::Script
     declare :rgba, [:red, :green, :blue, :alpha]
     declare :rgba, [:color, :alpha]
 
-    # Creates a {Sass::Script::Value::Color Color} object from hue, saturation,
-    # and lightness. Uses the algorithm from the [CSS3 spec](http://www.w3.org/TR/css3-color/#hsl-color).
+    # Creates a {Sass::Script::Value::Color Color} from hue, saturation, and
+    # lightness values. Uses the algorithm from the [CSS3 spec][].
+    #
+    # [CSS3 spec]: http://www.w3.org/TR/css3-color/#hsl-color
     #
-    # @param hue [Sass::Script::Value::Number]
-    #   The hue of the color. Should be between 0 and 360 degrees, inclusive
-    # @param saturation [Sass::Script::Value::Number]
-    #   The saturation of the color. Must be between `0%` and `100%`, inclusive
-    # @param lightness [Sass::Script::Value::Number]
-    #   The lightness of the color. Must be between `0%` and `100%`, inclusive
-    # @return [Sass::Script::Value::Color] The resulting color
     # @see #hsla
-    # @raise [ArgumentError] if `saturation` or `lightness` are out of bounds
+    # @overload hsl($hue, $saturation, $lightness)
+    # @param $hue [Sass::Script::Value::Number] The hue of the color. Should be
+    #   between 0 and 360 degrees, inclusive
+    # @param $saturation [Sass::Script::Value::Number] The saturation of the
+    #   color. Must be between `0%` and `100%`, inclusive
+    # @param $lightness [Sass::Script::Value::Number] The lightness of the
+    #   color. Must be between `0%` and `100%`, inclusive
+    # @return [Sass::Script::Value::Color]
+    # @raise [ArgumentError] if `$saturation` or `$lightness` are out of bounds
+    #   or any parameter is the wrong type
     def hsl(hue, saturation, lightness)
       hsla(hue, saturation, lightness, Sass::Script::Value::Number.new(1))
     end
     declare :hsl, [:hue, :saturation, :lightness]
 
-    # Creates a {Sass::Script::Value::Color Color} object from hue, saturation,
-    # and lightness, as well as an alpha channel indicating opacity. Uses the
-    # algorithm from the [CSS3 spec](http://www.w3.org/TR/css3-color/#hsl-color).
-    #
-    # @param hue [Sass::Script::Value::Number] The hue of the color.
-    #   Should be between 0 and 360 degrees, inclusive
-    # @param saturation [Sass::Script::Value::Number] The saturation of the color.
-    #   Must be between `0%` and `100%`, inclusive
-    # @param lightness [Sass::Script::Value::Number] The lightness of the color.
-    #   Must be between `0%` and `100%`, inclusive
-    # @param alpha [Sass::Script::Value::Number] The opacity of the color.
-    #   Must be between 0 and 1, inclusive
-    # @return [Sass::Script::Value::Color] The resulting color
+    # Creates a {Sass::Script::Value::Color Color} from hue, saturation,
+    # lightness, lightness, and alpha values. Uses the algorithm from the [CSS3
+    # spec][].
+    #
+    # [CSS3 spec]: http://www.w3.org/TR/css3-color/#hsl-color
+    #
     # @see #hsl
-    # @raise [ArgumentError] if `saturation`, `lightness`, or `alpha` are out of bounds
+    # @overload hsla($hue, $saturation, $lightness, $alpha)
+    # @param $hue [Sass::Script::Value::Number] The hue of the color. Should be
+    #   between 0 and 360 degrees, inclusive
+    # @param $saturation [Sass::Script::Value::Number] The saturation of the
+    #   color. Must be between `0%` and `100%`, inclusive
+    # @param $lightness [Sass::Script::Value::Number] The lightness of the
+    #   color. Must be between `0%` and `100%`, inclusive
+    # @param $alpha [Sass::Script::Value::Number] The opacity of the color. Must
+    #   be between 0 and 1, inclusive
+    # @return [Sass::Script::Value::Color]
+    # @raise [ArgumentError] if `$saturation`, `$lightness`, or `$alpha` are out
+    #   of bounds or any parameter is the wrong type
     def hsla(hue, saturation, lightness, alpha)
-      assert_type hue, :Number
-      assert_type saturation, :Number
-      assert_type lightness, :Number
-      assert_type alpha, :Number
+      assert_type hue, :Number, :hue
+      assert_type saturation, :Number, :saturation
+      assert_type lightness, :Number, :lightness
+      assert_type alpha, :Number, :alpha
 
       Sass::Util.check_range('Alpha channel', 0..1, alpha)
 
@@ -566,104 +583,118 @@ module Sass::Script
     end
     declare :hsla, [:hue, :saturation, :lightness, :alpha]
 
-    # Returns the red component of a color.
+    # Gets the red component of a color. Calculated from HSL where necessary via
+    # [this algorithm][hsl-to-rgb].
     #
-    # @param color [Sass::Script::Value::Color]
-    # @return [Sass::Script::Value::Number]
-    # @raise [ArgumentError] If `color` isn't a color
+    # [hsl-to-rgb]: http://www.w3.org/TR/css3-color/#hsl-color
+    #
+    # @overload red($color)
+    # @param $color [Sass::Script::Value::Color]
+    # @return [Sass::Script::Value::Number] The red component, between 0 and 255
+    #   inclusive
+    # @raise [ArgumentError] if `$color` isn't a color
     def red(color)
-      assert_type color, :Color
+      assert_type color, :Color, :color
       Sass::Script::Value::Number.new(color.red)
     end
     declare :red, [:color]
 
-    # Returns the green component of a color.
+    # Gets the green component of a color. Calculated from HSL where necessary
+    # via [this algorithm][hsl-to-rgb].
     #
-    # @param color [Sass::Script::Value::Color]
-    # @return [Sass::Script::Value::Number]
-    # @raise [ArgumentError] If `color` isn't a color
+    # [hsl-to-rgb]: http://www.w3.org/TR/css3-color/#hsl-color
+    #
+    # @overload green($color)
+    # @param $color [Sass::Script::Value::Color]
+    # @return [Sass::Script::Value::Number] The green component, between 0 and
+    #   255 inclusive
+    # @raise [ArgumentError] if `$color` isn't a color
     def green(color)
-      assert_type color, :Color
+      assert_type color, :Color, :color
       Sass::Script::Value::Number.new(color.green)
     end
     declare :green, [:color]
 
-    # Returns the blue component of a color.
+    # Gets the blue component of a color. Calculated from HSL where necessary
+    # via [this algorithm][hsl-to-rgb].
     #
-    # @param color [Sass::Script::Value::Color]
-    # @return [Sass::Script::Value::Number]
-    # @raise [ArgumentError] If `color` isn't a color
+    # [hsl-to-rgb]: http://www.w3.org/TR/css3-color/#hsl-color
+    #
+    # @overload blue($color)
+    # @param $color [Sass::Script::Value::Color]
+    # @return [Sass::Script::Value::Number] The blue component, between 0 and
+    #   255 inclusive
+    # @raise [ArgumentError] if `$color` isn't a color
     def blue(color)
-      assert_type color, :Color
+      assert_type color, :Color, :color
       Sass::Script::Value::Number.new(color.blue)
     end
     declare :blue, [:color]
 
-    # Returns the hue component of a color.
+    # Returns the hue component of a color. See [the CSS3 HSL
+    # specification][hsl]. Calculated from RGB where necessary via [this
+    # algorithm][rgb-to-hsl].
     #
-    # See [the CSS3 HSL specification](http://en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV).
+    # [hsl]: http://en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV
+    # [rgb-to-hsl]: http://en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV
     #
-    # Calculated from RGB where necessary via [this algorithm](http://en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV).
-    #
-    # @param color [Sass::Script::Value::Color]
-    # @return [Sass::Script::Value::Number] between 0deg and 360deg
-    # @see #adjust_hue
-    # @raise [ArgumentError] if `color` isn't a color
+    # @overload hue($color)
+    # @param $color [Sass::Script::Value::Color]
+    # @return [Sass::Script::Value::Number] The hue component, between 0deg and
+    #   360deg
+    # @raise [ArgumentError] if `$color` isn't a color
     def hue(color)
-      assert_type color, :Color
+      assert_type color, :Color, :color
       Sass::Script::Value::Number.new(color.hue, ["deg"])
     end
     declare :hue, [:color]
 
-    # Returns the saturation component of a color.
-    #
-    # See [the CSS3 HSL specification](http://en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV).
+    # Returns the saturation component of a color. See [the CSS3 HSL
+    # specification][hsl]. Calculated from RGB where necessary via [this
+    # algorithm][rgb-to-hsl].
     #
-    # Calculated from RGB where necessary via [this algorithm](http://en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV).
+    # [hsl]: http://en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV
+    # [rgb-to-hsl]: http://en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV
     #
-    # @param color [Sass::Script::Value::Color]
-    # @return [Sass::Script::Value::Number] between 0% and 100%
-    # @see #saturate
-    # @see #desaturate
-    # @raise [ArgumentError] if `color` isn't a color
+    # @overload saturation($color)
+    # @param $color [Sass::Script::Value::Color]
+    # @return [Sass::Script::Value::Number] The saturation component, between 0%
+    #   and 100%
+    # @raise [ArgumentError] if `$color` isn't a color
     def saturation(color)
-      assert_type color, :Color
+      assert_type color, :Color, :color
       Sass::Script::Value::Number.new(color.saturation, ["%"])
     end
     declare :saturation, [:color]
 
-    # Returns the hue component of a color.
-    #
-    # See [the CSS3 HSL specification](http://en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV).
+    # Returns the lightness component of a color. See [the CSS3 HSL
+    # specification][hsl]. Calculated from RGB where necessary via [this
+    # algorithm][rgb-to-hsl].
     #
-    # Calculated from RGB where necessary via [this algorithm](http://en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV).
+    # [hsl]: http://en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV
+    # [rgb-to-hsl]: http://en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV
     #
-    # @param color [Sass::Script::Value::Color]
-    # @return [Sass::Script::Value::Number] between 0% and 100%
-    # @see #lighten
-    # @see #darken
-    # @raise [ArgumentError] if `color` isn't a color
+    # @overload lightness($color)
+    # @param $color [Sass::Script::Value::Color]
+    # @return [Sass::Script::Value::Number] The lightness component, between 0%
+    #   and 100%
+    # @raise [ArgumentError] if `$color` isn't a color
     def lightness(color)
-      assert_type color, :Color
+      assert_type color, :Color, :color
       Sass::Script::Value::Number.new(color.lightness, ["%"])
     end
     declare :lightness, [:color]
 
-    # @overload alpha(color)
-    #   Returns the alpha component (opacity) of a color.
-    #   This is 1 unless otherwise specified.
-    #
-    #   @param color [Sass::Script::Value::Color]
-    #   @return [Sass::Script::Value::Number]
-    #   @see #opacify
-    #   @see #transparentize
-    #   @raise [ArgumentError] If `color` isn't a color
+    # Returns the alpha component (opacity) of a color. This is 1 unless
+    # otherwise specified.
     #
-    # @overload alpha(microsoft_string)
-    #   Support for the proprietary Microsoft `alpha(opacity=20)` syntax.
+    # This function also supports the proprietary Microsoft `alpha(opacity=20)`
+    # syntax as a special case.
     #
-    #   @param microsoft_string A special literal representing the
-    #     css-incompatible microsoft syntax
+    # @overload alpha($color)
+    # @param $color [Sass::Script::Value::Color]
+    # @return [Sass::Script::Value::Number] The alpha component, between 0 and 1
+    # @raise [ArgumentError] if `$color` isn't a color
     def alpha(*args)
       if args.all? do |a|
           a.is_a?(Sass::Script::Value::String) && a.type == :identifier &&
@@ -675,41 +706,41 @@ module Sass::Script
 
       raise ArgumentError.new("wrong number of arguments (#{args.size} for 1)") if args.size != 1
 
-      assert_type args.first, :Color
+      assert_type args.first, :Color, :color
       Sass::Script::Value::Number.new(args.first.alpha)
     end
     declare :alpha, [:color]
 
-    # Returns the alpha component (opacity) of a color.
-    # This is 1 unless otherwise specified.
+    # Returns the alpha component (opacity) of a color. This is 1 unless
+    # otherwise specified.
     #
-    # @param color [Sass::Script::Value::Color]
-    # @return [Sass::Script::Value::Number]
-    # @see #opacify
-    # @see #transparentize
-    # @raise [ArgumentError] If `color` isn't a color
+    # @overload opacity($color)
+    # @param $color [Sass::Script::Value::Color]
+    # @return [Sass::Script::Value::Number] The alpha component, between 0 and 1
+    # @raise [ArgumentError] if `$color` isn't a color
     def opacity(color)
       if color.is_a?(Sass::Script::Value::Number)
         return Sass::Script::Value::String.new("opacity(#{color})")
       end
-      assert_type color, :Color
+      assert_type color, :Color, :color
       Sass::Script::Value::Number.new(color.alpha)
     end
     declare :opacity, [:color]
 
-    # Makes a color more opaque.
-    # Takes a color and an amount between 0 and 1,
-    # and returns a color with the opacity increased by that value.
+    # Makes a color more opaque. Takes a color and a number between 0 and 1, and
+    # returns a color with the opacity increased by that amount.
     #
+    # @see #transparentize
     # @example
     #   opacify(rgba(0, 0, 0, 0.5), 0.1) => rgba(0, 0, 0, 0.6)
     #   opacify(rgba(0, 0, 17, 0.8), 0.2) => #001
-    # @param color [Sass::Script::Value::Color]
-    # @param amount [Sass::Script::Value::Number]
+    # @overload opacify($color, $amount)
+    # @param $color [Sass::Script::Value::Color]
+    # @param $amount [Sass::Script::Value::Number] The amount to increase the
+    #   opacity by, between 0 and 1
     # @return [Sass::Script::Value::Color]
-    # @see #transparentize
-    # @raise [ArgumentError] If `color` isn't a color,
-    #   or `number` isn't a number between 0 and 1
+    # @raise [ArgumentError] if `$amount` is out of bounds, or either parameter
+    #   is the wrong type
     def opacify(color, amount)
       _adjust(color, amount, :alpha, 0..1, :+)
     end
@@ -718,19 +749,20 @@ module Sass::Script
     alias_method :fade_in, :opacify
     declare :fade_in, [:color, :amount]
 
-    # Makes a color more transparent.
-    # Takes a color and an amount between 0 and 1,
-    # and returns a color with the opacity decreased by that value.
+    # Makes a color more transparent. Takes a color and a number between 0 and
+    # 1, and returns a color with the opacity decreased by that amount.
     #
+    # @see #opacify
     # @example
     #   transparentize(rgba(0, 0, 0, 0.5), 0.1) => rgba(0, 0, 0, 0.4)
     #   transparentize(rgba(0, 0, 0, 0.8), 0.2) => rgba(0, 0, 0, 0.6)
-    # @param color [Sass::Script::Value::Color]
-    # @param amount [Sass::Script::Value::Number]
+    # @overload transparentize($color, $amount)
+    # @param $color [Sass::Script::Value::Color]
+    # @param $amount [Sass::Script::Value::Number] The amount to decrease the
+    #   opacity by, between 0 and 1
     # @return [Sass::Script::Value::Color]
-    # @see #opacify
-    # @raise [ArgumentError] If `color` isn't a color,
-    #   or `number` isn't a number between 0 and 1
+    # @raise [ArgumentError] if `$amount` is out of bounds, or either parameter
+    #   is the wrong type
     def transparentize(color, amount)
       _adjust(color, amount, :alpha, 0..1, :-)
     end
@@ -739,56 +771,58 @@ module Sass::Script
     alias_method :fade_out, :transparentize
     declare :fade_out, [:color, :amount]
 
-    # Makes a color lighter.
-    # Takes a color and an amount between 0% and 100%,
-    # and returns a color with the lightness increased by that value.
+    # Makes a color lighter. Takes a color and a number between `0%` and `100%`,
+    # and returns a color with the lightness increased by that amount.
     #
+    # @see #darken
     # @example
     #   lighten(hsl(0, 0%, 0%), 30%) => hsl(0, 0, 30)
     #   lighten(#800, 20%) => #e00
-    # @param color [Sass::Script::Value::Color]
-    # @param amount [Sass::Script::Value::Number]
+    # @overload lighten($color, $amount)
+    # @param $color [Sass::Script::Value::Color]
+    # @param $amount [Sass::Script::Value::Number] The amount to increase the
+    #   lightness by, between `0%` and `100%`
     # @return [Sass::Script::Value::Color]
-    # @see #darken
-    # @raise [ArgumentError] If `color` isn't a color,
-    #   or `number` isn't a number between 0% and 100%
+    # @raise [ArgumentError] if `$amount` is out of bounds, or either parameter
+    #   is the wrong type
     def lighten(color, amount)
       _adjust(color, amount, :lightness, 0..100, :+, "%")
     end
     declare :lighten, [:color, :amount]
 
-    # Makes a color darker.
-    # Takes a color and an amount between 0% and 100%,
-    # and returns a color with the lightness decreased by that value.
+    # Makes a color darker. Takes a color and a number between 0% and 100%, and
+    # returns a color with the lightness decreased by that amount.
     #
+    # @see #lighten
     # @example
     #   darken(hsl(25, 100%, 80%), 30%) => hsl(25, 100%, 50%)
     #   darken(#800, 20%) => #200
-    # @param color [Sass::Script::Value::Color]
-    # @param amount [Sass::Script::Value::Number]
+    # @overload darken($color, $amount)
+    # @param $color [Sass::Script::Value::Color]
+    # @param $amount [Sass::Script::Value::Number] The amount to dencrease the
+    #   lightness by, between `0%` and `100%`
     # @return [Sass::Script::Value::Color]
-    # @see #lighten
-    # @raise [ArgumentError] If `color` isn't a color,
-    #   or `number` isn't a number between 0% and 100%
+    # @raise [ArgumentError] if `$amount` is out of bounds, or either parameter
+    #   is the wrong type
     def darken(color, amount)
       _adjust(color, amount, :lightness, 0..100, :-, "%")
     end
     declare :darken, [:color, :amount]
 
-    # Makes a color more saturated.
-    # Takes a color and an amount between 0% and 100%,
-    # and returns a color with the saturation increased by that value.
+    # Makes a color more saturated. Takes a color and a number between 0% and
+    # 100%, and returns a color with the saturation increased by that amount.
     #
+    # @see #desaturate
     # @example
     #   saturate(hsl(120, 30%, 90%), 20%) => hsl(120, 50%, 90%)
     #   saturate(#855, 20%) => #9e3f3f
-    # @overload saturate(color, amount)
-    #   @param color [Sass::Script::Value::Color]
-    #   @param amount [Sass::Script::Value::Number]
-    #   @return [Sass::Script::Value::Color]
-    #   @see #desaturate
-    #   @raise [ArgumentError] If `color` isn't a color,
-    #     or `number` isn't a number between 0% and 100%
+    # @overload saturate($color, $amount)
+    # @param $color [Sass::Script::Value::Color]
+    # @param $amount [Sass::Script::Value::Number] The amount to increase the
+    #   saturation by, between `0%` and `100%`
+    # @return [Sass::Script::Value::Color]
+    # @raise [ArgumentError] if `$amount` is out of bounds, or either parameter
+    #   is the wrong type
     def saturate(color, amount = nil)
       # Support the filter effects definition of saturate.
       # https://dvcs.w3.org/hg/FXTF/raw-file/tip/filters/index.html
@@ -798,93 +832,99 @@ module Sass::Script
     declare :saturate, [:color, :amount]
     declare :saturate, [:amount]
 
-    # Makes a color less saturated.
-    # Takes a color and an amount between 0% and 100%,
-    # and returns a color with the saturation decreased by that value.
+    # Makes a color less saturated. Takes a color and a number between 0% and
+    # 100%, and returns a color with the saturation decreased by that value.
     #
+    # @see #saturate
     # @example
     #   desaturate(hsl(120, 30%, 90%), 20%) => hsl(120, 10%, 90%)
     #   desaturate(#855, 20%) => #726b6b
-    # @param color [Sass::Script::Value::Color]
-    # @param amount [Sass::Script::Value::Number]
+    # @overload desaturate($color, $amount)
+    # @param $color [Sass::Script::Value::Color]
+    # @param $amount [Sass::Script::Value::Number] The amount to decrease the
+    #   saturation by, between `0%` and `100%`
     # @return [Sass::Script::Value::Color]
-    # @see #saturate
-    # @raise [ArgumentError] If `color` isn't a color,
-    #   or `number` isn't a number between 0% and 100%
+    # @raise [ArgumentError] if `$amount` is out of bounds, or either parameter
+    #   is the wrong type
     def desaturate(color, amount)
       _adjust(color, amount, :saturation, 0..100, :-, "%")
     end
     declare :desaturate, [:color, :amount]
 
-    # Changes the hue of a color while retaining the lightness and saturation.
-    # Takes a color and a number of degrees (usually between -360deg and 360deg),
-    # and returns a color with the hue rotated by that value.
+    # Changes the hue of a color. Takes a color and a number of degrees (usually
+    # between `-360deg` and `360deg`), and returns a color with the hue rotated
+    # along the color wheel by that amount.
     #
     # @example
     #   adjust-hue(hsl(120, 30%, 90%), 60deg) => hsl(180, 30%, 90%)
     #   adjust-hue(hsl(120, 30%, 90%), 060deg) => hsl(60, 30%, 90%)
     #   adjust-hue(#811, 45deg) => #886a11
-    # @param color [Sass::Script::Value::Color] The color to adjust.
-    # @param degrees [Sass::Script::Value::Number] The number of degrees to shift the hue.
-    # @return [Sass::Script::Value::Color] The transformed color.
-    # @raise [ArgumentError] If `color` isn't a color, or `degrees` isn't a number
+    # @overload adjust_hue($color, $degrees)
+    # @param $color [Sass::Script::Value::Color]
+    # @param $degrees [Sass::Script::Value::Number] The number of degrees to
+    #   rotate the hue
+    # @return [Sass::Script::Value::Color]
+    # @raise [ArgumentError] if either parameter is the wrong type
     def adjust_hue(color, degrees)
-      assert_type color, :Color
-      assert_type degrees, :Number
+      assert_type color, :Color, :color
+      assert_type degrees, :Number, :degrees
       color.with(:hue => color.hue + degrees.value)
     end
     declare :adjust_hue, [:color, :degrees]
 
-    # Returns an IE hex string for a color with an alpha channel
-    # suitable for passing to IE filters.
+    # Converts a color into the format understood by IE filters.
     #
     # @example
     #   ie-hex-str(#abc) => #FFAABBCC
     #   ie-hex-str(#3322BB) => #FF3322BB
     #   ie-hex-str(rgba(0, 255, 0, 0.5)) => #8000FF00
-    # @param color [Sass::Script::Value::Color]
-    # @return [Sass::Script::Value::String]
-    # @raise [ArgumentError] If `color` isn't a color
+    # @overload ie_hex_str($color)
+    # @param $color [Sass::Script::Value::Color]
+    # @return [Sass::Script::Value::String] The IE-formatted string
+    #   representation of the color
+    # @raise [ArgumentError] if `$color` isn't a color
     def ie_hex_str(color)
-      assert_type color, :Color
+      assert_type color, :Color, :color
       alpha = (color.alpha * 255).round.to_s(16).rjust(2, '0')
       Sass::Script::Value::String.new("##{alpha}#{color.send(:hex_str)[1..-1]}".upcase)
     end
     declare :ie_hex_str, [:color]
 
-    # Adjusts one or more properties of a color.
-    # This can change the red, green, blue, hue, saturation, value, and alpha properties.
-    # The properties are specified as keyword arguments,
-    # and are added to or subtracted from the color's current value for that property.
-    #
-    # `$red`, `$green`, and `$blue` properties should be between 0 and 255.
-    # `$saturation` and `$lightness` should be between 0% and 100%.
-    # `$alpha` should be between 0 and 1.
+    # Increases or decreases one or more properties of a color. This can change
+    # the red, green, blue, hue, saturation, value, and alpha properties. The
+    # properties are specified as keyword arguments, and are added to or
+    # subtracted from the color's current value for that property.
     #
-    # All properties are optional.
-    # You can't specify both RGB properties (`$red`, `$green`, `$blue`)
-    # and HSL properties (`$hue`, `$saturation`, `$value`) at the same time.
+    # All properties are optional. You can't specify both RGB properties
+    # (`$red`, `$green`, `$blue`) and HSL properties (`$hue`, `$saturation`,
+    # `$value`) at the same time.
     #
     # @example
     #   adjust-color(#102030, $blue: 5) => #102035
     #   adjust-color(#102030, $red: -5, $blue: 5) => #0b2035
     #   adjust-color(hsl(25, 100%, 80%), $lightness: -30%, $alpha: -0.4) => hsla(25, 100%, 50%, 0.6)
-    # @param color [Sass::Script::Value::Color]
-    # @option kwargs [Sass::Script::Value::Number] "red" The amount by which the red component should change.
-    # @option kwargs [Sass::Script::Value::Number] "green" The amount by which the green component should change.
-    # @option kwargs [Sass::Script::Value::Number] "blue" The amount by which the blue component should change.
-    # @option kwargs [Sass::Script::Value::Number] "hue" The number of degrees by which the hue should change.
-    # @option kwargs [Sass::Script::Value::Number] "saturation" The amount by which the saturation should change.
-    # @option kwargs [Sass::Script::Value::Number] "lightness" The amount by which the lightness should change.
-    # @option kwargs [Sass::Script::Value::Number] "alpha" The amount by which the alpha channel should change.
+    # @overload adjust_color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha])
+    # @param $color [Sass::Script::Value::Color]
+    # @param $red [Sass::Script::Value::Number] The adjustment to make on the
+    #   red component, between -255 and 255 inclusive
+    # @param $green [Sass::Script::Value::Number] The adjustment to make on the
+    #   green component, between -255 and 255 inclusive
+    # @param $blue [Sass::Script::Value::Number] The adjustment to make on the
+    #   blue component, between -255 and 255 inclusive
+    # @param $hue [Sass::Script::Value::Number] The adjustment to make on the
+    #   hue component, in degrees
+    # @param $saturation [Sass::Script::Value::Number] The adjustment to make on
+    #   the saturation component, between `-100%` and `100%` inclusive
+    # @param $lightness [Sass::Script::Value::Number] The adjustment to make on
+    #   the lightness component, between `-100%` and `100%` inclusive
+    # @param $alpha [Sass::Script::Value::Number] The adjustment to make on the
+    #   alpha component, between -1 and 1 inclusive
     # @return [Sass::Script::Value::Color]
-    # @raise [ArgumentError] if `color` is not a color,
-    #   if any keyword argument is not a number,
-    #   if any keyword argument is not in the legal range,
-    #   if an unexpected keyword argument is given,
-    #   or if both HSL and RGB properties are given.
+    # @raise [ArgumentError] if any parameter is the wrong type or out-of
+    #   bounds, or if RGB properties and HSL properties are adjusted at the
+    #   same time
     def adjust_color(color, kwargs)
-      assert_type color, :Color
+      assert_type color, :Color, :color
       with = Sass::Util.map_hash({
           "red" => [-255..255, ""],
           "green" => [-255..255, ""],
@@ -912,47 +952,47 @@ module Sass::Script
     end
     declare :adjust_color, [:color], :var_kwargs => true
 
-    # Scales one or more properties of a color by a percentage value.
-    # Unlike \{#adjust_color adjust-color}, which changes a color's properties by fixed amounts,
-    # \{#scale_color scale-color} fluidly changes them based on how high or low they already are.
-    # That means that lightening an already-light color with \{#scale_color scale-color}
-    # won't change the lightness much,
-    # but lightening a dark color by the same amount will change it more dramatically.
-    # This has the benefit of making `scale-color($color, ...)` have a similar effect
-    # regardless of what `$color` is.
-    #
-    # For example, the lightness of a color can be anywhere between 0 and 100.
-    # If `scale-color($color, $lightness: 40%)` is called, the resulting color's lightness
-    # will be 40% of the way between its original lightness and 100.
-    # If `scale-color($color, $lightness: -40%)` is called instead,
-    # the lightness will be 40% of the way between the original and 0.
-    #
-    # This can change the red, green, blue, saturation, value, and alpha properties.
-    # The properties are specified as keyword arguments.
-    # All arguments should be percentages between 0% and 100%.
-    #
-    # All properties are optional.
-    # You can't specify both RGB properties (`$red`, `$green`, `$blue`)
-    # and HSL properties (`$saturation`, `$value`) at the same time.
+    # Fluidly scales one or more properties of a color. Unlike
+    # \{#adjust_color adjust-color}, which changes a color's properties by fixed
+    # amounts, \{#scale_color scale-color} fluidly changes them based on how
+    # high or low they already are. That means that lightening an already-light
+    # color with \{#scale_color scale-color} won't change the lightness much,
+    # but lightening a dark color by the same amount will change it more
+    # dramatically. This has the benefit of making `scale-color($color, ...)`
+    # have a similar effect regardless of what `$color` is.
+    #
+    # For example, the lightness of a color can be anywhere between `0%` and
+    # `100%`. If `scale-color($color, $lightness: 40%)` is called, the resulting
+    # color's lightness will be 40% of the way between its original lightness
+    # and 100. If `scale-color($color, $lightness: -40%)` is called instead, the
+    # lightness will be 40% of the way between the original and 0.
+    #
+    # This can change the red, green, blue, saturation, value, and alpha
+    # properties. The properties are specified as keyword arguments. All
+    # arguments should be percentages between `0%` and `100%`.
+    #
+    # All properties are optional. You can't specify both RGB properties
+    # (`$red`, `$green`, `$blue`) and HSL properties (`$saturation`, `$value`)
+    # at the same time.
     #
     # @example
-    #   scale-color(hsl(120, 70, 80), $lightness: 50%) => hsl(120, 70, 90)
-    #   scale-color(rgb(200, 150, 170), $green: -40%, $blue: 70%) => rgb(200, 90, 229)
-    #   scale-color(hsl(200, 70, 80), $saturation: -90%, $alpha: -30%) => hsla(200, 7, 80, 0.7)
-    # @param color [Sass::Script::Value::Color]
-    # @option kwargs [Sass::Script::Value::Number] "red" The amount by which the red component should scale.
-    # @option kwargs [Sass::Script::Value::Number] "green" The amount by which the green component should scale.
-    # @option kwargs [Sass::Script::Value::Number] "blue" The amount by which the blue component should scale.
-    # @option kwargs [Sass::Script::Value::Number] "saturation" The amount by which the saturation should scale.
-    # @option kwargs [Sass::Script::Value::Number] "lightness" The amount by which the lightness should scale.
-    # @option kwargs [Sass::Script::Value::Number] "alpha" The amount by which the alpha channel should scale.
+    #   scale-color(hsl(120, 70%, 80%), $lightness: 50%) => hsl(120, 70%, 90%)
+    #   scale-color(rgb(200, 150%, 170%), $green: -40%, $blue: 70%) => rgb(200, 90, 229)
+    #   scale-color(hsl(200, 70%, 80%), $saturation: -90%, $alpha: -30%) => hsla(200, 7%, 80%, 0.7)
+    # @overload scale_color($color, [$red], [$green], [$blue], [$saturation], [$lightness], [$alpha])
+    # @param $color [Sass::Script::Value::Color]
+    # @param $red [Sass::Script::Value::Number]
+    # @param $green [Sass::Script::Value::Number]
+    # @param $blue [Sass::Script::Value::Number]
+    # @param $saturation [Sass::Script::Value::Number]
+    # @param $lightness [Sass::Script::Value::Number]
+    # @param $alpha [Sass::Script::Value::Number]
     # @return [Sass::Script::Value::Color]
-    # @raise [ArgumentError] if `color` is not a color,
-    #   if any keyword argument is not a percentage between 0% and 100%,
-    #   if an unexpected keyword argument is given,
-    #   or if both HSL and RGB properties are given.
+    # @raise [ArgumentError] if any parameter is the wrong type or out-of
+    #   bounds, or if RGB properties and HSL properties are adjusted at the
+    #   same time
     def scale_color(color, kwargs)
-      assert_type color, :Color
+      assert_type color, :Color, :color
       with = Sass::Util.map_hash({
           "red" => 255,
           "green" => 255,
@@ -982,39 +1022,41 @@ module Sass::Script
     end
     declare :scale_color, [:color], :var_kwargs => true
 
-    # Changes one or more properties of a color.
-    # This can change the red, green, blue, hue, saturation, value, and alpha properties.
-    # The properties are specified as keyword arguments,
-    # and replace the color's current value for that property.
-    #
-    # `$red`, `$green`, and `$blue` properties should be between 0 and 255.
-    # `$saturation` and `$lightness` should be between 0% and 100%.
-    # `$alpha` should be between 0 and 1.
+    # Changes one or more properties of a color. This can change the red, green,
+    # blue, hue, saturation, value, and alpha properties. The properties are
+    # specified as keyword arguments, and replace the color's current value for
+    # that property.
     #
-    # All properties are optional.
-    # You can't specify both RGB properties (`$red`, `$green`, `$blue`)
-    # and HSL properties (`$hue`, `$saturation`, `$value`) at the same time.
+    # All properties are optional. You can't specify both RGB properties
+    # (`$red`, `$green`, `$blue`) and HSL properties (`$hue`, `$saturation`,
+    # `$value`) at the same time.
     #
     # @example
     #   change-color(#102030, $blue: 5) => #102005
     #   change-color(#102030, $red: 120, $blue: 5) => #782005
     #   change-color(hsl(25, 100%, 80%), $lightness: 40%, $alpha: 0.8) => hsla(25, 100%, 40%, 0.8)
-    # @param color [Sass::Script::Value::Color]
-    # @option kwargs [Sass::Script::Value::Number] "red" The amount by which the red component should change.
-    # @option kwargs [Sass::Script::Value::Number] "green" The amount by which the green component should change.
-    # @option kwargs [Sass::Script::Value::Number] "blue" The amount by which the blue component should change.
-    # @option kwargs [Sass::Script::Value::Number] "hue" The number of degrees by which the hue should change.
-    # @option kwargs [Sass::Script::Value::Number] "saturation" The amount by which the saturation should change.
-    # @option kwargs [Sass::Script::Value::Number] "lightness" The amount by which the lightness should change.
-    # @option kwargs [Sass::Script::Value::Number] "alpha" The amount by which the alpha channel should change.
+    # @overload change_color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha])
+    # @param $color [Sass::Script::Value::Color]
+    # @param $red [Sass::Script::Value::Number] The new red component for the
+    #   color, within 0 and 255 inclusive
+    # @param $green [Sass::Script::Value::Number] The new green component for
+    #   the color, within 0 and 255 inclusive
+    # @param $blue [Sass::Script::Value::Number] The new blue component for the
+    #   color, within 0 and 255 inclusive
+    # @param $hue [Sass::Script::Value::Number] The new hue component for the
+    #   color, in degrees
+    # @param $saturation [Sass::Script::Value::Number] The new saturation
+    #   component for the color, between `0%` and `100%` inclusive
+    # @param $lightness [Sass::Script::Value::Number] The new lightness
+    #   component for the color, within `0%` and `100%` inclusive
+    # @param $alpha [Sass::Script::Value::Number] The new alpha component for
+    #   the color, within 0 and 1 inclusive
     # @return [Sass::Script::Value::Color]
-    # @raise [ArgumentError] if `color` is not a color,
-    #   if any keyword argument is not a number,
-    #   if any keyword argument is not in the legal range,
-    #   if an unexpected keyword argument is given,
-    #   or if both HSL and RGB properties are given.
+    # @raise [ArgumentError] if any parameter is the wrong type or out-of
+    #   bounds, or if RGB properties and HSL properties are adjusted at the
+    #   same time
     def change_color(color, kwargs)
-      assert_type color, :Color
+      assert_type color, :Color, :color
       with = Sass::Util.map_hash(%w[red green blue hue saturation lightness alpha]) do |name, max|
         next unless val = kwargs.delete(name)
         assert_type val, :Number, name
@@ -1030,33 +1072,32 @@ module Sass::Script
     end
     declare :change_color, [:color], :var_kwargs => true
 
-    # Mixes together two colors.
-    # Specifically, takes the average of each of the RGB components,
-    # optionally weighted by the given percentage.
-    # The opacity of the colors is also considered when weighting the components.
+    # Mixes two colors together. Specifically, takes the average of each of the
+    # RGB components, optionally weighted by the given percentage. The opacity
+    # of the colors is also considered when weighting the components.
     #
     # The weight specifies the amount of the first color that should be included
-    # in the returned color.
-    # The default, 50%, means that half the first color
-    # and half the second color should be used.
-    # 25% means that a quarter of the first color
-    # and three quarters of the second color should be used.
+    # in the returned color. The default, `50%`, means that half the first color
+    # and half the second color should be used. `25%` means that a quarter of
+    # the first color and three quarters of the second color should be used.
     #
     # @example
     #   mix(#f00, #00f) => #7f007f
     #   mix(#f00, #00f, 25%) => #3f00bf
     #   mix(rgba(255, 0, 0, 0.5), #00f) => rgba(63, 0, 191, 0.75)
-    # @overload mix(color1, color2, weight: 50%)
-    #   @param color1 [Sass::Script::Value::Color]
-    #   @param color2 [Sass::Script::Value::Color]
-    #   @param weight [Sass::Script::Value::Number] between 0% and 100%
-    #   @return [Sass::Script::Value::Color]
-    #   @raise [ArgumentError] if `color1` or `color2` aren't colors,
-    #     or `weight` isn't a number between 0% and 100%
-    def mix(color1, color2, weight = Sass::Script::Value::Number.new(50))
-      assert_type color1, :Color
-      assert_type color2, :Color
-      assert_type weight, :Number
+    # @overload mix($color-1, $color-2, $weight: 50%)
+    # @param $color-1 [Sass::Script::Value::Color]
+    # @param $color-2 [Sass::Script::Value::Color]
+    # @param $weight [Sass::Script::Value::Number] The relative weight of each
+    #   color. Closer to `0%` gives more weight to `$color`, closer to `100%`
+    #   gives more weight to `$color2`
+    # @return [Sass::Script::Value::Color]
+    # @raise [ArgumentError] if `$weight` is out of bounds or any parameter is
+    #   the wrong type
+    def mix(color_1, color_2, weight = Sass::Script::Value::Number.new(50))
+      assert_type color_1, :Color, :color_1
+      assert_type color_2, :Color, :color_2
+      assert_type weight, :Number, :weight
 
       Sass::Util.check_range("Weight", 0..100, weight, '%')
 
@@ -1065,11 +1106,11 @@ module Sass::Script
       # to perform the weighted average of the two RGB values.
       #
       # It works by first normalizing both parameters to be within [-1, 1],
-      # where 1 indicates "only use color1", -1 indicates "only use color2", and
+      # where 1 indicates "only use color_1", -1 indicates "only use color_2", and
       # all values in between indicated a proportionately weighted average.
       #
       # Once we have the normalized variables w and a, we apply the formula
-      # (w + a)/(1 + w*a) to get the combined weight (in [-1, 1]) of color1.
+      # (w + a)/(1 + w*a) to get the combined weight (in [-1, 1]) of color_1.
       # This formula has two especially nice properties:
       #
       #   * When either w or a are -1 or 1, the combined weight is also that number
@@ -1077,29 +1118,30 @@ module Sass::Script
       #
       #   * When a is 0, the combined weight is w, and vice versa.
       #
-      # Finally, the weight of color1 is renormalized to be within [0, 1]
-      # and the weight of color2 is given by 1 minus the weight of color1.
+      # Finally, the weight of color_1 is renormalized to be within [0, 1]
+      # and the weight of color_2 is given by 1 minus the weight of color_1.
       p = (weight.value/100.0).to_f
       w = p*2 - 1
-      a = color1.alpha - color2.alpha
+      a = color_1.alpha - color_2.alpha
 
       w1 = (((w * a == -1) ? w : (w + a)/(1 + w*a)) + 1)/2.0
       w2 = 1 - w1
 
-      rgb = color1.rgb.zip(color2.rgb).map {|v1, v2| v1*w1 + v2*w2}
-      alpha = color1.alpha*p + color2.alpha*(1-p)
+      rgb = color_1.rgb.zip(color_2.rgb).map {|v1, v2| v1*w1 + v2*w2}
+      alpha = color_1.alpha*p + color_2.alpha*(1-p)
       Sass::Script::Value::Color.new(rgb + [alpha])
     end
     declare :mix, [:color_1, :color_2]
     declare :mix, [:color_1, :color_2, :weight]
 
-    # Converts a color to grayscale.
-    # This is identical to `desaturate(color, 100%)`.
+    # Converts a color to grayscale. This is identical to `desaturate(color,
+    # 100%)`.
     #
-    # @param color [Sass::Script::Value::Color]
-    # @return [Sass::Script::Value::Color]
-    # @raise [ArgumentError] if `color` isn't a color
     # @see #desaturate
+    # @overload grayscale($color)
+    # @param $color [Sass::Script::Value::Color]
+    # @return [Sass::Script::Value::Color]
+    # @raise [ArgumentError] if `$color` isn't a color
     def grayscale(color)
       if color.is_a?(Sass::Script::Value::Number)
         return Sass::Script::Value::String.new("grayscale(#{color})")
@@ -1108,30 +1150,32 @@ module Sass::Script
     end
     declare :grayscale, [:color]
 
-    # Returns the complement of a color.
-    # This is identical to `adjust-hue(color, 180deg)`.
+    # Returns the complement of a color. This is identical to `adjust-hue(color,
+    # 180deg)`.
     #
-    # @param color [Sass::Script::Value::Color]
-    # @return [Sass::Script::Value::Color]
-    # @raise [ArgumentError] if `color` isn't a color
     # @see #adjust_hue #adjust-hue
+    # @overload complement($color)
+    # @param $color [Sass::Script::Value::Color]
+    # @return [Sass::Script::Value::Color]
+    # @raise [ArgumentError] if `$color` isn't a color
     def complement(color)
       adjust_hue color, Sass::Script::Value::Number.new(180)
     end
     declare :complement, [:color]
 
-    # Returns the inverse (negative) of a color.
-    # The red, green, and blue values are inverted, while the opacity is left alone.
+    # Returns the inverse (negative) of a color. The red, green, and blue values
+    # are inverted, while the opacity is left alone.
     #
-    # @param color [Sass::Script::Value::Color]
+    # @overload invert($color)
+    # @param $color [Sass::Script::Value::Color]
     # @return [Sass::Script::Value::Color]
-    # @raise [ArgumentError] if `color` isn't a color
+    # @raise [ArgumentError] if `$color` isn't a color
     def invert(color)
       if color.is_a?(Sass::Script::Value::Number)
         return Sass::Script::Value::String.new("invert(#{color})")
       end
 
-      assert_type color, :Color
+      assert_type color, :Color, :color
       color.with(
         :red => (255 - color.red),
         :green => (255 - color.green),
@@ -1139,16 +1183,17 @@ module Sass::Script
     end
     declare :invert, [:color]
 
-    # Removes quotes from a string if the string is quoted,
-    # or returns the same string if it's not.
+    # Removes quotes from a string. If the string is already unquoted, this will
+    # return it unmodified.
     #
-    # @param string [Sass::Script::Value::String]
-    # @return [Sass::Script::Value::String]
-    # @raise [ArgumentError] if `string` isn't a string
     # @see #quote
     # @example
     #   unquote("foo") => foo
     #   unquote(foo) => foo
+    # @overload unquote($string)
+    # @param $string [Sass::Script::Value::String]
+    # @return [Sass::Script::Value::String]
+    # @raise [ArgumentError] if `$string` isn't a string
     def unquote(string)
       if string.is_a?(Sass::Script::Value::String)
         Sass::Script::Value::String.new(string.value, :identifier)
@@ -1161,113 +1206,117 @@ module Sass::Script
     # Add quotes to a string if the string isn't quoted,
     # or returns the same string if it is.
     #
-    # @param string [Sass::Script::Value::String]
-    # @return [Sass::Script::Value::String]
-    # @raise [ArgumentError] if `string` isn't a string
     # @see #unquote
     # @example
     #   quote("foo") => "foo"
     #   quote(foo) => "foo"
+    # @overload quote($string)
+    # @param $string [Sass::Script::Value::String]
+    # @return [Sass::Script::Value::String]
+    # @raise [ArgumentError] if `$string` isn't a string
     def quote(string)
-      assert_type string, :String
+      assert_type string, :String, :string
       Sass::Script::Value::String.new(string.value, :string)
     end
     declare :quote, [:string]
 
     # Returns the number of characters in a string.
     #
-    # @return [Sass::Script::Value::Number]
-    # @raise [ArgumentError] if `string` isn't a string
     # @example
     #   str-length("foo") => 3
+    # @overload str_length($string)
+    # @param $string [Sass::Script::Value::String]
+    # @return [Sass::Script::Value::Number]
+    # @raise [ArgumentError] if `$string` isn't a string
     def str_length(string)
-      assert_type string, :String
+      assert_type string, :String, :string
       Sass::Script::Value::Number.new(string.value.size)
     end
     declare :str_length, [:string]
 
-    # Inserts a string into another string.
+    # Inserts `$insert` into `$string` at `$index`.
     #
-    # Inserts the `$insert` string into the `$original` before the character at
-    # the given `$index`.
+    # Note that unlike some languages, the first character in a Sass string is
+    # number 1, the second number 2, and so forth.
     #
-    # @param original [Sass::Script::Value::String]
-    #   The string that will receive the insertion.
-    # @param insert [Sass::Script::Value::String]
-    #   The string that will be inserted.
-    # @param index [Sass::Script::Value::Number]
-    #   The position where inserted string will start.
-    #   Negative indices count from the end of the original string.
-    #
-    # @return [Sass::Script::Value::String] A new string
-    # @raise [ArgumentError] if `$original` isn't a string, `$insert` isn't a string, or `$index` isn't a number.
     # @example
     #   str-insert("abcd", "X", 1) => "Xabcd"
     #   str-insert("abcd", "X", 4) => "abcXd"
-    #   str-insert("abcd", "X", 100) => "abcdX"
-    #   str-insert("abcd", "X", -100) => "Xabcd"
+    #   str-insert("abcd", "X", 5) => "abcXd"
+    #
+    # @overload str_insert($string, $insert, $index)
+    # @param $string [Sass::Script::Value::String]
+    # @param $insert [Sass::Script::Value::String]
+    # @param $index [Sass::Script::Value::Number] The position at which
+    #   `$insert` will be inserted. Negative indices count from the end of
+    #   `$string`. An index that's outside the bounds of the string will insert
+    #   `$insert` at the front or back of the string
+    # @return [Sass::Script::Value::String] The result string. This will be
+    #   quoted if and only if `$string` was quoted
+    # @raise [ArgumentError] if any parameter is the wrong type
     def str_insert(original, insert, index)
-      assert_type original, :String, "original"
-      assert_type insert, :String, "insert"
-      assert_integer index, "index"
-      assert_unit index, nil, "index"
+      assert_type original, :String, :string
+      assert_type insert, :String, :insert
+      assert_integer index, :index
+      assert_unit index, nil, :index
       insertion_point = index.value > 0 ? [index.value - 1, original.value.size].min : [index.value, -original.value.size - 1].max
       Sass::Script::Value::String.new(original.value.dup.insert(insertion_point, insert.value), original.type)
     end
-    declare :str_insert, [:original, :insert, :index]
+    declare :str_insert, [:string, :insert, :index]
 
-    # Starting at the left, finds the index of the first location
-    # where `substring` is found in `string`.
+    # Returns the index of the first occurance of `$substring` in `$string`. If
+    # there is no such occurance, returns 0.
+    #
+    # Note that unlike some languages, the first character in a Sass string is
+    # number 1, the second number 2, and so forth.
     #
-    # @return [Sass::Script::Value::Number] The index of the substring, or 0 if not found.
-    # @raise [ArgumentError] if `original` isn't a string, `insert` isn't a string, or `index` isn't a number.
-    # @param string The string to search
-    # @param substring The string to search for
     # @example
     #   str-index(abcd, a)  => 1
     #   str-index(abcd, ab) => 1
     #   str-index(abcd, X)  => 0
     #   str-index(abcd, c)  => 3
+    #
+    # @overload str_index($string, $substring)
+    # @param $string [Sass::Script::Value::String]
+    # @param $substring [Sass::Script::Value::String]
+    # @return [Sass::Script::Value::Number]
+    # @raise [ArgumentError] if any parameter is the wrong type
     def str_index(string, substring)
-      assert_type string, :String
-      assert_type substring, :String
+      assert_type string, :String, :string
+      assert_type substring, :String, :substring
       index = string.value.index(substring.value) || -1
       Sass::Script::Value::Number.new(index + 1)
     end
     declare :str_index, [:string, :substring]
 
 
-    # Slice a substring from `string` from `start-at` index to `end-at` index.
+    # Extracts a substring from `$string`. The substring will begin at index
+    # `$start-at` and ends at index `$end-at`.
+    #
+    # Note that unlike some languages, the first character in a Sass string is
+    # number 1, the second number 2, and so forth.
     #
-    # @return [Sass::Script::Value::String] A new string
-    # @param start_at
-    #   The index (inclusive) of the first character to slice out of the string.
-    #   If negative, counts from the end of the string.
-    # @param end_at
-    #   The index (inclusive) of the last character to slice out of the string.
-    # @overload str_slice(string, start_at)
-    #   Slice starting at `start_at` to the end of the string.
-    # @overload str_slice(string, start_at, end_at)
-    #   Slice starting at `start_at` to `end_at`
-    # @raise [ArgumentError] if `string` isn't a string or `start_at` and `end_at` aren't unitless numbers
     # @example
-    #  str-slice(abcd,    2,   3) => bc
-    #  str-slice(abcd,    2     ) => bcd
-    #  str-slice(abcd,   -2     ) => cd
-    #  str-slice(abcd,    2,  -2) => bc
-    #  str-slice("abcd",  3,  -3) => ""
-    #  str-slice(abcd,    1,   1) => a
-    #  str-slice(abcd,    1,   2) => ab
-    #  str-slice(abcd,    1,   4) => abcd
-    #  str-slice(abcd, -100,   4) => abcd
-    #  str-slice(abcd,    1, 100) => abcd
-    #  str-slice("abcd",  2,   1) => ""
-    #  str-slice("abcd",  2,   3) => "bc"
+    #  str-slice("abcd", 2, 3)   => "bc"
+    #  str-slice("abcd", 2)      => "bcd"
+    #  str-slice("abcd", -3, -2) => "bc"
+    #  str-slice("abcd", 2, -2)  => "bc"
+    #
+    # @overload str_slice($string, $start-at, $end-at: -1)
+    # @param $start-at [Sass::Script::Value::Number] The index of the first
+    #   character of the substring. If this is negative, it counts from the end
+    #   of `$string`
+    # @param $end-before [Sass::Script::Value::Number] The index of the last
+    #   character of the substring. If this is negative, it counts from the end
+    #   of `$string`. Defaults to -1
+    # @return [Sass::Script::Value::String] The substring. This will be quoted
+    #   if and only if `$string` was quoted
+    # @raise [ArgumentError] if any parameter is the wrong type
     def str_slice(string, start_at, end_at = nil)
-      assert_type string, :String
+      assert_type string, :String, :string
       assert_unit start_at, nil, "start-at"
 
-      end_at = Sass::Script::Value::Number.new(-1)if end_at.nil?
+      end_at = Sass::Script::Value::Number.new(-1) if end_at.nil?
       assert_unit end_at, nil, "end-at"
 
       s = start_at.value > 0 ? start_at.value - 1 : start_at.value
@@ -1282,33 +1331,37 @@ module Sass::Script
     declare :str_slice, [:string, :start_at]
     declare :str_slice, [:string, :start_at, :end_at]
 
-    # Convert a string to upper case
+    # Converts a string to upper case.
     #
-    # @return [Sass::Script::Value::String]
-    # @raise [ArgumentError] if `string` isn't a string
     # @example
     #   to-upper-case(abcd) => ABCD
-    #   to-upper-case("abcd") => "ABCD"
+    #
+    # @overload to_upper_case($string)
+    # @param $string [Sass::Script::Value::String]
+    # @return [Sass::Script::Value::String]
+    # @raise [ArgumentError] if `$string` isn't a string
     def to_upper_case(string)
-      assert_type string, :String
+      assert_type string, :String, :string
       Sass::Script::Value::String.new(string.value.upcase, string.type)
     end
     declare :to_upper_case, [:string]
 
-    # Convert a string to lower case
+    # Convert a string to lower case,
     #
-    # @return [Sass::Script::Value::String]
-    # @raise [ArgumentError] if `string` isn't a string
     # @example
     #   to-lower-case(ABCD) => abcd
-    #   to-lower-case("ABCD") => "abcd"
+    #
+    # @overload to_lower_case($string)
+    # @param $string [Sass::Script::Value::String]
+    # @return [Sass::Script::Value::String]
+    # @raise [ArgumentError] if `$string` isn't a string
     def to_lower_case(string)
-      assert_type string, :String
+      assert_type string, :String, :string
       Sass::Script::Value::String.new(string.value.downcase, string.type)
     end
     declare :to_lower_case, [:string]
 
-    # Inspects the type of the argument, returning it as an unquoted string.
+    # Returns the type of a value.
     #
     # @example
     #   type-of(100px)  => number
@@ -1317,29 +1370,33 @@ module Sass::Script
     #   type-of(true)   => bool
     #   type-of(#fff)   => color
     #   type-of(blue)   => color
-    # @param value [Value] The object to inspect
-    # @return [Sass::Script::Value::String] The unquoted string name of the value's type
+    # @overload type_of($value)
+    # @param $value [Sass::Script::Value::Base] The value to inspect
+    # @return [Sass::Script::Value::String] The unquoted string name of the
+    #   value's type
     def type_of(value)
       Sass::Script::Value::String.new(value.class.name.gsub(/Sass::Script::Value::/,'').downcase)
     end
     declare :type_of, [:value]
 
-    # Returns true if the feature name specified exists in the current Sass runtime.
+    # Returns whether a feature exists in the current Sass runtime.
     #
     # @example
     #   feature-exists(some-feature-that-exists) => true
     #   feature-exists(what-is-this-i-dont-know) => false
     #
-    # @param feature [Sass::Script::Value::String] The name of the feature to check
-    # @return [Sass::Script::Value::Bool] Whether the feature is supported in this version of Sass.
+    # @overload feature_exists($feature)
+    # @param $feature [Sass::Script::Value::String] The name of the feature
+    # @return [Sass::Script::Value::Bool] Whether the feature is supported in this version of Sass
+    # @raise [ArgumentError] if `$feature` isn't a string
     def feature_exists(feature)
+      assert_type feature, :String, :feature
       Sass::Script::Value::Bool.new(Sass.has_feature?(feature.value))
     end
     declare :feature_exists, [:feature]
 
-
-    # Inspects the unit of the number, returning it as a quoted string.
-    # Complex units are sorted in alphabetical order by numerator and denominator.
+    # Returns the unit(s) associated with a number. Complex units are sorted in
+    # alphabetical order by numerator and denominator.
     #
     # @example
     #   unit(100) => ""
@@ -1347,57 +1404,62 @@ module Sass::Script
     #   unit(3em) => "em"
     #   unit(10px * 5em) => "em*px"
     #   unit(10px * 5em / 30cm / 1rem) => "em*px/cm*rem"
-    # @param number [Value] The number to inspect
-    # @return [Sass::Script::Value::String] The unit(s) of the number
-    # @raise [ArgumentError] if `number` isn't a number
+    # @overload unit($number)
+    # @param $number [Sass::Script::Value::Number]
+    # @return [Sass::Script::Value::String] The unit(s) of the number, as a
+    #   quoted string
+    # @raise [ArgumentError] if `$number` isn't a number
     def unit(number)
-      assert_type number, :Number
+      assert_type number, :Number, :number
       Sass::Script::Value::String.new(number.unit_str, :string)
     end
     declare :unit, [:number]
 
-    # Inspects the unit of the number, returning a boolean indicating if it is unitless.
+    # Returns whether a number has units.
     #
     # @example
     #   unitless(100) => true
     #   unitless(100px) => false
-    # @param number [Value] The number to inspect
-    # @return [Sass::Script::Value::Bool] Whether or not the number is unitless
-    # @raise [ArgumentError] if `number` isn't a number
+    # @overload unitless($number)
+    # @param $number [Sass::Script::Value::Number]
+    # @return [Sass::Script::Value::Bool]
+    # @raise [ArgumentError] if `$number` isn't a number
     def unitless(number)
-      assert_type number, :Number
+      assert_type number, :Number, :number
       Sass::Script::Value::Bool.new(number.unitless?)
     end
     declare :unitless, [:number]
 
-    # Returns true if two numbers are similar enough to be added, subtracted, or compared.
+    # Returns whether two numbers can added, subtracted, or compared.
     #
     # @example
     #   comparable(2px, 1px) => true
     #   comparable(100px, 3em) => false
     #   comparable(10cm, 3mm) => true
-    # @param number_1 [Sass::Script::Value::Number]
-    # @param number_2 [Sass::Script::Value::Number]
-    # @return [Sass::Script::Value::Bool] indicating if the numbers can be compared.
-    # @raise [ArgumentError] if `number_1` or `number_2` aren't numbers
+    # @overload comparable($number-1, $number-2)
+    # @param $number-1 [Sass::Script::Value::Number]
+    # @param $number-2 [Sass::Script::Value::Number]
+    # @return [Sass::Script::Value::Bool]
+    # @raise [ArgumentError] if either parameter is the wrong type
     def comparable(number_1, number_2)
-      assert_type number_1, :Number
-      assert_type number_2, :Number
+      assert_type number_1, :Number, :number_1
+      assert_type number_2, :Number, :number_2
       Sass::Script::Value::Bool.new(number_1.comparable_to?(number_2))
     end
     declare :comparable, [:number_1, :number_2]
 
-    # Converts a decimal number to a percentage.
+    # Converts a unitless number to a percentage.
     #
     # @example
+    #   percentage(0.2) => 20%
     #   percentage(100px / 50px) => 200%
-    # @param value [Sass::Script::Value::Number]
-    #   The decimal number to convert to a percentage
-    # @return [Sass::Script::Value::Number] The percentage
-    # @raise [ArgumentError] If `value` isn't a unitless number
+    # @overload percentage($value)
+    # @param $value [Sass::Script::Value::Number]
+    # @return [Sass::Script::Value::Number]
+    # @raise [ArgumentError] if `$value` isn't a unitless number
     def percentage(value)
       unless value.is_a?(Sass::Script::Value::Number) && value.unitless?
-        raise ArgumentError.new("#{value.inspect} is not a unitless number")
+        raise ArgumentError.new("$value: #{value.inspect} is not a unitless number")
       end
       Sass::Script::Value::Number.new(value.value * 100, ['%'])
     end
@@ -1408,76 +1470,83 @@ module Sass::Script
     # @example
     #   round(10.4px) => 10px
     #   round(10.6px) => 11px
-    # @param value [Sass::Script::Value::Number] The number
-    # @return [Sass::Script::Value::Number] The rounded number
-    # @raise [ArgumentError] if `value` isn't a number
+    # @overload round($value)
+    # @param $value [Sass::Script::Value::Number]
+    # @return [Sass::Script::Value::Number]
+    # @raise [ArgumentError] if `$value` isn't a number
     def round(value)
       numeric_transformation(value) {|n| n.round}
     end
     declare :round, [:value]
 
-    # Rounds a number up to the nearest whole number.
+    # Rounds a number up to the next whole number.
     #
     # @example
     #   ceil(10.4px) => 11px
     #   ceil(10.6px) => 11px
-    # @param value [Sass::Script::Value::Number] The number
-    # @return [Sass::Script::Value::Number] The rounded number
-    # @raise [ArgumentError] if `value` isn't a number
+    # @overload ceil($value)
+    # @param $value [Sass::Script::Value::Number]
+    # @return [Sass::Script::Value::Number]
+    # @raise [ArgumentError] if `$value` isn't a number
     def ceil(value)
       numeric_transformation(value) {|n| n.ceil}
     end
     declare :ceil, [:value]
 
-    # Rounds down to the nearest whole number.
+    # Rounds a number down to the previous whole number.
     #
     # @example
     #   floor(10.4px) => 10px
     #   floor(10.6px) => 10px
-    # @param value [Sass::Script::Value::Number] The number
-    # @return [Sass::Script::Value::Number] The rounded number
-    # @raise [ArgumentError] if `value` isn't a number
+    # @overload floor($value)
+    # @param $value [Sass::Script::Value::Number]
+    # @return [Sass::Script::Value::Number]
+    # @raise [ArgumentError] if `$value` isn't a number
     def floor(value)
       numeric_transformation(value) {|n| n.floor}
     end
     declare :floor, [:value]
 
-    # Finds the absolute value of a number.
+    # Returns the absolute value of a number.
     #
     # @example
     #   abs(10px) => 10px
     #   abs(-10px) => 10px
-    # @param value [Sass::Script::Value::Number] The number
-    # @return [Sass::Script::Value::Number] The absolute value
-    # @raise [ArgumentError] if `value` isn't a number
+    # @overload abs($value)
+    # @param $value [Sass::Script::Value::Number]
+    # @return [Sass::Script::Value::Number]
+    # @raise [ArgumentError] if `$value` isn't a number
     def abs(value)
       numeric_transformation(value) {|n| n.abs}
     end
     declare :abs, [:value]
 
-    # Finds the minimum of several values. This function takes any number of
+    # Finds the minimum of several numbers. This function takes any number of
     # arguments.
     #
     # @example
     #   min(1px, 4px) => 1px
     #   min(5em, 3em, 4em) => 3em
-    # @param values [Array<Sass::Script::Value::Number>] The numbers
-    # @return [Sass::Script::Value::Number] The minimum value
+    # @overload min($numbers...)
+    # @param $numbers [[Sass::Script::Value::Number]]
+    # @return [Sass::Script::Value::Number]
     # @raise [ArgumentError] if any argument isn't a number, or if not all of
     #   the arguments have comparable units
-    def min(*values)
-      values.each {|v| assert_type v, :Number}
-      values.inject {|min, val| min.lt(val).to_bool ? min : val}
+    def min(*numbers)
+      numbers.each {|n| assert_type n, :Number}
+      numbers.inject {|min, num| min.lt(num).to_bool ? min : num}
     end
     declare :min, [], :var_args => :true
 
-    # Finds the maximum of several values. This function takes any number of
+    # Finds the maximum of several numbers. This function takes any number of
     # arguments.
     #
     # @example
     #   max(1px, 4px) => 4px
     #   max(5em, 3em, 4em) => 5em
-    # @return [Sass::Script::Value::Number] The maximum value
+    # @overload max($numbers...)
+    # @param $numbers [[Sass::Script::Value::Number]]
+    # @return [Sass::Script::Value::Number]
     # @raise [ArgumentError] if any argument isn't a number, or if not all of
     #   the arguments have comparable units
     def max(*values)
@@ -1491,8 +1560,9 @@ module Sass::Script
     # @example
     #   length(10px) => 1
     #   length(10px 20px 30px) => 3
-    # @param list [Value] The list
-    # @return [Sass::Script::Value::Number] The length
+    # @overload length($list)
+    # @param $list [Sass::Script::Value::Base]
+    # @return [Sass::Script::Value::Number]
     def length(list)
       Sass::Script::Value::Number.new(list.to_a.size)
     end
@@ -1500,21 +1570,21 @@ module Sass::Script
 
     # Gets the nth item in a list.
     #
-    # Note that unlike some languages, the first item in a Sass list is number 1,
-    # the second number 2, and so forth. You can also use negative numbers to
-    # count from the end of the list. So -1 is the last item, -2 is the
-    # second-to-last item, etc.
+    # Note that unlike some languages, the first item in a Sass list is number
+    # 1, the second number 2, and so forth.
     #
     # @example
     #   nth(10px 20px 30px, 1) => 10px
     #   nth((Helvetica, Arial, sans-serif), 3) => sans-serif
-    #   nth((red, green, blue), -2) => green
-    # @param list [Value] The list
-    # @param n [Sass::Script::Value::Number] The index into the list
-    # @return [Sass::Script::Value::Base] The nth item in the list
-    # @raise [ArgumentError] If `n` isn't an integer whose absolute value is between 1 and the list's length.
+    # @overload nth($list, $n)
+    # @param $list [Sass::Script::Value::Base]
+    # @param $n [Sass::Script::Value::Number] The index of the item to get.
+    #   Negative indices count from the end of the list.
+    # @return [Sass::Script::Value::Base]
+    # @raise [ArgumentError] if `$n` isn't an integer between 1 and the length
+    #   of `$list`
     def nth(list, n)
-      assert_type n, :Number
+      assert_type n, :Number, :n
       if !n.int? || n.to_i == 0
         raise ArgumentError.new("List index #{n} must be a non-zero integer")
       elsif list.to_a.size == 0
@@ -1528,12 +1598,12 @@ module Sass::Script
     end
     declare :nth, [:list, :n]
 
-    # Joins together two lists into a new list.
+    # Joins together two lists into one.
     #
-    # Unless the `$separator` argument is passed,
-    # if one list is comma-separated and one is space-separated,
-    # the first parameter's separator is used for the resulting list.
-    # If the lists have only one item each, spaces are used for the resulting list.
+    # Unless `$separator` is passed, if one list is comma-separated and one is
+    # space-separated, the first parameter's separator is used for the resulting
+    # list. If both lists have fewer than two items, spaces are used for the
+    # resulting list.
     #
     # @example
     #   join(10px 20px, 30px 40px) => 10px 20px 30px 40px
@@ -1541,15 +1611,15 @@ module Sass::Script
     #   join(10px, 20px) => 10px 20px
     #   join(10px, 20px, comma) => 10px, 20px
     #   join((blue, red), (#abc, #def), space) => blue red #abc #def
-    # @overload join(list1, list2, separator: auto)
-    #   @param list1 [Value] The first list to join
-    #   @param list2 [Value] The second list to join
-    #   @param separator [Sass::Script::Value::String]
-    #     How the list separator (comma or space) should be determined. If this
-    #     is `comma` or `space`, that is always the separator; if this is `auto`
-    #     (the default), the separator is determined as explained above.
+    # @overload join($list1, $list2, $separator: auto)
+    # @param $list1 [Sass::Script::Value::Base]
+    # @param $list2 [Sass::Script::Value::Base]
+    # @param $separator [Sass::Script::Value::String] The list separator to use.
+    #   If this is `comma` or `space`, that separator will be used. If this is
+    #   `auto` (the default), the separator is determined as explained above.
+    # @return [Sass::Script::Value::List]
     def join(list1, list2, separator = Sass::Script::Value::String.new("auto"))
-      assert_type separator, :String
+      assert_type separator, :String, :separator
       unless %w[auto space comma].include?(separator.value)
         raise ArgumentError.new("Separator name must be space, comma, or auto")
       end
@@ -1568,8 +1638,7 @@ module Sass::Script
 
     # Appends a single value onto the end of a list.
     #
-    # Unless the `$separator` argument is passed,
-    # if the list has only one item,
+    # Unless the `$separator` argument is passed, if the list had only one item,
     # the resulting list will be space-separated.
     #
     # @example
@@ -1578,15 +1647,15 @@ module Sass::Script
     #   append(10px 20px, 30px 40px) => 10px 20px (30px 40px)
     #   append(10px, 20px, comma) => 10px, 20px
     #   append((blue, red), green, space) => blue red green
-    # @overload append(list, val, separator: auto)
-    #   @param list [Value] The list to add the value to
-    #   @param val [Value] The value to add to the end of the list
-    #   @param separator [Sass::Script::Value::String]
-    #     How the list separator (comma or space) should be determined. If this
-    #     is `comma` or `space`, that is always the separator; if this is `auto`
-    #     (the default), the separator is the same as that used by the list.
-    def append(list, val, separator = Sass::Script::Value::String.new("auto"))
-      assert_type separator, :String
+    # @overload append($list, $val, $separator: auto)
+    # @param $list [Sass::Script::Value::Base]
+    # @param $val [Sass::Script::Value::Base]
+    # @param $separator [Sass::Script::Value::String] The list separator to use.
+    #   If this is `comma` or `space`, that separator will be used. If this is
+    #   `auto` (the default), the separator is determined as explained above.
+    # @return [Sass::Script::Value::List]
+    def append(list, val, separator = Sass::Script::String.new("auto"))
+      assert_type separator, :String, :separator
       unless %w[auto space comma].include?(separator.value)
         raise ArgumentError.new("Separator name must be space, comma, or auto")
       end
@@ -1602,8 +1671,9 @@ module Sass::Script
     declare :append, [:list, :val]
     declare :append, [:list, :val, :separator]
 
-    # Combines several lists into a single comma separated list, where the nth
-    # value is a space separated list of the source lists' nth values.
+    # Combines several lists into a single multidimensional list. The nth value
+    # of the resulting list is a space separated list of the source lists' nth
+    # values.
     #
     # The length of the resulting list is the length of the
     # shortest list.
@@ -1611,6 +1681,9 @@ module Sass::Script
     # @example
     #   zip(1px 1px 3px, solid dashed solid, red green blue)
     #   => 1px solid red, 1px dashed green, 3px solid blue
+    # @overload zip($lists...)
+    # @param $lists [[Sass::Script::Value::Base]]
+    # @return [Sass::Script::Value::List]
     def zip(*lists)
       length = nil
       values = []
@@ -1628,12 +1701,20 @@ module Sass::Script
     declare :zip, [], :var_args => true
 
 
-    # Returns the position of a value within a list. If not found, returns
-    # false.
+    # Returns the position of a value within a list. If the value isn't found,
+    # returns false instead.
+    #
+    # Note that unlike some languages, the first item in a Sass list is number
+    # 1, the second number 2, and so forth.
     #
     # @example
     #   index(1px solid red, solid) => 2
     #   index(1px solid red, dashed) => false
+    # @overload index($list, $value)
+    # @param $list [Sass::Script::Value::Base]
+    # @param $value [Sass::Script::Value::Base]
+    # @return [Sass::Script::Value::Number, Sass::Script::Value::Bool] The
+    #   1-based index of `$value` in `$list`, or `false`
     def index(list, value)
       index = list.to_a.index {|e| e.eq(value).to_bool }
       if index
@@ -1644,13 +1725,16 @@ module Sass::Script
     end
     declare :index, [:list, :value]
 
-    # Returns the separator of the given list.
-    # If not a list, returns false.
+    # Returns the separator of a list. If the list doesn't have a separator due
+    # to having fewer than two elements, returns `space`.
     #
     # @example
-    #   list-separator(1px 2px 3px) => 'space'
-    #   list-separator(1px, 2px, 3px) => 'comma'
-    #   list-separator('foo') => 'space'
+    #   list-separator(1px 2px 3px) => space
+    #   list-separator(1px, 2px, 3px) => comma
+    #   list-separator('foo') => space
+    # @overload list_separator($list)
+    # @param $list [Sass::Script::Value::Base]
+    # @return [Sass::Script::Value::String] `comma` or `space`
     def list_separator(list)
       if list.is_a?(Sass::Script::Value::List)
         Sass::Script::Value::String.new(list.separator.to_s)
@@ -1660,15 +1744,19 @@ module Sass::Script
     end
     declare :separator, [:list]
 
-    # Returns one of two values based on the truth value of the first argument.
+    # Returns one of two values, depending on whether or not `$condition` is
+    # true. Just like in `@if`, all values other than `false` and `null` are
+    # considered to be true.
     #
     # @example
     #   if(true, 1px, 2px) => 1px
     #   if(false, 1px, 2px) => 2px
-    # @param condition [Sass::Script::Value::Bool]
-    #   Whether the first or second value will be returned.
-    # @param if_true [Value] The value that will be returned if `$condition` is true.
-    # @param if_false [Value] The value that will be returned if `$condition` is false.
+    # @overload if($condition, $if-true, $if-false)
+    # @param $condition [Sass::Script::Value::Base] Whether the `$if-true` or
+    #   `$if-false` will be returned
+    # @param $if-true [Sass::Script::Value::Base]
+    # @param $if-false [Sass::Script::Value::Base]
+    # @return [Sass::Script::Value::Base] `$if-true` or `$if-false`
     def if(condition, if_true, if_false)
       if condition.to_bool
         if_true
@@ -1678,9 +1766,12 @@ module Sass::Script
     end
     declare :if, [:condition, :if_true, :if_false]
 
-    # Returns a unique unquoted string that is a legal CSS identifier. The
-    # identifier returned is only guaranteed to be unique within the scope of a
-    # single Sass run.
+    # Returns a unique CSS identifier. The identifier is returned as an unquoted
+    # string. The identifier returned is only guaranteed to be unique within the
+    # scope of a single Sass run.
+    #
+    # @overload unique_id()
+    # @return [Sass::Script::Value::String]
     def unique_id
       Thread.current[:sass_last_unique_id] ||= rand(36**8)
       # avoid the temptation of trying to guess the next unique value.
@@ -1697,6 +1788,8 @@ module Sass::Script
     #
     # @example
     #   counter(item, ".") => counter(item,".")
+    # @overload counter($args...)
+    # @return [String]
     def counter(*args)
       Sass::Script::Value::String.new("counter(#{args.map {|a| a.to_s(options)}.join(',')})")
     end
@@ -1708,13 +1801,13 @@ module Sass::Script
     # another numeric value with the same units.
     # It yields a number to a block to perform the operation and return a number
     def numeric_transformation(value)
-      assert_type value, :Number
+      assert_type value, :Number, :value
       Sass::Script::Value::Number.new(yield(value.value), value.numerator_units, value.denominator_units)
     end
 
     def _adjust(color, amount, attr, range, op, units = "")
-      assert_type color, :Color
-      assert_type amount, :Number
+      assert_type color, :Color, :color
+      assert_type amount, :Number, :amount
       Sass::Util.check_range('Amount', range, amount, units)
 
       # TODO: is it worth restricting here,