docs(detectLimit): add @example

lib/detectLimit.js

@@ -24,6 +24,50 @@ import awaitify from './internal/awaitify.js'
  * (iteratee) or the value `undefined` if none passed. Invoked with
  * (err, result).
  * @returns {Promise} a promise, if a callback is omitted
+ * @example
+ *
+ * // dir1 is a directory that contains file1.txt, file2.txt
+ * // dir2 is a directory that contains file3.txt, file4.txt
+ * // dir3 is a directory that contains file5.txt
+ *
+ * // asynchronous function that checks if a file exists
+ * function fileExists(file, callback) {
+ *    fs.access(file, fs.constants.F_OK, (err) => {
+ *        callback(null, !err);
+ *    });
+ * }
+ *
+ * async.detectLimit(['file3.txt','file2.txt','dir1/file1.txt'], 2, fileExists,
+ *    function(err, result) {
+ *        console.log(result);
+ *        // dir1/file1.txt
+ *        // result now equals the first file in the list that exists
+ *    }
+ * );
+ *
+ * // Using Promises
+ * async.detectLimit(['file3.txt','file2.txt','dir1/file1.txt'], 2, fileExists)
+ * .then(result => {
+ *     console.log(result);
+ *     // dir1/file1.txt
+ *     // result now equals the first file in the list that exists
+ * }).catch(err => {
+ *     console.log(err);
+ * });
+ *
+ * // Using async/await
+ * async () => {
+ *     try {
+ *         let result = await async.detectLimit(['file3.txt','file2.txt','dir1/file1.txt'], 2, fileExists);
+ *         console.log(result);
+ *         // dir1/file1.txt
+ *         // result now equals the first file in the list that exists
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
  */
 function detectLimit(coll, limit, iteratee, callback) {
     return createTester(bool => bool, (res, item) => item)(eachOfLimit(limit), coll, iteratee, callback)