docs: add examples.

Author: ghosind

all.go

@@ -12,6 +12,26 @@ import (
 //
 // The index of the function will be -1 if all functions have been completed without error or
 // panic.
+//
+//	out, err := async.All(func() (int, error) {
+//	  return 1, nil
+//	}, func() (string, error) {
+//	  time.Sleep(100 * time.Millisecond)
+//	  return "hello", nil
+//	}, func(ctx context.Context) error {
+//	  time.Sleep(50 * time.Millisecond)
+//	  return nil
+//	})
+//	// out: [][]any{{1, nil}, {"hello", nil}, {nil}}
+//	// err: nil
+//
+//	_, err = async.All(func() (int, error) {
+//	  return 0, errors.New("some error")
+//	}, func() (string, error) {
+//	  time.Sleep(100 * time.Millisecond)
+//	  return "hello", nil
+//	})
+//	// err: function 0 error: some error
 func All(funcs ...AsyncFn) ([][]any, error) {
 	return all(context.Background(), funcs...)
 }
@@ -90,6 +110,18 @@ func runTaskInAll(ctx context.Context, n int, fn AsyncFn, ch chan<- executeResul
 // AllCompleted executes the functions asynchronously until all functions have been finished. It
 // will return an error slice that is ordered by the functions order, and a boolean value to
 // indicate whether any functions return an error or panic.
+//
+//	out, err := async.AllCompleted(func() (int, error) {
+//	  return 1, nil
+//	}, func() (string, error) {
+//	  time.Sleep(100 * time.Millisecond)
+//	  return "hello", nil
+//	}, func(ctx context.Context) error {
+//	  time.Sleep(50 * time.Millisecond)
+//	  return errors.New("some error")
+//	})
+//	// out: [][]any{{1, nil}, {"hello", nil}, {some error}}
+//	// err: function 2 error: some error
 func AllCompleted(funcs ...AsyncFn) ([][]any, error) {
 	return allCompleted(context.Background(), funcs...)
 }

forever.go

@@ -12,6 +12,28 @@ type ForeverFn func(ctx context.Context, next func(context.Context)) error
 //
 // You can use the context and call the next function to pass values to the next invocation. The
 // next function can be invoked one time only, and it will have no effect if it is invoked again.
+//
+//	err := Forever(func(ctx context.Context, next func(context.Context)) error {
+//	  v := ctx.Value("key")
+//	  if v != nil {
+//	    vi := v.(int)
+//	    if vi == 3 {
+//	      return errors.New("finish")
+//	    }
+//
+//	    fmt.Printf("value: %d\n", vi)
+//
+//	    next(context.WithValue(ctx, "key", vi+1))
+//	  } else {
+//	    next(context.WithValue(ctx, "key", 1))
+//	  }
+//
+//	  return nil
+//	})
+//	fmt.Printf("err: %v\n", err)
+//	// value: 1
+//	// value: 2
+//	// err: finish
 func Forever(fn ForeverFn) error {
 	return forever(context.Background(), fn)
 }

parallel.go

@@ -12,6 +12,20 @@ import (
 //
 // The number of concurrency must be greater than or equal to 0, and it means no concurrency
 // limitation if the number is 0.
+//
+//	// Run 2 functions asynchronously at the time.
+//	out, err := Parallel(2, func(ctx context.Context) (int, error) {
+//	  // Do something
+//	  return 1, nil
+//	}, func(ctx context.Context) (string, error) {
+//	  // Do something
+//	  return "hello", nil
+//	}, func(ctx context.Context) error {
+//	// Do something
+//	  return nil
+//	} /* , ... */)
+//	// out: [][]any{{1, <nil>}, {"hello", <nil>}, {<nil>}}
+//	// err: <nil>
 func Parallel(concurrency int, funcs ...AsyncFn) ([][]any, error) {
 	return parallel(context.Background(), concurrency, funcs...)
 }

race.go

@@ -8,6 +8,19 @@ import (
 // Race executes the functions asynchronously, it will return the index and the result of the first
 // of the finished function (including panic), and it will not send a cancel signal to other
 // functions.
+//
+//	out, index, err := Race(func(ctx context.Context) (int, error) {
+//	  request.Get("https://example.com")
+//	  return 0, nil
+//	}, func(ctx context.Context) (string, error) {
+//	  time.Sleep(500 * time.Millisecond)
+//	  return "test", nil
+//	})
+//	// If the first function faster than the second one:
+//	// out: []any{0, <nil>}, index: 0, err: <nil>
+//	//
+//	// Otherwise:
+//	// out: []any{"test", <nil>}, index: 1, err: <nil>
 func Race(funcs ...AsyncFn) ([]any, int, error) {
 	return race(context.Background(), funcs...)
 }