Bump to v3.2.0.

collection/countBy.js

@@ -13,10 +13,14 @@ var hasOwnProperty = objectProto.hasOwnProperty;
  * The `iteratee` is bound to `thisArg` and invoked with three arguments;
  * (value, index|key, collection).
  *
- * If a property name is provided for `predicate` the created "_.property"
+ * If a property name is provided for `predicate` the created `_.property`
  * style callback returns the property value of the given element.
  *
- * If an object is provided for `predicate` the created "_.matches" style
+ * If a value is also provided for `thisArg` the created `_.matchesProperty`
+ * style callback returns `true` for elements that have a matching property
+ * value, else `false`.
+ *
+ * If an object is provided for `predicate` the created `_.matches` style
  * callback returns `true` for elements that have the properties of the given
  * object, else `false`.
  *
@@ -25,8 +29,7 @@ var hasOwnProperty = objectProto.hasOwnProperty;
  * @category Collection
  * @param {Array|Object|string} collection The collection to iterate over.
  * @param {Function|Object|string} [iteratee=_.identity] The function invoked
- *  per iteration. If a property name or object is provided it is used to
- *  create a "_.property" or "_.matches" style callback respectively.
+ *  per iteration.
  * @param {*} [thisArg] The `this` binding of `iteratee`.
  * @returns {Object} Returns the composed aggregate object.
  * @example

collection/every.js

@@ -8,10 +8,14 @@ var arrayEvery = require('../internal/arrayEvery'),
  * The predicate is bound to `thisArg` and invoked with three arguments;
  * (value, index|key, collection).
  *
- * If a property name is provided for `predicate` the created "_.property"
+ * If a property name is provided for `predicate` the created `_.property`
  * style callback returns the property value of the given element.
  *
- * If an object is provided for `predicate` the created "_.matches" style
+ * If a value is also provided for `thisArg` the created `_.matchesProperty`
+ * style callback returns `true` for elements that have a matching property
+ * value, else `false`.
+ *
+ * If an object is provided for `predicate` the created `_.matches` style
  * callback returns `true` for elements that have the properties of the given
  * object, else `false`.
  *
@@ -21,27 +25,30 @@ var arrayEvery = require('../internal/arrayEvery'),
  * @category Collection
  * @param {Array|Object|string} collection The collection to iterate over.
  * @param {Function|Object|string} [predicate=_.identity] The function invoked
- *  per iteration. If a property name or object is provided it is used to
- *  create a "_.property" or "_.matches" style callback respectively.
+ *  per iteration.
  * @param {*} [thisArg] The `this` binding of `predicate`.
  * @returns {boolean} Returns `true` if all elements pass the predicate check,
  *  else `false`.
  * @example
  *
- * _.every([true, 1, null, 'yes']);
+ * _.every([true, 1, null, 'yes'], Boolean);
  * // => false
  *
  * var users = [
- *   { 'user': 'barney', 'age': 36 },
- *   { 'user': 'fred',   'age': 40 }
+ *   { 'user': 'barney', 'active': false },
+ *   { 'user': 'fred',   'active': false }
  * ];
  *
- * // using the "_.property" callback shorthand
- * _.every(users, 'age');
+ * // using the `_.matches` callback shorthand
+ * _.every(users, { 'user': 'barney', 'active': false });
+ * // => false
+ *
+ * // using the `_.matchesProperty` callback shorthand
+ * _.every(users, 'active', false);
  * // => true
  *
