Assert: made documentation more descriptive

chaijs · May 7, 2017 · b744130 · b744130
1 parent 33e4403
commit b744130
Showing 1 changed file with 48 additions and 40 deletions.
diff --git a/lib/chai/interface/assert.js b/lib/chai/interface/assert.js
@@ -1013,9 +1013,11 @@ module.exports = function (chai, util) {
   };
 
   /**
-   * ### .nestedInclude(object1, object2, [message])
+   * ### .nestedInclude(haystack, needle, [message])
    * 
-   * Asserts that 'object1' includes 'object2'. 
+   * Asserts that 'haystack' includes 'needle'. 
+   * Can be used to assert the inclusion of a subset of properties in an 
+   * object.
    * Enables the use of dot- and bracket-notation for referencing nested 
    * properties.
    * '[]' and '.' in property names can be escaped using double backslashes.
@@ -1024,8 +1026,8 @@ module.exports = function (chai, util) {
    *     assert.nestedInclude({'a': {'[b]': 'x'}}, {'a.\\[b\\]': 'x'});
    * 
    * @name nestedInclude
-   * @param {Object} object1
-   * @param {Object} object2
+   * @param {Object} haystack
+   * @param {Object} needle
    * @param {String} message
    * @namespace Assert
    * @api public 
@@ -1036,9 +1038,11 @@ module.exports = function (chai, util) {
   };
 
   /**
-   * ### .notNestedInclude(object1, object2, [message])
+   * ### .notNestedInclude(haystack, needle, [message])
    * 
-   * Asserts that 'object1' does not include 'object2'. 
+   * Asserts that 'haystack' does not include 'needle'. 
+   * Can be used to assert the absence of a subset of properties in an 
+   * object.
    * Enables the use of dot- and bracket-notation for referencing nested 
    * properties. 
    * '[]' and '.' in property names can be escaped using double backslashes.
@@ -1047,8 +1051,8 @@ module.exports = function (chai, util) {
    *     assert.notNestedInclude({'a': {'[b]': 'x'}}, {'a.\\[b\\]': 'y'});
    * 
    * @name notNestedInclude
-   * @param {Object} object1
-   * @param {Object} object2
+   * @param {Object} haystack
+   * @param {Object} needle
    * @param {String} message
    * @namespace Assert
    * @api public 
@@ -1060,10 +1064,11 @@ module.exports = function (chai, util) {
   };
 
   /**
-   * ### .deepNestedInclude(object1, object2, [message])
+   * ### .deepNestedInclude(haystack, needle, [message])
    * 
-   * Asserts that 'object1' includes 'object2' while checking for 
-   * deep equality.
+   * Asserts that 'haystack' includes 'needle'.
+   * Can be used to assert the inclusion of a subset of properties in an 
+   * object while checking for deep equality.
    * Enables the use of dot- and bracket-notation for referencing nested 
    * properties.
    * '[]' and '.' in property names can be escaped using double backslashes.
@@ -1072,8 +1077,8 @@ module.exports = function (chai, util) {
    *     assert.deepNestedInclude({'.a': {'[b]': {x: 1}}}, {'\\.a.\\[b\\]': {x: 1}});
    *    
    * @name deepNestedInclude
-   * @param {Object} object1
-   * @param {Object} object2
+   * @param {Object} haystack
+   * @param {Object} needle
    * @param {String} message
    * @namespace Assert
    * @api public 
@@ -1085,10 +1090,11 @@ module.exports = function (chai, util) {
   };
 
   /**
-   * ### .notDeepNestedInclude(object1, object2, [message])
+   * ### .notDeepNestedInclude(haystack, needle, [message])
    * 
-   * Asserts that 'object1' does not include 'object2' while 
-   * checking for deep equality.
+   * Asserts that 'haystack' does not include 'needle'.
+   * Can be used to assert the absence of a subset of properties in an 
+   * object while checking for deep equality.
    * Enables the use of dot- and bracket-notation for referencing nested 
    * properties.
    * '[]' and '.' in property names can be escaped using double backslashes.
@@ -1097,8 +1103,8 @@ module.exports = function (chai, util) {
    *     assert.notDeepNestedInclude({'.a': {'[b]': {x: 1}}}, {'\\.a.\\[b\\]': {y: 2}});
    *    
    * @name notDeepNestedInclude
-   * @param {Object} object1
-   * @param {Object} object2
+   * @param {Object} haystack
+   * @param {Object} needle
    * @param {String} message
    * @namespace Assert
    * @api public 
@@ -1110,16 +1116,17 @@ module.exports = function (chai, util) {
   };
 
   /**
-   * ### .ownInclude(object1, object2, [message])
+   * ### .ownInclude(haystack, needle, [message])
    * 
-   * Asserts that 'object1' includes 'object2' while 
-   * ignoring inherited properties.
+   * Asserts that 'haystack' includes 'needle'.
+   * Can be used to assert the inclusion of a subset of properties in an 
+   * object while ignoring inherited properties.
    * 
    *     assert.ownInclude({ a: 1 }, { a: 1 });
    * 
    * @name ownInclude
-   * @param {Object} object1
-   * @param {Object} object2
+   * @param {Object} haystack
+   * @param {Object} needle
    * @param {String} message
    * @namespace Assert
    * @api public
@@ -1130,18 +1137,19 @@ module.exports = function (chai, util) {
   };
 
   /**
-   * ### .notOwnInclude(object1, object2, [message])
+   * ### .notOwnInclude(haystack, needle, [message])
    * 
-   * Asserts that 'object1' does not include 'object2' while 
-   * ignoring inherited properties.
+   * Asserts that 'haystack' includes 'needle'.
+   * Can be used to assert the absence of a subset of properties in an 
+   * object while ignoring inherited properties.
    * 
    *     Object.prototype.b = 2;
    * 
    *     assert.notOwnInclude({ a: 1 }, { b: 2 });
    * 
    * @name notOwnInclude
-   * @param {Object} object1
-   * @param {Object} object2
+   * @param {Object} haystack
+   * @param {Object} needle
    * @param {String} message
    * @namespace Assert
    * @api public
@@ -1152,17 +1160,17 @@ module.exports = function (chai, util) {
   };
 
   /**
-   * ### .deepOwnInclude(object1, object2, [message])
+   * ### .deepOwnInclude(haystack, needle, [message])
    * 
-   * Asserts that 'object1' includes 'object2' while 
-   * ignoring inherited properties.
-   * Deep equality is used.
+   * Asserts that 'haystack' includes 'needle'.
+   * Can be used to assert the inclusion of a subset of properties in an 
+   * object while ignoring inherited properties and checking for deep equality.
    * 
    *      assert.deepOwnInclude({a: {b: 2}}, {a: {b: 2}});
    *      
    * @name deepOwnInclude
-   * @param {Object} object1
-   * @param {Object} object2
+   * @param {Object} haystack
+   * @param {Object} needle
    * @param {String} message
    * @namespace Assert
    * @api public
@@ -1174,17 +1182,17 @@ module.exports = function (chai, util) {
   };
 
    /**
-   * ### .notDeepOwnInclude(object1, object2, [message])
+   * ### .notDeepOwnInclude(haystack, needle, [message])
    * 
-   * Asserts that 'object1' does not include 'object2' while 
-   * ignoring inherited properties.
-   * Deep equality is used.
+   * Asserts that 'haystack' includes 'needle'.
+   * Can be used to assert the absence of a subset of properties in an 
+   * object while ignoring inherited properties and checking for deep equality.
    * 
    *      assert.notDeepOwnInclude({a: {b: 2}}, {a: {c: 3}});
    *      
    * @name notDeepOwnInclude
-   * @param {Object} object1
-   * @param {Object} object2
+   * @param {Object} haystack
+   * @param {Object} needle
    * @param {String} message
    * @namespace Assert
    * @api public