From 2e331a484cb17e458fc2e05b74828d78f472ddee Mon Sep 17 00:00:00 2001
From: Jake Luer <jake@alogicalparadox.com>
Date: Wed, 14 Aug 2013 15:04:25 +0300
Subject: [PATCH] readme: document all methods

---
 README.md   | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 lib/type.js |  35 ++++++++++--
 2 files changed, 183 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 565b4f4..bcfbc3c 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,158 @@
 
     $ component install chaijs/type-detect
 
+## Usage
+
+### Primary
+
+The primary export of `type-detect` is function that can server as a replacement for 
+`typeof`. The results of this function will be more specific than that of native `typeof`.
+
+```js
+var type = require('type-detect');
+```
+
+#### array
+
+```js
+assert('array' === type([]));
+assert('array' === type(new Array()));
+```
+
+#### regexp
+
+```js
+assert('regexp' === type(/a-z/gi));
+assert('regexp' === type(new RegExp('a-z')));
+```
+
+#### function
+
+```js
+assert('function' === type(function () {}));
+```
+
+#### arguments
+
+```js
+(function () {
+  assert('arguments' === type(arguments));
+})();
+```
+
+#### date
+
+```js
+assert('date' === type(new Date));
+```
+
+#### number
+
+```js
+assert('number' === type(1));
+assert('number' === type(1.234));
+assert('number' === type(-1));
+assert('number' === type(-1.234));
+assert('number' === type(Infinity));
+assert('number' === type(NaN));
+```
+
+#### string
+
+```js
+assert('string' === type('hello world'));
+```
+
+#### null
+
+```js
+assert('null' === type(null));
+assert('null' !== type(undefined));
+```
+
+#### undefined
+
+```js
+assert('undefined' === type(undefined));
+assert('undefined' !== type(null));
+```
+
+#### object
+
+```js
+var Noop = function () {};
+assert('object' === type({}));
+assert('object' !== type(Noop));
+assert('object' === type(new Noop));
+assert('object' === type(new Object));
+assert('object' === type(new String('hello')));
+```
+
+### Library
+
+A `Library` is a small constructed repository for custom type detections.
+
+```js
+var lib = new type.Library;
+```
+
+#### .of (obj)
+
+* **@param** _{Mixed}_ object to test
+* **@return** _{String}_  type
+
+Expose replacement `typeof` detection to the library.
+
+```js
+if ('string' === lib.of('hello world')) {
+  // ...
+}
+```
+
+
+#### .define (type, test)
+
+* **@param** _{String}_ type 
+* **@param** _{RegExp|Function}_ test 
+
+Add a test to for the `.test()` assertion.
+
+Can be defined as a regular expression:
+
+```js
+lib.define('int', /^[0-9]+$/);
+```
+
+... or as a function:
+
+```js
+lib.define('bln', function (obj) {
+  if ('boolean' === lib.of(obj)) return true;
+  var blns = [ 'yes', 'no', 'true', 'false', 1, 0 ];
+  if ('string' === lib.of(obj)) obj = obj.toLowerCase();
+  return !! ~blns.indexOf(obj);
+});
+```
+
+
+#### .test (obj, test)
+
+* **@param** _{Mixed}_ object 
+* **@param** _{String}_ type 
+* **@return** _{Boolean}_  result
+
+Assert that an object is of type. Will first
+check natives, and if that does not pass it will
+use the user defined custom tests.
+
+```js
+assert(lib.test('1', 'int'));
+assert(lib.test('yes', 'bln'));
+```
+
+
+
+
 ## License
 
 (The MIT License)
diff --git a/lib/type.js b/lib/type.js
index 5235813..7098140 100644
--- a/lib/type.js
+++ b/lib/type.js
@@ -23,10 +23,11 @@ var natives = {
 };
 
 /**
+ * ### typeOf (obj)
+ *
  * Use several different techniques to determine
- * the type of object being passed.
+ * the type of object being tested.
  *
- * Provided as primary export.
  *
  * @param {Mixed} object
  * @return {String} object type
@@ -62,7 +63,7 @@ function Library () {
 /**
  * #### .of (obj)
  *
- * Expose native type detection to a library.
+ * Expose replacement `typeof` detection to the library.
  *
  * ```js
  * if ('string' === lib.of('hello world')) {
@@ -77,7 +78,26 @@ function Library () {
 Library.prototype.of = getType;
 
 /**
- * Add a test to for the `.is()` assertion.
+ * #### .define (type, test)
+ *
+ * Add a test to for the `.test()` assertion.
+ *
+ * Can be defined as a regular expression:
+ *
+ * ```js
+ * lib.define('int', /^[0-9]+$/);
+ * ```
+ *
+ * ... or as a function:
+ *
+ * ```js
+ * lib.define('bln', function (obj) {
+ *   if ('boolean' === lib.of(obj)) return true;
+ *   var blns = [ 'yes', 'no', 'true', 'false', 1, 0 ];
+ *   if ('string' === lib.of(obj)) obj = obj.toLowerCase();
+ *   return !! ~blns.indexOf(obj);
+ * });
+ * ```
  *
  * @param {String} type
  * @param {RegExp|Function} test
@@ -91,10 +111,17 @@ Library.prototype.define = function (type, test) {
 };
 
 /**
+ * #### .test (obj, test)
+ *
  * Assert that an object is of type. Will first
  * check natives, and if that does not pass it will
  * use the user defined custom tests.
  *
+ * ```js
+ * assert(lib.test('1', 'int'));
+ * assert(lib.test('yes', 'bln'));
+ * ```
+ *
  * @param {Mixed} object
  * @param {String} type
  * @return {Boolean} result