- * // using the "_.matches" callback shorthand
- * _.every(users, { 'age': 36 });
+ * // using the `_.property` callback shorthand
+ * _.every(users, 'active');
  * // => false
  */
 function every(collection, predicate, thisArg) {

collection/filter.js

@@ -8,10 +8,14 @@ var arrayFilter = require('../internal/arrayFilter'),
  * `predicate` returns truthy for. The predicate is bound to `thisArg` and
  * invoked with three arguments; (value, index|key, collection).
  *
- * If a property name is provided for `predicate` the created "_.property"
+ * If a property name is provided for `predicate` the created `_.property`
  * style callback returns the property value of the given element.
  *
- * If an object is provided for `predicate` the created "_.matches" style
+ * If a value is also provided for `thisArg` the created `_.matchesProperty`
+ * style callback returns `true` for elements that have a matching property
+ * value, else `false`.
+ *
+ * If an object is provided for `predicate` the created `_.matches` style
  * callback returns `true` for elements that have the properties of the given
  * object, else `false`.
  *
@@ -21,8 +25,7 @@ var arrayFilter = require('../internal/arrayFilter'),
  * @category Collection
  * @param {Array|Object|string} collection The collection to iterate over.
  * @param {Function|Object|string} [predicate=_.identity] The function invoked
- *  per iteration. If a property name or object is provided it is used to
- *  create a "_.property" or "_.matches" style callback respectively.
+ *  per iteration.
  * @param {*} [thisArg] The `this` binding of `predicate`.
  * @returns {Array} Returns the new filtered array.
  * @example
@@ -31,16 +34,20 @@ var arrayFilter = require('../internal/arrayFilter'),
  * // => [2, 4]
  *
  * var users = [
- *   { 'user': 'barney', 'age': 36, 'active': false },
- *   { 'user': 'fred',   'age': 40, 'active': true }
+ *   { 'user': 'barney', 'age': 36, 'active': true },
+ *   { 'user': 'fred',   'age': 40, 'active': false }
  * ];
  *
- * // using the "_.property" callback shorthand
- * _.pluck(_.filter(users, 'active'), 'user');
+ * // using the `_.matches` callback shorthand
+ * _.pluck(_.filter(users, { 'age': 36, 'active': true }), 'user');
+ * // => ['barney']
+ *
+ * // using the `_.matchesProperty` callback shorthand
+ * _.pluck(_.filter(users, 'active', false), 'user');
  * // => ['fred']
  *
- * // using the "_.matches" callback shorthand
- * _.pluck(_.filter(users, { 'age': 36 }), 'user');
+ * // using the `_.property` callback shorthand
+ * _.pluck(_.filter(users, 'active'), 'user');
  * // => ['barney']
  */
 function filter(collection, predicate, thisArg) {

collection/find.js

@@ -9,10 +9,14 @@ var baseCallback = require('../internal/baseCallback'),
  * `predicate` returns truthy for. The predicate is bound to `thisArg` and
  * invoked with three arguments; (value, index|key, collection).
  *
- * If a property name is provided for `predicate` the created "_.property"
+ * If a property name is provided for `predicate` the created `_.property`
  * style callback returns the property value of the given element.
  *
- * If an object is provided for `predicate` the created "_.matches" style
+ * If a value is also provided for `thisArg` the created `_.matchesProperty`
+ * style callback returns `true` for elements that have a matching property
+ * value, else `false`.
+ *
+ * If an object is provided for `predicate` the created `_.matches` style
  * callback returns `true` for elements that have the properties of the given
  * object, else `false`.
  *
@@ -22,28 +26,31 @@ var baseCallback = require('../internal/baseCallback'),
  * @category Collection
  * @param {Array|Object|string} collection The collection to search.
  * @param {Function|Object|string} [predicate=_.identity] The function invoked
- *  per iteration. If a property name or object is provided it is used to
- *  create a "_.property" or "_.matches" style callback respectively.
+ *  per iteration.
  * @param {*} [thisArg] The `this` binding of `predicate`.
  * @returns {*} Returns the matched element, else `undefined`.
  * @example
  *
  * var users = [
- *   { 'user': 'barney',  'age': 36, 'active': false },
- *   { 'user': 'fred',    'age': 40, 'active': true },
- *   { 'user': 'pebbles', 'age': 1,  'active': false }
+ *   { 'user': 'barney',  'age': 36, 'active': true },
+ *   { 'user': 'fred',    'age': 40, 'active': false },
+ *   { 'user': 'pebbles', 'age': 1,  'active': true }
  * ];
  *
  * _.result(_.find(users, function(chr) { return chr.age < 40; }), 'user');
  * // => 'barney'
  *
- * // using the "_.matches" callback shorthand
- * _.result(_.find(users, { 'age': 1 }), 'user');
+ * // using the `_.matches` callback shorthand
+ * _.result(_.find(users, { 'age': 1, 'active': true }), 'user');
  * // => 'pebbles'
  *
- * // using the "_.property" callback shorthand
- * _.result(_.find(users, 'active'), 'user');
+ * // using the `_.matchesProperty` callback shorthand
+ * _.result(_.find(users, 'active', false), 'user');
  * // => 'fred'
+ *
+ * // using the `_.property` callback shorthand
+ * _.result(_.find(users, 'active'), 'user');
+ * // => 'barney'
  */
 function find(collection, predicate, thisArg) {
   if (isArray(collection)) {

collection/findLast.js

@@ -11,8 +11,7 @@ var baseCallback = require('../internal/baseCallback'),
  * @category Collection
  * @param {Array|Object|string} collection The collection to search.
  * @param {Function|Object|string} [predicate=_.identity] The function invoked
- *  per iteration. If a property name or object is provided it is used to
- *  create a "_.property" or "_.matches" style callback respectively.
+ *  per iteration.
  * @param {*} [thisArg] The `this` binding of `predicate`.
  * @returns {*} Returns the matched element, else `undefined`.
  * @example

collection/findWhere.js

@@ -6,6 +6,11 @@ var baseMatches = require('../internal/baseMatches'),
  * source object, returning the first element that has equivalent property
  * values.
  *
+ * **Note:** This method supports comparing arrays, booleans, `Date` objects,
+ * numbers, `Object` objects, regexes, and strings. Objects are compared by
+ * their own, not inherited, enumerable properties. For comparing a single
+ * own or inherited property value see `_.matchesProperty`.
+ *
  * @static
  * @memberOf _
  * @category Collection
@@ -15,14 +20,14 @@ var baseMatches = require('../internal/baseMatches'),
  * @example
  *
  * var users = [
- *   { 'user': 'barney', 'age': 36, 'status': 'busy' },
- *   { 'user': 'fred',   'age': 40, 'status': 'busy' }
+ *   { 'user': 'barney', 'age': 36, 'active': true },
+ *   { 'user': 'fred',   'age': 40, 'active': false }
  * ];
  *
- * _.result(_.findWhere(users, { 'status': 'busy' }), 'user');
+ * _.result(_.findWhere(users, { 'age': 36, 'active': true }), 'user');
  * // => 'barney'
  *
- * _.result(_.findWhere(users, { 'age': 40 }), 'user');
+ * _.result(_.findWhere(users, { 'age': 40, 'active': false }), 'user');
  * // => 'fred'
  */
 function findWhere(collection, source) {

collection/groupBy.js

@@ -13,10 +13,14 @@ var hasOwnProperty = objectProto.hasOwnProperty;
  * The `iteratee` is bound to `thisArg` and invoked with three arguments;
  * (value, index|key, collection).
  *
- * If a property name is provided for `predicate` the created "_.property"
+ * If a property name is provided for `predicate` the created `_.property`
  * style callback returns the property value of the given element.
  *
- * If an object is provided for `predicate` the created "_.matches" style
+ * If a value is also provided for `thisArg` the created `_.matchesProperty`
+ * style callback returns `true` for elements that have a matching property
+ * value, else `false`.
+ *
+ * If an object is provided for `predicate` the created `_.matches` style
  * callback returns `true` for elements that have the properties of the given
  * object, else `false`.
  *
@@ -25,8 +29,7 @@ var hasOwnProperty = objectProto.hasOwnProperty;
  * @category Collection
  * @param {Array|Object|string} collection The collection to iterate over.
  * @param {Function|Object|string} [iteratee=_.identity] The function invoked
- *  per iteration. If a property name or object is provided it is used to
- *  create a "_.property" or "_.matches" style callback respectively.
+ *  per iteration.
  * @param {*} [thisArg] The `this` binding of `iteratee`.
  * @returns {Object} Returns the composed aggregate object.
  * @example
@@ -37,7 +40,7 @@ var hasOwnProperty = objectProto.hasOwnProperty;
  * _.groupBy([4.2, 6.1, 6.4], function(n) { return this.floor(n); }, Math);
  * // => { '4': [4.2], '6': [6.1, 6.4] }
  *
- * // using the "_.property" callback shorthand
+ * // using the `_.property` callback shorthand
  * _.groupBy(['one', 'two', 'three'], 'length');
  * // => { '3': ['one', 'two'], '5': ['three'] }
  */

collection/indexBy.js

@@ -7,10 +7,14 @@ var createAggregator = require('../internal/createAggregator');
  * iteratee function is bound to `thisArg` and invoked with three arguments;
  * (value, index|key, collection).
  *
- * If a property name is provided for `predicate` the created "_.property"
+ * If a property name is provided for `predicate` the created `_.property`
  * style callback returns the property value of the given element.
  *
- * If an object is provided for `predicate` the created "_.matches" style
+ * If a value is also provided for `thisArg` the created `_.matchesProperty`
+ * style callback returns `true` for elements that have a matching property
+ * value, else `false`.
+ *
+ * If an object is provided for `predicate` the created `_.matches` style
  * callback returns `true` for elements that have the properties of the given
  * object, else `false`.
  *
@@ -19,8 +23,7 @@ var createAggregator = require('../internal/createAggregator');
  * @category Collection
  * @param {Array|Object|string} collection The collection to iterate over.
  * @param {Function|Object|string} [iteratee=_.identity] The function invoked
- *  per iteration. If a property name or object is provided it is used to
- *  create a "_.property" or "_.matches" style callback respectively.
+ *  per iteration.
  * @param {*} [thisArg] The `this` binding of `iteratee`.
  * @returns {Object} Returns the composed aggregate object.
  * @example

collection/map.js

@@ -8,21 +8,34 @@ var arrayMap = require('../internal/arrayMap'),
  * `iteratee`. The `iteratee` is bound to `thisArg` and invoked with three
  * arguments; (value, index|key, collection).
  *
- * If a property name is provided for `predicate` the created "_.property"
+ * If a property name is provided for `predicate` the created `_.property`
  * style callback returns the property value of the given element.
  *
- * If an object is provided for `predicate` the created "_.matches" style
+ * If a value is also provided for `thisArg` the created `_.matchesProperty`
+ * style callback returns `true` for elements that have a matching property
+ * value, else `false`.
+ *
+ * If an object is provided for `predicate` the created `_.matches` style
  * callback returns `true` for elements that have the properties of the given
  * object, else `false`.
  *
+ * Many lodash methods are guarded to work as interatees for methods like
+ * `_.every`, `_.filter`, `_.map`, `_.mapValues`, `_.reject`, and `_.some`.
+ *
+ * The guarded methods are:
+ * `ary`, `callback`, `chunk`, `clone`, `create`, `curry`, `curryRight`, `drop`,
+ * `dropRight`, `fill`, `flatten`, `invert`, `max`, `min`, `parseInt`, `slice`,
+ * `sortBy`, `take`, `takeRight`, `template`, `trim`, `trimLeft`, `trimRight`,
+ * `trunc`, `random`, `range`, `sample`, `uniq`, and `words`
+ *
  * @static
  * @memberOf _
  * @alias collect
  * @category Collection
  * @param {Array|Object|string} collection The collection to iterate over.
  * @param {Function|Object|string} [iteratee=_.identity] The function invoked
- *  per iteration. If a property name or object is provided it is used to
- *  create a "_.property" or "_.matches" style callback respectively.
+ *  per iteration.
+ *  create a `_.property` or `_.matches` style callback respectively.
  * @param {*} [thisArg] The `this` binding of `iteratee`.
  * @returns {Array} Returns the new mapped array.
  * @example
@@ -38,7 +51,7 @@ var arrayMap = require('../internal/arrayMap'),
  *   { 'user': 'fred' }
  * ];
  *
- * // using the "_.property" callback shorthand
+ * // using the `_.property` callback shorthand
  * _.map(users, 'user');
  * // => ['barney', 'fred']
  */

collection/max.js

@@ -8,10 +8,14 @@ var arrayMax = require('../internal/arrayMax'),
  * is ranked. The `iteratee` is bound to `thisArg` and invoked with three
  * arguments; (value, index, collection).
  *
- * If a property name is provided for `predicate` the created "_.property"
+ * If a property name is provided for `predicate` the created `_.property`
  * style callback returns the property value of the given element.
  *
- * If an object is provided for `predicate` the created "_.matches" style
+ * If a value is also provided for `thisArg` the created `_.matchesProperty`
+ * style callback returns `true` for elements that have a matching property
+ * value, else `false`.
+ *
+ * If an object is provided for `predicate` the created `_.matches` style
  * callback returns `true` for elements that have the properties of the given
  * object, else `false`.
  *
@@ -20,8 +24,6 @@ var arrayMax = require('../internal/arrayMax'),
  * @category Collection
  * @param {Array|Object|string} collection The collection to iterate over.
  * @param {Function|Object|string} [iteratee] The function invoked per iteration.
- *  If a property name or object is provided it is used to create a "_.property"
- *  or "_.matches" style callback respectively.
  * @param {*} [thisArg] The `this` binding of `iteratee`.
  * @returns {*} Returns the maximum value.
  * @example
@@ -40,7 +42,7 @@ var arrayMax = require('../internal/arrayMax'),
  * _.max(users, function(chr) { return chr.age; });
  * // => { 'user': 'fred', 'age': 40 };
  *
- * // using the "_.property" callback shorthand
+ * // using the `_.property` callback shorthand
  * _.max(users, 'age');
  * // => { 'user': 'fred', 'age': 40 };
  */

collection/min.js

@@ -8,10 +8,14 @@ var arrayMin = require('../internal/arrayMin'),
  * is ranked. The `iteratee` is bound to `thisArg` and invoked with three
  * arguments; (value, index, collection).
  *
- * If a property name is provided for `predicate` the created "_.property"
+ * If a property name is provided for `predicate` the created `_.property`
  * style callback returns the property value of the given element.
  *
- * If an object is provided for `predicate` the created "_.matches" style
+ * If a value is also provided for `thisArg` the created `_.matchesProperty`
+ * style callback returns `true` for elements that have a matching property
+ * value, else `false`.
+ *
+ * If an object is provided for `predicate` the created `_.matches` style
  * callback returns `true` for elements that have the properties of the given
  * object, else `false`.
  *
@@ -20,8 +24,6 @@ var arrayMin = require('../internal/arrayMin'),
  * @category Collection
  * @param {Array|Object|string} collection The collection to iterate over.
  * @param {Function|Object|string} [iteratee] The function invoked per iteration.
- *  If a property name or object is provided it is used to create a "_.property"
- *  or "_.matches" style callback respectively.
  * @param {*} [thisArg] The `this` binding of `iteratee`.
  * @returns {*} Returns the minimum value.
  * @example
@@ -40,7 +42,7 @@ var arrayMin = require('../internal/arrayMin'),
  * _.min(users, function(chr) { return chr.age; });
  * // => { 'user': 'barney', 'age': 36 };
  *
- * // using the "_.property" callback shorthand
+ * // using the `_.property` callback shorthand
  * _.min(users, 'age');
  * // => { 'user': 'barney', 'age': 36 };
  */

collection/partition.js

@@ -6,10 +6,14 @@ var createAggregator = require('../internal/createAggregator');
  * contains elements `predicate` returns falsey for. The predicate is bound
  * to `thisArg` and invoked with three arguments; (value, index|key, collection).
  *
- * If a property name is provided for `predicate` the created "_.property"
+ * If a property name is provided for `predicate` the created `_.property`
  * style callback returns the property value of the given element.
  *
- * If an object is provided for `predicate` the created "_.matches" style
+ * If a value is also provided for `thisArg` the created `_.matchesProperty`
+ * style callback returns `true` for elements that have a matching property
+ * value, else `false`.
+ *
+ * If an object is provided for `predicate` the created `_.matches` style
  * callback returns `true` for elements that have the properties of the given
  * object, else `false`.
  *
@@ -18,8 +22,7 @@ var createAggregator = require('../internal/createAggregator');
  * @category Collection
  * @param {Array|Object|string} collection The collection to iterate over.
  * @param {Function|Object|string} [predicate=_.identity] The function invoked
- *  per iteration. If a property name or object is provided it is used to
- *  create a "_.property" or "_.matches" style callback respectively.
+ *  per iteration.
  * @param {*} [thisArg] The `this` binding of `predicate`.
  * @returns {Array} Returns the array of grouped elements.
  * @example
@@ -36,12 +39,18 @@ var createAggregator = require('../internal/createAggregator');
  *   { 'user': 'pebbles', 'age': 1,  'active': false }
  * ];
  *
- * // using the "_.matches" callback shorthand
- * _.map(_.partition(users, { 'age': 1 }), function(array) { return _.pluck(array, 'user'); });
+ * var mapper = function(array) { return _.pluck(array, 'user'); };
+ *
+ * // using the `_.matches` callback shorthand
+ * _.map(_.partition(users, { 'age': 1, 'active': false }), mapper);
  * // => [['pebbles'], ['barney', 'fred']]
  *
- * // using the "_.property" callback shorthand
- * _.map(_.partition(users, 'active'), function(array) { return _.pluck(array, 'user'); });
+ * // using the `_.matchesProperty` callback shorthand
+ * _.map(_.partition(users, 'active', false), mapper);
+ * // => [['barney', 'pebbles'], ['fred']]
+ *
+ * // using the `_.property` callback shorthand
+ * _.map(_.partition(users, 'active'), mapper);
  * // => [['fred'], ['barney', 'pebbles']]
  */
 var partition = createAggregator(function(result, value, key) {

collection/pluck.js

@@ -25,7 +25,7 @@ var baseProperty = require('../internal/baseProperty'),
  * // => [36, 40] (iteration order is not guaranteed)
  */
 function pluck(collection, key) {
-  return map(collection, baseProperty(key + ''));
+  return map(collection, baseProperty(key));
 }
 
 module.exports = pluck;

collection/reduce.js

@@ -12,6 +12,12 @@ var arrayReduce = require('../internal/arrayReduce'),
  * value. The `iteratee` is bound to `thisArg`and invoked with four arguments;
  * (accumulator, value, index|key, collection).
  *
+ * Many lodash methods are guarded to work as interatees for methods like
+ * `_.reduce`, `_.reduceRight`, and `_.transform`.
+ *
+ * The guarded methods are:
+ * `assign`, `defaults`, `merge`, and `sortAllBy`
+ *
  * @static
  * @memberOf _
  * @alias foldl, inject

collection/reject.js

@@ -7,10 +7,14 @@ var arrayFilter = require('../internal/arrayFilter'),
  * The opposite of `_.filter`; this method returns the elements of `collection`
  * that `predicate` does **not** return truthy for.
  *
- * If a property name is provided for `predicate` the created "_.property"
+ * If a property name is provided for `predicate` the created `_.property`
  * style callback returns the property value of the given element.
  *
- * If an object is provided for `predicate` the created "_.matches" style
+ * If a value is also provided for `thisArg` the created `_.matchesProperty`
+ * style callback returns `true` for elements that have a matching property
+ * value, else `false`.
+ *
+ * If an object is provided for `predicate` the created `_.matches` style
  * callback returns `true` for elements that have the properties of the given
  * object, else `false`.
  *
@@ -19,8 +23,7 @@ var arrayFilter = require('../internal/arrayFilter'),
  * @category Collection
  * @param {Array|Object|string} collection The collection to iterate over.
  * @param {Function|Object|string} [predicate=_.identity] The function invoked
- *  per iteration. If a property name or object is provided it is used to
- *  create a "_.property" or "_.matches" style callback respectively.
+ *  per iteration.
  * @param {*} [thisArg] The `this` binding of `predicate`.
  * @returns {Array} Returns the new filtered array.
  * @example
@@ -33,13 +36,17 @@ var arrayFilter = require('../internal/arrayFilter'),
  *   { 'user': 'fred',   'age': 40, 'active': true }
  * ];
  *
- * // using the "_.property" callback shorthand
- * _.pluck(_.reject(users, 'active'), 'user');
+ * // using the `_.matches` callback shorthand
+ * _.pluck(_.reject(users, { 'age': 40, 'active': true }), 'user');
  * // => ['barney']
  *
- * // using the "_.matches" callback shorthand
- * _.pluck(_.reject(users, { 'age': 36 }), 'user');
+ * // using the `_.matchesProperty` callback shorthand
+ * _.pluck(_.reject(users, 'active', false), 'user');
  * // => ['fred']
+ *
+ * // using the `_.property` callback shorthand
+ * _.pluck(_.reject(users, 'active'), 'user');
+ * // => ['barney']
  */
 function reject(collection, predicate, thisArg) {
   var func = isArray(collection) ? arrayFilter : baseFilter;

collection/some.js

@@ -9,10 +9,14 @@ var arraySome = require('../internal/arraySome'),
  * over the entire collection. The predicate is bound to `thisArg` and invoked
  * with three arguments; (value, index|key, collection).
  *
- * If a property name is provided for `predicate` the created "_.property"
+ * If a property name is provided for `predicate` the created `_.property`
  * style callback returns the property value of the given element.
  *
- * If an object is provided for `predicate` the created "_.matches" style
+ * If a value is also provided for `thisArg` the created `_.matchesProperty`
+ * style callback returns `true` for elements that have a matching property
+ * value, else `false`.
+ *
+ * If an object is provided for `predicate` the created `_.matches` style
  * callback returns `true` for elements that have the properties of the given
  * object, else `false`.
  *
@@ -22,8 +26,7 @@ var arraySome = require('../internal/arraySome'),
  * @category Collection
  * @param {Array|Object|string} collection The collection to iterate over.
  * @param {Function|Object|string} [predicate=_.identity] The function invoked
- *  per iteration. If a property name or object is provided it is used to
- *  create a "_.property" or "_.matches" style callback respectively.
+ *  per iteration.
  * @param {*} [thisArg] The `this` binding of `predicate`.
  * @returns {boolean} Returns `true` if any element passes the predicate check,
  *  else `false`.
@@ -33,17 +36,21 @@ var arraySome = require('../internal/arraySome'),
  * // => true
  *
  * var users = [
- *   { 'user': 'barney', 'age': 36, 'active': false },
- *   { 'user': 'fred',   'age': 40, 'active': true }
+ *   { 'user': 'barney', 'active': true },
+ *   { 'user': 'fred',   'active': false }
  * ];
  *
- * // using the "_.property" callback shorthand
- * _.some(users, 'active');
+ * // using the `_.matches` callback shorthand
+ * _.some(users, { user': 'barney', 'active': false });
+ * // => false
+ *
+ * // using the `_.matchesProperty` callback shorthand
+ * _.some(users, 'active', false);
  * // => true
  *
- * // using the "_.matches" callback shorthand
- * _.some(users, { 'age': 1 });
- * // => false
+ * // using the `_.property` callback shorthand
+ * _.some(users, 'active');
+ * // => true
  */
 function some(collection, predicate, thisArg) {
   var func = isArray(collection) ? arraySome : baseSome;

collection/sortBy.js

@@ -12,10 +12,14 @@ var baseCallback = require('../internal/baseCallback'),
  * The `iteratee` is bound to `thisArg` and invoked with three arguments;
  * (value, index|key, collection).
  *
- * If a property name is provided for `predicate` the created "_.property"
+ * If a property name is provided for `predicate` the created `_.property`
  * style callback returns the property value of the given element.
  *
- * If an object is provided for `predicate` the created "_.matches" style
+ * If a value is also provided for `thisArg` the created `_.matchesProperty`
+ * style callback returns `true` for elements that have a matching property
+ * value, else `false`.
+ *
+ * If an object is provided for `predicate` the created `_.matches` style
  * callback returns `true` for elements that have the properties of the given
  * object, else `false`.
  *
@@ -25,7 +29,7 @@ var baseCallback = require('../internal/baseCallback'),
  * @param {Array|Object|string} collection The collection to iterate over.
  * @param {Array|Function|Object|string} [iteratee=_.identity] The function
  *  invoked per iteration. If a property name or an object is provided it is
- *  used to create a "_.property" or "_.matches" style callback respectively.
+ *  used to create a `_.property` or `_.matches` style callback respectively.
  * @param {*} [thisArg] The `this` binding of `iteratee`.
  * @returns {Array} Returns the new sorted array.
  * @example
@@ -42,7 +46,7 @@ var baseCallback = require('../internal/baseCallback'),
  *   { 'user': 'barney' }
  * ];
  *
- * // using the "_.property" callback shorthand
+ * // using the `_.property` callback shorthand
  * _.pluck(_.sortBy(users, 'user'), 'user');
  * // => ['barney', 'fred', 'pebbles']
  */

collection/sortByAll.js

@@ -38,7 +38,7 @@ function sortByAll(collection) {
       props = baseFlatten(args, false, false, 1),
       result = isLength(length) ? Array(length) : [];
 
-  baseEach(collection, function(value, key, collection) {
+  baseEach(collection, function(value) {
     var length = props.length,
         criteria = Array(length);
 

collection/where.js

@@ -6,6 +6,11 @@ var baseMatches = require('../internal/baseMatches'),
  * source object, returning an array of all elements that have equivalent
  * property values.
  *
+ * **Note:** This method supports comparing arrays, booleans, `Date` objects,
+ * numbers, `Object` objects, regexes, and strings. Objects are compared by
+ * their own, not inherited, enumerable properties. For comparing a single
+ * own or inherited property value see `_.matchesProperty`.
+ *
  * @static
  * @memberOf _
  * @category Collection
@@ -15,18 +20,15 @@ var baseMatches = require('../internal/baseMatches'),
  * @example
  *
  * var users = [
- *   { 'user': 'barney', 'age': 36, 'status': 'busy', 'pets': ['hoppy'] },
- *   { 'user': 'fred',   'age': 40, 'status': 'busy', 'pets': ['baby puss', 'dino'] }
+ *   { 'user': 'barney', 'age': 36, 'active': false, 'pets': ['hoppy'] },
+ *   { 'user': 'fred',   'age': 40, 'active': true, 'pets': ['baby puss', 'dino'] }
  * ];
  *
- * _.pluck(_.where(users, { 'age': 36 }), 'user');
+ * _.pluck(_.where(users, { 'age': 36, 'active': false }), 'user');
  * // => ['barney']
  *
  * _.pluck(_.where(users, { 'pets': ['dino'] }), 'user');
  * // => ['fred']
- *
- * _.pluck(_.where(users, { 'status': 'busy' }), 'user');
- * // => ['barney', 'fred']
  */
 function where(collection, source) {
   return filter(collection, baseMatches(source));