Update documentation concerning fs.readdir (mochajs#3657)

No order is implied via fs.readdir(). Different OS/filesystem combinations can give different results via readdir(3) which returns directory entries in traversal order (e.g., on macOS, HFS+ uses lexical order and APFS uses filename hash order).

lib/utils.js

@@ -83,6 +83,10 @@ function ignored(path) {
 /**
  * Lookup files in the given `dir`.
  *
+ * @description
+ * Filenames are returned in _traversal_ order by the OS/filesystem.
+ * **Make no assumption that the names will be sorted in any fashion.**
+ *
  * @private
  * @param {string} dir
  * @param {string[]} [ext=['.js']]
@@ -502,12 +506,16 @@ exports.canonicalize = function canonicalize(value, stack, typeHint) {
 /**
  * Lookup file names at the given `path`.
  *
- * @memberof Mocha.utils
+ * @description
+ * Filenames are returned in _traversal_ order by the OS/filesystem.
+ * **Make no assumption that the names will be sorted in any fashion.**
+ *
  * @public
- * @param {string} filepath Base path to start searching from.
- * @param {string[]} extensions File extensions to look for.
- * @param {boolean} recursive Whether or not to recurse into subdirectories.
+ * @memberof Mocha.utils
  * @todo Fix extension handling
+ * @param {string} filepath - Base path to start searching from.
+ * @param {string[]} extensions - File extensions to look for.
+ * @param {boolean} recursive - Whether to recurse into subdirectories.
  * @return {string[]} An array of paths.
  */
 exports.lookupFiles = function lookupFiles(filepath, extensions, recursive) {