caolan/async

Documentation needs better examples

Open

#1609 opened on Jan 13, 2019

View on GitHub
 (23 comments) (11 reactions) (0 assignees)JavaScript (28,067 stars) (2,398 forks)batch import
docshelp wanted

Description

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

Contributor guide

Tech stack
javascript
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
mostly clear
Prerequisites
basic knowledge of async.jsunderstanding of callbacks
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60
Research direction
Review all existing documentation examples in the README and source files. Identify the most common use cases for each function (map, filter, each, etc.) and replace simplistic examples like fs.stat with realistic scenarios such as fetching user data or processing API responses. Ensure each example demonstrates the function's options (e.g., concurrency, error handling). Check the issue comments for specific suggestions and link to the relevant files (e.g., docs/index.md).