comment updates for docs

This commit is contained in:
Jake Luer 2012-05-09 12:11:36 -04:00
parent 4f9c813f3f
commit 8cec45ac8a
2 changed files with 85 additions and 142 deletions

View file

@ -1,45 +1,10 @@
/*!
* chai
* http://chaijs.com
* Copyright(c) 2011-2012 Jake Luer <jake@alogicalparadox.com>
* MIT Licensed
*
* Primarily a refactor of: should.js
* https://github.com/visionmedia/should.js
* Copyright(c) 2011 TJ Holowaychuk <tj@vision-media.ca>
* MIT Licensed
*/
/**
* ### BDD Style Introduction
*
* The BDD style is exposed through `expect` or `should` interfaces. In both
* scenarios, you chain together natural language assertions.
*
* // expect
* var expect = require('chai').expect;
* expect(foo).to.equal('bar');
*
* // should
* var should = require('chai').should();
* foo.should.equal('bar');
*
* #### Differences
*
* The `expect` interface provides a function as a starting point for chaining
* your language assertions. It works on node.js and in all browsers.
*
* The `should` interface extends `Object.prototype` to provide a single getter as
* the starting point for your language assertions. It works on node.js and in
* all browsers except Internet Explorer.
*
* #### Configuration
*
* By default, Chai does not show stack traces upon an AssertionError. This can
* be changed by modifying the `includeStack` parameter for chai.Assertion. For example:
*
* var chai = require('chai');
* chai.Assertion.includeStack = true; // defaults to false
*/
/*!
* Module dependencies.
@ -58,7 +23,7 @@ module.exports = Assertion;
/*!
* # Assertion Constructor
* Assertion Constructor
*
* Creates object for chaining.
*
@ -72,7 +37,7 @@ function Assertion (obj, msg, stack) {
}
/*!
* ## Assertion.includeStack
* ### Assertion.includeStack
*
* User configurable property, influences whether stack trace
* is included in Assertion error message. Default of false
@ -86,7 +51,7 @@ function Assertion (obj, msg, stack) {
Assertion.includeStack = false;
/*!
* # .assert(expression, message, negateMessage, expected, actual)
* ### .assert(expression, message, negateMessage, expected, actual)
*
* Executes an expression and check expectations. Throws AssertionError for reporting if test doesn't pass.
*
@ -116,7 +81,7 @@ Assertion.prototype.assert = function (expr, msg, negateMsg, expected, _actual)
/*!
*
* # ._obj
* ### ._obj
*
* Quick reference to stored `actual` value for plugin developers.
*
@ -133,7 +98,7 @@ Object.defineProperty(Assertion.prototype, '_obj',
});
/**
* # to
* ### .to
*
* Language chain.
*
@ -149,7 +114,7 @@ Object.defineProperty(Assertion.prototype, 'to',
});
/**
* # be
* ### .be
*
* Language chain.
*
@ -165,7 +130,7 @@ Object.defineProperty(Assertion.prototype, 'be',
});
/**
* # been
* ### .been
*
* Language chain. Also tests `tense` to past for addon
* modules that use the tense feature.
@ -183,7 +148,7 @@ Object.defineProperty(Assertion.prototype, 'been',
});
/**
* # .a(type)
* ### .a(type)
*
* Assert typeof. Also can be used as a language chain.
*
@ -227,7 +192,7 @@ Object.defineProperty(Assertion.prototype, 'a',
});
/**
* # .include(value)
* ### .include(value)
*
* Assert the inclusion of an object in an Array or substring in string.
* Also toggles the `contain` flag for the `keys` assertion if used as property.
@ -239,6 +204,7 @@ Object.defineProperty(Assertion.prototype, 'a',
* @param {Object|String|Number} obj
* @api public
*/
var include = function () {
flag(this, 'contains', true);
@ -268,7 +234,7 @@ Object.defineProperty(Assertion.prototype, 'include',
/**
* # is
* ### .is
*
* Language chain.
*
@ -284,7 +250,7 @@ Object.defineProperty(Assertion.prototype, 'is',
});
/**
* # and
* ### .and
*
* Language chain.
*
@ -300,7 +266,7 @@ Object.defineProperty(Assertion.prototype, 'and',
});
/**
* # have
* ### .have
*
* Language chain.
*
@ -316,7 +282,7 @@ Object.defineProperty(Assertion.prototype, 'have',
});
/**
* # with
* ### .with
*
* Language chain.
*
@ -332,7 +298,7 @@ Object.defineProperty(Assertion.prototype, 'with',
});
/**
* # .not
* ### .not
*
* Negates any of assertions following in the chain.
*
@ -349,7 +315,7 @@ Object.defineProperty(Assertion.prototype, 'not',
});
/**
* # .ok
* ### .ok
*
* Assert object truthiness.
*
@ -375,7 +341,7 @@ Object.defineProperty(Assertion.prototype, 'ok',
});
/**
* # .true
* ### .true
*
* Assert object is true
*
@ -398,7 +364,7 @@ Object.defineProperty(Assertion.prototype, 'true',
});
/**
* # .false
* ### .false
*
* Assert object is false
*
@ -421,7 +387,7 @@ Object.defineProperty(Assertion.prototype, 'false',
});
/**
* # .null
* ### .null
*
* Assert object is null
*
@ -444,7 +410,7 @@ Object.defineProperty(Assertion.prototype, 'null',
});
/**
* # .undefined
* ### .undefined
*
* Assert object is undefined
*
@ -467,7 +433,7 @@ Object.defineProperty(Assertion.prototype, 'undefined',
});
/**
* # .exist
* ### .exist
*
* Assert object exists (null).
*
@ -494,7 +460,7 @@ Object.defineProperty(Assertion.prototype, 'exist',
});
/**
* # .empty
* ### .empty
*
* Assert object's length to be 0.
*
@ -526,7 +492,7 @@ Object.defineProperty(Assertion.prototype, 'empty',
});
/**
* # .arguments
* ### .arguments
*
* Assert object is an instanceof arguments.
*
@ -555,14 +521,14 @@ Object.defineProperty(Assertion.prototype, 'arguments',
});
/**
* # .equal(value)
* ### .equal(value)
*
* Assert strict equality.
*
* expect('hello').to.equal('hello');
*
* @name equal
* @param {*} value
* @param {Mixed} value
* @api public
*/
@ -577,7 +543,7 @@ Assertion.prototype.equal = function (val) {
};
/**
* # .eql(value)
* ### .eql(value)
*
* Assert deep equality.
*
@ -599,14 +565,14 @@ Assertion.prototype.eql = function (obj) {
};
/**
* # .above(value)
* ### .above(value)
*
* Assert greater than `value`.
*
* expect(10).to.be.above(5);
*
* @name above
* @alias mt
* @alias gt
* @param {Number} value
* @api public
*/
@ -621,7 +587,7 @@ Assertion.prototype.above = function (val) {
};
/**
* # .below(value)
* ### .below(value)
*
* Assert less than `value`.
*
@ -643,7 +609,7 @@ Assertion.prototype.below = function (val) {
};
/**
* # .within(start, finish)
* ### .within(start, finish)
*
* Assert that a number is within a range.
*
@ -668,7 +634,7 @@ Assertion.prototype.within = function (start, finish) {
};
/**
* # .instanceof(constructor)
* ### .instanceof(constructor)
*
* Assert instanceof.
*
@ -694,7 +660,7 @@ Assertion.prototype.instanceOf = function (constructor) {
};
/**
* # .property(name, [value])
* ### .property(name, [value])
*
* Assert that property of `name` exists, optionally with `value`.
*
@ -705,7 +671,7 @@ Assertion.prototype.instanceOf = function (constructor) {
*
* @name property
* @param {String} name
* @param {*} value (optional)
* @param {Mixed} value (optional)
* @returns value of property for chaining
* @api public
*/
@ -741,7 +707,7 @@ Assertion.prototype.property = function (name, val) {
};
/**
* # .ownProperty(name)
* ### .ownProperty(name)
*
* Assert that has own property by `name`.
*
@ -763,7 +729,7 @@ Assertion.prototype.ownProperty = function (name) {
};
/**
* # .length(val)
* ### .length(val)
*
* Assert that object has expected length.
*
@ -793,7 +759,7 @@ Assertion.prototype.length = function (n) {
};
/**
* # .match(regexp)
* ### .match(regexp)
*
* Assert that matches regular expression.
*
@ -816,7 +782,7 @@ Assertion.prototype.match = function (re) {
/**
* # .string(string)
* ### .string(string)
*
* Assert inclusion of string in string.
*
@ -840,7 +806,7 @@ Assertion.prototype.string = function (str) {
};
/**
* # .keys(key1, [key2], [...])
* ### .keys(key1, [key2], [...])
*
* Assert exact keys or the inclusing of keys using the `contain` modifier.
*
@ -907,7 +873,7 @@ Assertion.prototype.keys = function(keys) {
}
/**
* # .throw(constructor)
* ### .throw(constructor)
*
* Assert that a function will throw a specific type of error, or specific type of error
* (as determined using `instanceof`), optionally with a RegExp or string inclusion test
@ -1015,7 +981,7 @@ Assertion.prototype.Throw = function (constructor, msg) {
};
/**
* # .respondTo(method)
* ### .respondTo(method)
*
* Assert that object/class will respond to a method.
*
@ -1045,7 +1011,7 @@ Assertion.prototype.respondTo = function (method) {
};
/**
* # .satisfy(method)
* ### .satisfy(method)
*
* Assert that passes a truth test.
*
@ -1070,7 +1036,7 @@ Assertion.prototype.satisfy = function (matcher) {
};
/**
* # .closeTo(expected, delta)
* ### .closeTo(expected, delta)
*
* Assert that actual is equal to +/- delta.
*
@ -1101,7 +1067,7 @@ Assertion.prototype.closeTo = function (expected, delta) {
return alias;
})
('equal', 'eq')
('above', 'mt')
('above', 'gt')
('below', 'lt')
('length', 'lengthOf')
('keys', 'key')

View file

@ -4,29 +4,6 @@
* MIT Licensed
*/
/**
* ### TDD Style Introduction
*
* The TDD style is exposed through `assert` interfaces. This provides
* the classic assert.`test` notation, similiar to that packaged with
* node.js. This assert module, however, provides several additional
* tests and is browser compatible.
*
* // assert
* var assert = require('chai').assert;
* , foo = 'bar';
*
* assert.typeOf(foo, 'string');
* assert.equal(foo, 'bar');
*
* #### Configuration
*
* By default, Chai does not show stack traces upon an AssertionError. This can
* be changed by modifying the `includeStack` parameter for chai.Assertion. For example:
*
* var chai = require('chai');
* chai.Assertion.includeStack = true; // defaults to false
*/
module.exports = function (chai, util) {
@ -44,7 +21,7 @@ module.exports = function (chai, util) {
var assert = chai.assert = {};
/**
* # .fail(actual, expect, msg, operator)
* ### .fail(actual, expect, msg, operator)
*
* Throw a failure. Node.js compatible.
*
@ -67,7 +44,7 @@ module.exports = function (chai, util) {
}
/**
* # .ok(object, [message])
* ### .ok(object, [message])
*
* Assert object is truthy.
*
@ -85,7 +62,7 @@ module.exports = function (chai, util) {
};
/**
* # .equal(actual, expected, [message])
* ### .equal(actual, expected, [message])
*
* Assert strict equality.
*
@ -111,7 +88,7 @@ module.exports = function (chai, util) {
};
/**
* # .notEqual(actual, expected, [message])
* ### .notEqual(actual, expected, [message])
*
* Assert not equal.
*
@ -137,7 +114,7 @@ module.exports = function (chai, util) {
};
/**
* # .strictEqual(actual, expected, [message])
* ### .strictEqual(actual, expected, [message])
*
* Assert strict equality.
*
@ -155,7 +132,7 @@ module.exports = function (chai, util) {
};
/**
* # .notStrictEqual(actual, expected, [message])
* ### .notStrictEqual(actual, expected, [message])
*
* Assert strict equality.
*
@ -173,7 +150,7 @@ module.exports = function (chai, util) {
};
/**
* # .deepEqual(actual, expected, [message])
* ### .deepEqual(actual, expected, [message])
*
* Assert not deep equality.
*
@ -191,7 +168,7 @@ module.exports = function (chai, util) {
};
/**
* # .notDeepEqual(actual, expected, [message])
* ### .notDeepEqual(actual, expected, [message])
*
* Assert not deep equality.
*
@ -209,7 +186,7 @@ module.exports = function (chai, util) {
};
/**
* # .isTrue(value, [message])
* ### .isTrue(value, [message])
*
* Assert `value` is true.
*
@ -227,7 +204,7 @@ module.exports = function (chai, util) {
};
/**
* # .isFalse(value, [message])
* ### .isFalse(value, [message])
*
* Assert `value` is false.
*
@ -245,7 +222,7 @@ module.exports = function (chai, util) {
};
/**
* # .isNull(value, [message])
* ### .isNull(value, [message])
*
* Assert `value` is null.
*
@ -262,7 +239,7 @@ module.exports = function (chai, util) {
};
/**
* # .isNotNull(value, [message])
* ### .isNotNull(value, [message])
*
* Assert `value` is not null.
*
@ -280,7 +257,7 @@ module.exports = function (chai, util) {
};
/**
* # .isUndefined(value, [message])
* ### .isUndefined(value, [message])
*
* Assert `value` is undefined.
*
@ -297,7 +274,7 @@ module.exports = function (chai, util) {
};
/**
* # .isDefined(value, [message])
* ### .isDefined(value, [message])
*
* Assert `value` is not undefined.
*
@ -315,7 +292,7 @@ module.exports = function (chai, util) {
};
/**
* # .isFunction(value, [message])
* ### .isFunction(value, [message])
*
* Assert `value` is a function.
*
@ -333,7 +310,7 @@ module.exports = function (chai, util) {
};
/**
* # .isNotFunction(value, [message])
* ### .isNotFunction(value, [message])
*
* Assert `value` is NOT a function.
*
@ -351,7 +328,7 @@ module.exports = function (chai, util) {
};
/**
* # .isObject(value, [message])
* ### .isObject(value, [message])
*
* Assert `value` is an object.
*
@ -369,7 +346,7 @@ module.exports = function (chai, util) {
};
/**
* # .isNotObject(value, [message])
* ### .isNotObject(value, [message])
*
* Assert `value` is NOT an object.
*
@ -387,7 +364,7 @@ module.exports = function (chai, util) {
};
/**
* # .isArray(value, [message])
* ### .isArray(value, [message])
*
* Assert `value` is an instance of Array.
*
@ -405,7 +382,7 @@ module.exports = function (chai, util) {
};
/**
* # .isArray(value, [message])
* ### .isArray(value, [message])
*
* Assert `value` is NOT an instance of Array.
*
@ -423,7 +400,7 @@ module.exports = function (chai, util) {
};
/**
* # .isString(value, [message])
* ### .isString(value, [message])
*
* Assert `value` is a string.
*
@ -441,7 +418,7 @@ module.exports = function (chai, util) {
};
/**
* # .isNotString(value, [message])
* ### .isNotString(value, [message])
*
* Assert `value` is NOT a string.
*
@ -459,7 +436,7 @@ module.exports = function (chai, util) {
};
/**
* # .isNumber(value, [message])
* ### .isNumber(value, [message])
*
* Assert `value` is a number
*
@ -477,7 +454,7 @@ module.exports = function (chai, util) {
};
/**
* # .isNotNumber(value, [message])
* ### .isNotNumber(value, [message])
*
* Assert `value` NOT is a number
*
@ -495,7 +472,7 @@ module.exports = function (chai, util) {
};
/**
* # .isBoolean(value, [message])
* ### .isBoolean(value, [message])
*
* Assert `value` is a boolean
*
@ -516,7 +493,7 @@ module.exports = function (chai, util) {
};
/**
* # .isNotBoolean(value, [message])
* ### .isNotBoolean(value, [message])
*
* Assert `value` is NOT a boolean
*
@ -537,7 +514,7 @@ module.exports = function (chai, util) {
};
/**
* # .typeOf(value, name, [message])
* ### .typeOf(value, name, [message])
*
* Assert typeof `value` is `name`.
*
@ -555,7 +532,7 @@ module.exports = function (chai, util) {
};
/**
* # .notTypeOf(value, name, [message])
* ### .notTypeOf(value, name, [message])
*
* Assert typeof `value` is NOT `name`.
*
@ -573,7 +550,7 @@ module.exports = function (chai, util) {
};
/**
* # .instanceOf(object, constructor, [message])
* ### .instanceOf(object, constructor, [message])
*
* Assert `value` is instanceof `constructor`.
*
@ -594,7 +571,7 @@ module.exports = function (chai, util) {
};
/**
* # .notInstanceOf(object, constructor, [message])
* ### .notInstanceOf(object, constructor, [message])
*
* Assert `value` is NOT instanceof `constructor`.
*
@ -615,7 +592,7 @@ module.exports = function (chai, util) {
};
/**
* # .include(value, includes, [message])
* ### .include(value, includes, [message])
*
* Assert the inclusion of an object in another. Works
* for strings and arrays.
@ -641,7 +618,7 @@ module.exports = function (chai, util) {
};
/**
* # .match(value, regex, [message])
* ### .match(value, regex, [message])
*
* Assert that `value` matches regular expression.
*
@ -659,7 +636,7 @@ module.exports = function (chai, util) {
};
/**
* # .notMatch(value, regex, [message])
* ### .notMatch(value, regex, [message])
*
* Assert that `value` does not match regular expression.
*
@ -677,7 +654,7 @@ module.exports = function (chai, util) {
};
/**
* # .ownProperty(object, property, [message])
* ### .ownProperty(object, property, [message])
*
* Assert that `object` has property. Can use dot-notation for deep reference.
*
@ -695,7 +672,7 @@ module.exports = function (chai, util) {
};
/**
* # .notOwnProperty(object, property, [message])
* ### .notOwnProperty(object, property, [message])
*
* Assert that `object` does not have property. Can use dot-notation for deep reference.
*
@ -713,7 +690,7 @@ module.exports = function (chai, util) {
};
/**
* # .ownPropertyVal(object, property, value, [message])
* ### .ownPropertyVal(object, property, value, [message])
*
* Assert that `object` has property with `value`.
* Can use dot-notation for deep reference.
@ -733,7 +710,7 @@ module.exports = function (chai, util) {
};
/**
* # .ownPropertyNotVal(object, property, value, [message])
* ### .ownPropertyNotVal(object, property, value, [message])
*
* Assert that `object` has property but `value`
* does not equal `value`. Can use dot-notation for deep reference.
@ -752,7 +729,7 @@ module.exports = function (chai, util) {
};
/**
* # .length(object, length, [message])
* ### .length(object, length, [message])
*
* Assert that object has expected length.
*
@ -771,7 +748,7 @@ module.exports = function (chai, util) {
};
/**
* # .throws(function, [constructor/regexp], [message])
* ### .throws(function, [constructor/regexp], [message])
*
* Assert that a function will throw a specific
* type of error.
@ -797,7 +774,7 @@ module.exports = function (chai, util) {
};
/**
* # .doesNotThrow(function, [constructor/regexp], [message])
* ### .doesNotThrow(function, [constructor/regexp], [message])
*
* Assert that a function will throw a specific
* type of error.
@ -823,7 +800,7 @@ module.exports = function (chai, util) {
};
/**
* # .operator(val, operator, val2, [message])
* ### .operator(val, operator, val2, [message])
*
* Compare two values using operator.
*