diff --git a/src/util/Collection.js b/src/util/Collection.js
index 8c5bbdc0b..79ee0f3a2 100644
--- a/src/util/Collection.js
+++ b/src/util/Collection.js
@@ -56,7 +56,7 @@ class Collection extends Map {
}
/**
- * Returns the first item in this collection.
+ * Obtains the first item in this collection.
* @returns {*}
*/
first() {
@@ -64,7 +64,7 @@ class Collection extends Map {
}
/**
- * Returns the first key in this collection.
+ * Obtains the first key in this collection.
* @returns {*}
*/
firstKey() {
@@ -72,8 +72,8 @@ class Collection extends Map {
}
/**
- * Returns the last item in this collection. This is a relatively slow operation,
- * since an array copy of the values must be made to find the last element.
+ * Obtains the last item in this collection. This relies on the `array()` method, and thus the caching mechanism
+ * applies here as well.
* @returns {*}
*/
last() {
@@ -82,8 +82,8 @@ class Collection extends Map {
}
/**
- * Returns the last key in this collection. This is a relatively slow operation,
- * since an array copy of the keys must be made to find the last element.
+ * Obtains the last key in this collection. This relies on the `keyArray()` method, and thus the caching mechanism
+ * applies here as well.
* @returns {*}
*/
lastKey() {
@@ -92,8 +92,8 @@ class Collection extends Map {
}
/**
- * Returns a random item from this collection. This is a relatively slow operation,
- * since an array copy of the values must be made to find a random element.
+ * Obtains a random item from this collection. This relies on the `array()` method, and thus the caching mechanism
+ * applies here as well.
* @returns {*}
*/
random() {
@@ -102,8 +102,8 @@ class Collection extends Map {
}
/**
- * Returns a random key from this collection. This is a relatively slow operation,
- * since an array copy of the keys must be made to find a random element.
+ * Obtains a random key from this collection. This relies on the `keyArray()` method, and thus the caching mechanism
+ * applies here as well.
* @returns {*}
*/
randomKey() {
@@ -112,7 +112,8 @@ class Collection extends Map {
}
/**
- * Returns an array of items where `item[prop] === value` of the collection
+ * Searches for all items where their specified property's value is identical to the given value
+ * (`item[prop] === value`).
* @param {string} prop The property to test against
* @param {*} value The expected value
* @returns {Array}
@@ -130,8 +131,8 @@ class Collection extends Map {
}
/**
- * Searches for a single item where `item[prop] === value`, or the given function returns `true`.
- * In the latter case, this is identical to
+ * Searches for a single item where its specified property's value is identical to the given value
+ * (`item[prop] === value`), or the given function returns a truthy value. In the latter case, this is identical to
* [Array.find()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find).
* Do not use this to obtain an item by its ID. Instead, use `collection.get(id)`. See
* [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/get) for details.
@@ -163,8 +164,8 @@ class Collection extends Map {
/* eslint-disable max-len */
/**
- * Searches for the key of an item where `item[prop] === value`, or the given function returns `true`.
- * In the latter case, this is identical to
+ * Searches for the key of a single item where its specified property's value is identical to the given value
+ * (`item[prop] === value`), or the given function returns a truthy value. In the latter case, this is identical to
* [Array.findIndex()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex).
* @param {string|Function} propOrFn The property to test against, or the function to test with
* @param {*} [value] The expected value - only applicable and required if using a property for the first argument
@@ -193,7 +194,8 @@ class Collection extends Map {
}
/**
- * Searches for an item where `item[prop] === value`, and returns `true` if one is found.
+ * Searches for the existence of a single item where its specified property's value is identical to the given value
+ * (`item[prop] === value`).
* Do not use this to check for an item by its ID. Instead, use `collection.has(id)`. See
* [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/has) for details.
* @param {string} prop The property to test against
@@ -231,7 +233,7 @@ class Collection extends Map {
* [Array.filter()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter).
* @param {Function} fn Function used to test (should return a boolean)
* @param {Object} [thisArg] Value to use as `this` when executing function
- * @returns {Collection}
+ * @returns {Array}
*/
filterArray(fn, thisArg) {
if (thisArg) fn = fn.bind(thisArg);