comments / docs updates

lib/assertion.js

@@ -151,6 +151,11 @@ Object.defineProperty(Assertion.prototype, '_obj',
  *
  * Negates any of assertions following in the chain.
  *
+ *    expect(foo).to.not.equal('bar');
+ *    expect(goodFn).to.not.throw(Error);
+ *    expect({ foo: 'baz' }).to.have.property('foo')
+ *      .and.not.equal('bar');
+ *
  * @name not
  * @api public
  */
@@ -166,9 +171,15 @@ Object.defineProperty(Assertion.prototype, 'not',
 /**
  * ### .a(type)
  *
- * Assert typeof. Also can be used as a language chain.
+ * The `a` and `an` assertions are aliases that can be
+ * used either as property languague chains or to assert
+ * typeof.
  *
+ *     // typeof
  *     expect('test').to.be.a('string');
+ *     expect({ foo: 'bar' }).to.be.an('object');
+ *
+ *     // language chain
  *     expect(foo).to.be.an.instanceof(Foo);
  *
  * @name a
@@ -210,8 +221,10 @@ Object.defineProperty(Assertion.prototype, 'a',
 /**
  * ### .include(value)
  *
- * Assert the inclusion of an object in an Array or substring in string.
+ * The `include` and `contain` assertions can be used as either a property
- * Also toggles the `contain` flag for the `keys` assertion if used as property.
+ * based language chain or as a method to assert the inclusion of an object
+ * in an Array or substring in string. When used as a property langugae chain,
+ * it toggles the `contain` flag for the `keys` assertion.
  *
  *     expect([1,2,3]).to.include(2);
  *     expect('foobar').to.contain('foo');
@@ -256,6 +269,7 @@ Object.defineProperty(Assertion.prototype, 'include',
  * Assert object truthiness.
  *
  *     expect('everthing').to.be.ok;
+ *     expect(1).to.be.ok;
  *     expect(false).to.not.be.ok;
  *     expect(undefined).to.not.be.ok;
  *     expect(null).to.not.be.ok;
@@ -281,6 +295,9 @@ Object.defineProperty(Assertion.prototype, 'ok',
  *
  * Assert object is true
  *
+ *     expect(true).to.be.true;
+ *     expect(1).to.not.be.true;
+ *
  * @name true
  * @api public
  */
@@ -304,6 +321,9 @@ Object.defineProperty(Assertion.prototype, 'true',
  *
  * Assert object is false
  *
+ *     expect(false).to.be.false;
+ *     expect(0).to.not.be.false;
+ *
  * @name false
  * @api public
  */
@@ -327,6 +347,9 @@ Object.defineProperty(Assertion.prototype, 'false',
  *
  * Assert object is null
  *
+ *     expect(null).to.be.null;
+ *     expect(undefined).not.to.be.null;
+ *
  * @name null
  * @api public
  */
@@ -350,6 +373,9 @@ Object.defineProperty(Assertion.prototype, 'null',
  *
  * Assert object is undefined
  *
+ *      expect(undefined).to.be.undefined;
+ *      expect(null).to.not.be.undefined;
+ *
  * @name undefined
  * @api public
  */
@@ -375,6 +401,7 @@ Object.defineProperty(Assertion.prototype, 'undefined',
  *
  *     var foo = 'hi'
  *       , bar;
+ *
  *     expect(foo).to.exist;
  *     expect(bar).to.not.exist;
  *
@@ -398,9 +425,13 @@ Object.defineProperty(Assertion.prototype, 'exist',
 /**
  * ### .empty
  *
- * Assert object's length to be 0.
+ * Assert object's length to be `0`. For arrays, it check
+ * the length property. For objects it gets the count of
+ * enumerable keys.
  *
  *     expect([]).to.be.empty;
+ *     expect('').to.be.empty;
+ *     expect({}).to.be.empty;
  *
  * @name empty
  * @api public
@@ -411,7 +442,7 @@ Object.defineProperty(Assertion.prototype, 'empty',
       var obj = flag(this, 'object')
         , expected = obj;
 
-      if (Array.isArray(obj)) {
+      if (Array.isArray(obj) || 'string' === typeof object) {
         expected = obj.length;
       } else if (typeof obj === 'object') {
         expected = Object.keys(obj).length;
@@ -459,9 +490,11 @@ Object.defineProperty(Assertion.prototype, 'arguments',
 /**
  * ### .equal(value)
  *
- * Assert strict equality.
+ * Assert strict equality (===).
  *
  *     expect('hello').to.equal('hello');
+ *     expect(42).to.equal(42);
+ *     expect(1).to.not.equal(true);
  *
  * @name equal
  * @param {Mixed} value
@@ -484,6 +517,7 @@ Assertion.prototype.equal = function (val) {
  * Assert deep equality.
  *
  *     expect({ foo: 'bar' }).to.eql({ foo: 'bar' });
+ *     expect([ 1, 2, 3 ]).to.eql([ 1, 2, 3 ]);
  *
  * @name eql
  * @param {*} value
@@ -578,6 +612,7 @@ Assertion.prototype.within = function (start, finish) {
  *       , Chai = new Tea('chai');
  *
  *     expect(Chai).to.be.an.instanceof(Tea);
+ *     expect([ 1, 2, 3 ]).to.be.instanceof(Array);
  *
  * @name instanceof
  * @param {Constructor}
@@ -599,12 +634,24 @@ Assertion.prototype.instanceOf = function (constructor) {
  * ### .property(name, [value])
  *
  * Assert that property of `name` exists, optionally with `value`.
+ * Can use dot-notation for deep reference.
  *
+ *     // legacy / simple referencing
  *     var obj = { foo: 'bar' }
  *     expect(obj).to.have.property('foo');
  *     expect(obj).to.have.property('foo', 'bar');
  *     expect(obj).to.have.property('foo').to.be.a('string');
  *
+ *     // deep referencing
+ *     var deepObj = {
+ *         green: { tea: 'matcha' }
+ *       , teas: [ 'chai', 'matcha', { tea: 'konacha' } ]
+ *     };
+
+ *     expect(deepObj).to.have.property('green.tea', 'matcha');
+ *     expect(deepObj).to.have.property('teas[1]', 'matcha');
+ *     expect(deepObj).to.have.property('teas[2].tea', 'konacha');
+ *
  * @name property
  * @param {String} name
  * @param {Mixed} value (optional)
@@ -744,7 +791,8 @@ Assertion.prototype.string = function (str) {
 /**
  * ### .keys(key1, [key2], [...])
  *
- * Assert exact keys or the inclusing of keys using the `contain` modifier.
+ * Assert exact keys or the inclusing of keys
+ * using the `include` or `contain` modifier.
  *
  *     expect({ foo: 1, bar: 2 }).to.have.keys(['foo', 'bar']);
  *     expect({ foo: 1, bar: 2, baz: 3 }).to.contain.keys('foo', 'bar');
@@ -830,7 +878,8 @@ Assertion.prototype.keys = function(keys) {
  * to check for the existence of a type of error but for a message that does not match
  * is to use `and`.
  *
- *      expect(fn).to.throw(ReferenceError).and.not.throw(/good function/);
+ *     expect(fn).to.throw(ReferenceError)
+ *        .and.not.throw(/good function/);
  *
  * @name throw
  * @alias throws