update docs and move complement into combination function. Issue #56

Author: bgrins

README.md

@@ -1,13 +1,19 @@
 # TinyColor
 
-## JavaScript color parsing
+## JavaScript color tooling
 
-Fast, small color manipulation and conversion for JavaScript.  TinyColor is allows many forms of input, while providing color conversions and other color utility functions.  It has no dependencies.
+TinyColor is a small, fast library for color manipulation and conversion in JavaScript.  It allows many forms of input, while providing color conversions and other color utility functions.  It has no dependencies.
 
 [![Build Status](https://travis-ci.org/bgrins/TinyColor.png?branch=master)](https://travis-ci.org/bgrins/TinyColor)
 
 ## Including in a browser
 
+Download [tinycolor.js](https://raw.githubusercontent.com/bgrins/TinyColor/master/tinycolor.js) or install it with bower:
+
+    bower install tinycolor
+
+Then just include it in the page in a `script` tag:
+
     <script type='text/javascript' src='tinycolor.js'></script>
     <script type='text/javascript'>
     var color = tinycolor("red");
@@ -238,33 +244,118 @@ Print to a string, depending on the input format.  You can also override this by
     color2.setAlpha(.5);
     color2.toString(); // "rgba(255, 0, 0, 0.5)"
 
-## Color Utilities
+### Color Modification
 
-    tinycolor.equals(color1, color2)
+These methods manipulate the current color, and return it for chaining.  For instance:
 
-### Color Modification
+    tinycolor("red").lighten().desaturate().toHexString() // "#f53d3d"
 
-Modification functions may take an `amount` variable from 0 - 100, indicating how much the effect should be applied.
+### lighten
 
-    tinycolor.lighten(color, amount = 10)
-    tinycolor.brighten(color, amount = 10)
-    tinycolor.darken(color, amount = 10)
-    tinycolor.desaturate(color, amount = 10)
-    tinycolor.saturate(color, amount = 10)
-    tinycolor.greyscale(color)
-    tinycolor.spin(color, amount)
-    tinycolor.mix(color1, color2, amount = 50)
+`lighten: function(amount = 10) -> TinyColor`.  Lighten the color a given amount, from 0 to 100.  Providing 100 will always return white.
+
+    tinycolor("#f00").lighten().toString(); // "#ff3333"
+    tinycolor("#f00").lighten(100).toString(); // "#ffffff"
+
+### brighten
+
+`brighten: function(amount = 10) -> TinyColor`.  Brighten the color a given amount, from 0 to 100.
+
+    tinycolor("#f00").brighten().toString(); // "#ff1919"
+
+### darken
+
+`darken: function(amount = 10) -> TinyColor`.  Darken the color a given amount, from 0 to 100.  Providing 100 will always return black.
+
+    tinycolor("#f00").darken().toString(); // "#cc0000"
+    tinycolor("#f00").darken(100).toString(); // "#000000"
+
+### desaturate
+
+`desaturate: function(amount = 10) -> TinyColor`.  Desaturate the color a given amount, from 0 to 100.  Providing 100 will is the same as calling `greyscale`.
+
+    tinycolor("#f00").desaturate().toString(); // "#f20d0d"
+    tinycolor("#f00").desaturate(100).toString(); // "#808080"
+
+### saturate
+
+`saturate: function(amount = 10) -> TinyColor`.  Saturate the color a given amount, from 0 to 100.
+
+    tinycolor("hsl(0, 10%, 50%)").saturate().toString(); // "hsl(0, 20%, 50%)"
+
+### greyscale
+
+`greyscale: function() -> TinyColor`.  Completely desaturates a color into greyscale.  Same as calling `desaturate(100)`.
+
+    tinycolor("#f00").greyscale().toString(); // "#808080"
+
+### spin
+
+`spin: function(amount = 0) -> TinyColor`.  Spin the hue a given amount, from -360 to 360.  Calling with 0, 360, or -360 will do nothing (since it sets the hue back to what it was before).
+
+    tinycolor("#f00").spin(180).toString(); // "#00ffff"
+    tinycolor("#f00").spin(-90).toString(); // "#7f00ff"
+    tinycolor("#f00").spin(90).toString(); // "#80ff00"
+
+    // spin(0) and spin(360) do nothing
+    tinycolor("#f00").spin(0).toString(); // "#ff0000"
+    tinycolor("#f00").spin(360).toString(); // "#ff0000"
 
 ### Color Combinations
 
-Combination functions return an Array of TinyColor objects.
+Combination functions return an array of TinyColor objects unless otherwise noted.
 
-    tinycolor.analogous(color, results = 6, slices = 30)
-    tinycolor.complement(color)
-    tinycolor.monochromatic(color, results = 6)
-    tinycolor.splitcomplement(color)
-    tinycolor.triad(color)
-    tinycolor.tetrad(color)
+### analogous
+
+`analogous: function(, results = 6, slices = 30) -> array<TinyColor>`.
+
+    var colors = tinycolor("#f00").analogous();
+
+    colors.map(function(t) { return t.toHexString(); }); // [ "#ff0000", "#ff0066", "#ff0033", "#ff0000", "#ff3300", "#ff6600" ]
+
+### monochromatic
+
+`monochromatic: function(, results = 6) -> array<TinyColor>`.
+
+    var colors = tinycolor("#f00").monochromatic();
+
+    colors.map(function(t) { return t.toHexString(); }); // [ "#ff0000", "#2a0000", "#550000", "#800000", "#aa0000", "#d40000" ]
+
+### splitcomplement
+
+`splitcomplement: function() -> array<TinyColor>`.
+
+    var colors = tinycolor("#f00").splitcomplement();
+
+    colors.map(function(t) { return t.toHexString(); }); // [ "#ff0000", "#ccff00", "#0066ff" ]
+
+### triad
+
+`triad: function() -> array<TinyColor>`.
+
+    var colors = tinycolor("#f00").triad();
+
+    colors.map(function(t) { return t.toHexString(); }); // [ "#ff0000", "#00ff00", "#0000ff" ]
+
+### tetrad
+
+`tetrad: function() -> array<TinyColor>`.
+
+    var colors = tinycolor("#f00").tetrad();
+
+    colors.map(function(t) { return t.toHexString(); }); // [ "#ff0000", "#80ff00", "#00ffff", "#7f00ff" ]
+
+
+### complement
+
+`complement: function() -> TinyColor`.
+
+    tinycolor("#f00").complement().toHexString(); // "#00ffff"
+
+## Color Utilities
+
+    tinycolor.equals(color1, color2)
+    tinycolor.mix(color1, color2, amount = 50)
 
 ### Readability
 

test/test.js

@@ -577,7 +577,6 @@ test("Modifications", function () {
   }
 
   equal (tinycolor("red").greyscale().toHex(), "808080", "Greyscale works");
-  equal (tinycolor("red").complement().toHex(), "00ffff", "Complement works");
 });
 
 test("Spin", function () {
@@ -625,6 +624,12 @@ function colorsToHexString(colors) {
   }).join(",");
 }
 
+test("complement", function() {
+  var complementDoesntModifyInstance = tinycolor("red");
+  equal (complementDoesntModifyInstance.complement().toHex(), "00ffff", "Complement works");
+  equal (complementDoesntModifyInstance.toHex(), "ff0000", "Complement did not modify this color");
+});
+
 test("analogous", function() {
   var combination = tinycolor("red").analogous();
   equal(colorsToHexString(combination), "ff0000,ff0066,ff0033,ff0000,ff3300,ff6600", "Correct Combination");

tinycolor.js

@@ -219,16 +219,16 @@ tinycolor.prototype = {
     spin: function() {
         return this._applyModification(spin, arguments);
     },
-    complement: function() {
-        return this._applyModification(complement, arguments);
-    },
 
     _applyCombination: function(fn, args) {
         return fn.apply(null, [this].concat([].slice.call(args)));
     },
     analogous: function() {
         return this._applyCombination(analogous, arguments);
     },
+    complement: function() {
+        return this._applyCombination(complement, arguments);
+    },
     monochromatic: function() {
         return this._applyCombination(monochromatic, arguments);
     },
@@ -566,12 +566,6 @@ function darken (color, amount) {
     return tinycolor(hsl);
 }
 
-function complement(color) {
-    var hsl = tinycolor(color).toHsl();
-    hsl.h = (hsl.h + 180) % 360;
-    return tinycolor(hsl);
-}
-
 // Spin takes a positive or negative amount within [-360, 360] indicating the change of hue.
 // Values outside of this range will be wrapped into this range.
 function spin(color, amount) {
@@ -586,6 +580,12 @@ function spin(color, amount) {
 // Thanks to jQuery xColor for some of the ideas behind these
 // <https://github.com/infusion/jQuery-xcolor/blob/master/jquery.xcolor.js>
 
+function complement(color) {
+    var hsl = tinycolor(color).toHsl();
+    hsl.h = (hsl.h + 180) % 360;
+    return tinycolor(hsl);
+}
+
 function triad(color) {
     var hsl = tinycolor(color).toHsl();
     var h = hsl.h;