Skip to content

Commit

Permalink
fix(docs): fixes and updates API docs
Browse files Browse the repository at this point in the history
Fixes #14
  • Loading branch information
tunnckoCore committed Oct 29, 2016
1 parent f4c7f02 commit b909ae7
Show file tree
Hide file tree
Showing 3 changed files with 2,857 additions and 7 deletions.
23 changes: 23 additions & 0 deletions .verb.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,29 @@ console.log(isAsyncFunction(fs.stat, false)) // => 1
// and that's the second element in `common-callback-names` array
```

**Side note:** In previous nodejs versions it was called in a few different ways - `cb_`, `callback_` and etc. That's why [common-callback-names][] exists. As in v7 it seems everything now is called `callback`. So in most of the cases you will get boolean `true` always - both in strict and non-strict mode. In non-strict mode that will mean your function has argument called `callback`.

If you pass array of names as second argument, in non-strict mode you will get index of that array.

**Example**

```js
var isAsyncFn = require('is-async-function')

// you considered you callback fucntion
// to be called `qux` for some reason
function myAsyncFn (foo, bar, qux) {
qux(null, 123)
}

console.log(isAsyncFn(myAsyncFn)) // => false
console.log(isAsyncFn(myAsyncFn, false)) // => false

console.log(isAsyncFn(myAsyncFn, ['callback', 'qux'], false)) // => 1
// you are getting "1", because `qux` is second item
// in provided `names` array.
```

{% if (verb.related && verb.related.list && verb.related.list.length) { %}
## Related
{%= related(verb.related.list, {words: 12}) %}
Expand Down
37 changes: 30 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,13 @@ const isAsyncFunction = require('is-async-function')
### [isAsyncFunction](index.js#L47)
> Trying to guess is `fn` asynchronous function or not. But not [is-callback-function][] be aware of that diff.
**Params**

* `fn` **{Function}**: is this `fn` a callback function
* `names` **{Array}**: arguments names, default are [common-callback-names][]
* `strict` **{Boolean}**: defaults to `true` to always return a boolean, pass `false` to get index (position) - this is useful when you wanna understand which "callback name" exists as argument in that `fn`
* `returns` **{Boolean|Number}**: always boolean `true` or `false` when on strict mode, othewise it can be Number index representing the position and if index is 0 it is transformed to boolean `true` - so always positive value if function is async.

**Example**

```js
Expand All @@ -41,13 +48,6 @@ console.log(isAsyncFunction(fs.readFile, ['foo', 'bar']))
// => false, because fs.readFile uses `cb`
```

**Params**

* `fn` **{Function}**: is this `fn` a callback function
* `names` **{Array}**: arguments names, default are [common-callback-names][]
* `strict` **{Boolean}**: defaults to `true` to always return a boolean, pass `false` to get index (position) - this is useful when you wanna understand which "callback name" exists as argument in that `fn`
* `returns` **{Boolean|Number}**: always boolean `true` or `false` when on strict mode, othewise it can be Number index representing the position and if index is 0 it is transformed to boolean `true` - so always positive value if function is async.

**non-strict mode**

> passing `false` as second or third argument
Expand All @@ -64,6 +64,29 @@ console.log(isAsyncFunction(fs.stat, false)) // => 1
// and that's the second element in `common-callback-names` array
```

**Side note:** In previous nodejs versions it was called in a few different ways - `cb_`, `callback_` and etc. That's why [common-callback-names][] exists. As in v7 it seems everything now is called `callback`. So in most of the cases you will get boolean `true` always - both in strict and non-strict mode. In non-strict mode that will mean your function has argument called `callback`.

If you pass array of names as second argument, in non-strict mode you will get index of that array.

**Example**

```js
var isAsyncFn = require('is-async-function')

// you considered you callback fucntion
// to be called `qux` for some reason
function myAsyncFn (foo, bar, qux) {
qux(null, 123)
}

console.log(isAsyncFn(myAsyncFn)) // => false
console.log(isAsyncFn(myAsyncFn, false)) // => false

console.log(isAsyncFn(myAsyncFn, ['callback', 'qux'], false)) // => 1
// you are getting "1", because `qux` is second item
// in provided `names` array.
```

## Related
- [common-callback-names](https://www.npmjs.com/package/common-callback-names): List of common callback names - callback, cb, callback_, next, done. | [homepage](https://github.com/tunnckocore/common-callback-names#readme "List of common callback names - callback, cb, callback_, next, done.")
- [fn-args](https://www.npmjs.com/package/fn-args): Get the arguments of a function | [homepage](https://github.com/sindresorhus/fn-args "Get the arguments of a function")
Expand Down
Loading

0 comments on commit b909ae7

Please sign in to comment.