Enhance examples for Collections methods. (#1726)

* Enhance examples for Collections methods.

* Update collection example code, avoiding usage of IIFE on async/await examples

* Convert examples on async.auto, async.series, and async.parallel to samples using Promises and async/await

Co-authored-by: Roman Balayan <roman.balayan@paymaya.com>

1 files changed, 110 insertions, 10 deletions

diff --git a/docs/v3/series.js.html b/docs/v3/series.js.html
index 02b62f3..bef4a61 100644
--- a/docs/v3/series.js.html
+++ b/docs/v3/series.js.html
@@ -113,35 +113,135 @@ import eachOfSeries from './eachOfSeries';
  * with (err, result).
  * @return {Promise} a promise, if no callback is passed
  * @example
+ *
+ * //Using Callbacks
  * async.series([
  *     function(callback) {
- *         // do some stuff ...
- *         callback(null, 'one');
+ *         setTimeout(function() {
+ *             // do some async task
+ *             callback(null, 'one');
+ *         }, 200);
  *     },
  *     function(callback) {
- *         // do some more stuff ...
- *         callback(null, 'two');
+ *         setTimeout(function() {
+ *             // then do another async task
+ *             callback(null, 'two');
+ *         }, 100);
  *     }
- * ],
- * // optional callback
- * function(err, results) {
- *     // results is now equal to ['one', 'two']
+ * ], function(err, results) {
+ *     console.log(results);
+ *     // results is equal to ['one','two']
  * });
  *
+ * // an example using objects instead of arrays
  * async.series({
  *     one: function(callback) {
  *         setTimeout(function() {
+ *             // do some async task
  *             callback(null, 1);
  *         }, 200);
  *     },
- *     two: function(callback){
+ *     two: function(callback) {
  *         setTimeout(function() {
+ *             // then do another async task
  *             callback(null, 2);
  *         }, 100);
  *     }
  * }, function(err, results) {
- *     // results is now equal to: {one: 1, two: 2}
+ *     console.log(results);
+ *     // results is equal to: { one: 1, two: 2 }
+ * });
+ *
+ * //Using Promises
+ * async.series([
+ *     function(callback) {
+ *         setTimeout(function() {
+ *             callback(null, 'one');
+ *         }, 200);
+ *     },
+ *     function(callback) {
+ *         setTimeout(function() {
+ *             callback(null, 'two');
+ *         }, 100);
+ *     }
+ * ]).then(results => {
+ *     console.log(results);
+ *     // results is equal to ['one','two']
+ * }).catch(err => {
+ *     console.log(err);
  * });
+ *
+ * // an example using an object instead of an array
+ * async.series({
+ *     one: function(callback) {
+ *         setTimeout(function() {
+ *             // do some async task
+ *             callback(null, 1);
+ *         }, 200);
+ *     },
+ *     two: function(callback) {
+ *         setTimeout(function() {
+ *             // then do another async task
+ *             callback(null, 2);
+ *         }, 100);
+ *     }
+ * }).then(results => {
+ *     console.log(results);
+ *     // results is equal to: { one: 1, two: 2 }
+ * }).catch(err => {
+ *     console.log(err);
+ * });
+ *
+ * //Using async/await
+ * async () => {
+ *     try {
+ *         let results = await async.series([
+ *             function(callback) {
+ *                 setTimeout(function() {
+ *                     // do some async task
+ *                     callback(null, 'one');
+ *                 }, 200);
+ *             },
+ *             function(callback) {
+ *                 setTimeout(function() {
+ *                     // then do another async task
+ *                     callback(null, 'two');
+ *                 }, 100);
+ *             }
+ *         ]);
+ *         console.log(results);
+ *         // results is equal to ['one','two']
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
+ * // an example using an object instead of an array
+ * async () => {
+ *     try {
+ *         let results = await async.parallel({
+ *             one: function(callback) {
+ *                 setTimeout(function() {
+ *                     // do some async task
+ *                     callback(null, 1);
+ *                 }, 200);
+ *             },
+ *            two: function(callback) {
+ *                 setTimeout(function() {
+ *                     // then do another async task
+ *                     callback(null, 2);
+ *                 }, 100);
+ *            }
+ *         });
+ *         console.log(results);
+ *         // results is equal to: { one: 1, two: 2 }
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
  */
 export default function series(tasks, callback) {
     return _parallel(eachOfSeries, tasks, callback);