readme: document all methods

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)

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