Documentation needs better examples

Consider this example for map

async.map(['file1','file2','file3'], fs.stat, function(err, results) {
    // results is now an array of stats for each file
});

This basically tells me nothing except syntax. In most cases people aren’t going to pass fs.stat. The examples should include use of all possible options. All examples for all functions and methods need to be updated. They are too simplistic

[aearly]

I agree, we need much better docs. I’d also like to change many of the examples (or add mroe examples) to use async/await. However, this is something that takes time I don’t have at the moment.

[flatcoding]

I’m in particular looking for a (simple) Promise-based example of async.mapLimit, even without async/await. Haven’t found any non-callback example so far at all.