docs: add async module to readme (nvim-lua#208)

README.md

@@ -18,6 +18,8 @@ Plug 'nvim-lua/plenary.nvim'
 
 ## Modules
 
+- `plenary.async`
+- `plenary.async_lib`
 - `plenary.job`
 - `plenary.path`
 - `plenary.scandir`
@@ -26,6 +28,75 @@ Plug 'nvim-lua/plenary.nvim'
 - `plenary.filetype`
 - `plenary.strings`
 
+### plenary.async
+
+A Lua module for asynchronous programming using coroutines. This library is built on native lua coroutines and `libuv`. Coroutines make it easy to avoid callback hell and allow for easy cooperative concurrency and cancellation. Apart from allowing users to perform asynchronous io easily, this library also functions as an abstraction for coroutines.
+
+#### Getting started
+
+You can do
+```lua
+local async = require "plenary.async"
+```
+All other modules are automatically required and can bet accessed by indexing `async`.
+You needn't worry about performance as this will require all the submodules lazily.
+
+#### A quick example
+
+Libuv luv provides this example of reading a file.
+
+```lua
+local uv = vim.loop
+
+local read_file = function(path, callback)
+  uv.fs_open(path, "r", 438, function(err, fd)
+    assert(not err, err)
+    uv.fs_fstat(fd, function(err, stat)
+      assert(not err, err)
+      uv.fs_read(fd, stat.size, 0, function(err, data)
+        assert(not err, err)
+        uv.fs_close(fd, function(err)
+          assert(not err, err)
+          callback(data)
+        end)
+      end)
+    end)
+  end)
+end
+```
+
+We can write it using the library like this:
+```lua
+local a = require "plenary.async"
+
+local read_file = function(path)
+  local err, fd = a.uv.fs_open(path, "r", 438)
+  assert(not err, err)
+
+  local err, stat = a.uv.fs_fstat(fd)
+  assert(not err, err)
+
+  local err, data = a.uv.fs_read(fd, stat.size, 0)
+  assert(not err, err)
+
+  local err = a.uv.fs_close(fd)
+  assert(not err, err)
+
+  return data
+end
+```
+
+#### Plugins using this
+
+- [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim)
+- [gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim)
+- [vgit.nvim](https://github.com/tanvirtin/vgit.nvim)
+- [neogit](https://github.com/TimUntersberger/neogit) (using version 1)
+
+### plenary.async_lib
+
+Please use `plenary.async` instead. This was version 1 and is just here for compatibility reasons.
+
 ### plenary.job
 
 A Lua module to interact with system processes. Pass in your `command`, the desired `args`, `env` and `cwd`.