Write docs.

Readme.md

@@ -4,8 +4,83 @@
 
 [![browser support](http://ci.testling.com/Gozala/interset.png)](http://ci.testling.com/Gozala/interset)
 
-Binary operations for logical sets
+Binary operations for logical sets in our case arrays, although in a future
+support for upcoming sets maybe added.
+
+## API
+
+#### union
+
+Return a set that is the [union][] of the input sets.
+
+[!union](http://upload.wikimedia.org/wikipedia/commons/thumb/3/30/Venn0111.svg/200px-Venn0111.svg.png)
+
+
+```js
+var union = require("interset/union")
+
+union()
+// => []
+
+union([1, 2])
+// => [1, 2]
+
+union([1, 2], [2, 3])
+// => [1, 2, 3]
+
+union([1, 2], [2, 3], [3, 4])
+// => [1, 2, 3, 4]
+```
+
+#### intersection
+
+Return a set that is the [intersection][] of the input sets.
+
+[!intersection](http://upload.wikimedia.org/wikipedia/commons/thumb/9/99/Venn0001.svg/200px-Venn0001.svg.png)
+
+```js
+intersection()
+// => TypeError: intersection requires at least one argument
+
+intersection([1])
+// => [1]
+
+intersection([1, 2], [2, 3])
+// => [2]
+
+intersection([1, 2], [2, 3], [3, 4])
+// => []
+
+intersection([1, "a"], ["a", 3], ["a"])
+// => ["a"]
+```
+
+#### difference
+
+Return a set that is the first set without elements of the remaining sets
+
+[!difference](http://upload.wikimedia.org/wikipedia/commons/thumb/5/5a/Venn0010.svg/200px-Venn0010.svg.png)
+
+```js
+var difference = require("interset/difference")
+
+difference()
+// => TypeError: difference requires at least one arguments
+
+difference([1, 2, 3])
+// => [1, 2, 3]
+
+difference([1, 2], [2, 3])
+// => [1]
+
+difference([1, 2, 3], [1], [1, 4], [3])
+// => [2]
+```
 
 ## Install
 
     npm install interset
+
+[union]:http://en.wikipedia.org/wiki/Union_%28set_theory%29
+[intersection]:http://en.wikipedia.org/wiki/Intersection_%28set_theory%29
+[difference]:http://en.wikipedia.org/wiki/Set_difference#Relative_complement

difference.js

@@ -4,9 +4,26 @@ var slicer = Array.prototype.slice
 var concater = Array.prototype.concat
 var excludes = function excludes(item) { return this.indexOf(item) < 0 }
 
-module.exports = function difference(source, exclude, rest) {
-  if (!source) throw TypeError("difference requires  at least one arguments")
-  if (!exclude) return source
-  exclude = concater.apply([], slicer.call(arguments, 1))
-  return source.filter(excludes, exclude)
+module.exports = function difference(first, second) {
+  /**
+  Return a set that is the `first` set without elements of the remaining sets
+
+      var difference = require("interset/difference")
+
+      difference()
+      // => TypeError: difference requires at least one arguments
+
+      difference([1, 2, 3])
+      // => [1, 2, 3]
+
+      difference([1, 2], [2, 3])
+      // => [1]
+
+      difference([1, 2, 3], [1], [1, 4], [3])
+      // => [2]
+  **/
+  if (!first) throw TypeError("difference requires at least one argument")
+  if (!second) return first
+  var remaining = concater.apply([], slicer.call(arguments, 1))
+  return first.filter(excludes, remaining)
 }

intersection.js

@@ -3,14 +3,34 @@
 var slicer = Array.prototype.slice
 var contains = function(item) { return this.indexOf(item) >= 0 }
 
-function intersection2(first, second) {
-  return first.length > second.length ? first.filter(contains, second) :
-         second.filter(contains, first)
+function intersection2(a, b) {
+  return a.length > b.length ? a.filter(contains, b) :
+         b.filter(contains, a)
 }
 
-module.exports = function intersection(first, second, rest) {
-  if (!first) throw TypeError("intersection requires  at least one arguments")
-  if (!second) return first
-  if (!rest) return intersection2(first, second)
-  return slicer.call(arguments, 1).reduce(intersection2, first)
+module.exports = function intersection(a, b, rest) {
+  /**
+  Return a set that is the [intersection][] of the input sets.
+
+      var intersection = require("interset/intersection")
+
+      intersection()
+      // => TypeError: intersection requires at least one arguments
+
+      intersection([1])
+      // => [1]
+
+      intersection([1, 2], [2, 3])
+      // => [2]
+
+      intersection([1, 2], [2, 3], [3, 4])
+      // => []
+
+      intersection([1, "a"], ["a", 3], ["a"])
+      // => ["a"]
+  **/
+  if (!a) throw TypeError("intersection requires at least one argument")
+  if (!b) return a
+  if (!rest) return intersection2(a, b)
+  return slicer.call(arguments, 1).reduce(intersection2, a)
 }

union.js

@@ -10,8 +10,25 @@ function include(union, set) {
   return set.reduce(add, union)
 }
 
-module.exports = function union(first, second, rest) {
-  if (!first) return []
-  if (!second) return first
+module.exports = function union(a, b) {
+  /**
+  Return a set that is the [union][] of the input sets.
+
+      var union = require("interset/union")
+
+      union()
+      // => []
+
+      union([1, 2])
+      // => [1, 2]
+
+      union([1, 2], [2, 3])
+      // => [1, 2, 3]
+
+      union([1, 2], [2, 3], [3, 4])
+      // => [1, 2, 3, 4]
+  **/
+  if (!a) return []
+  if (!b) return a
   return slicer.call(arguments).reduce(include, [])
 }