Adding await docs. (#494)

docs/README.md

@@ -24,10 +24,13 @@ You'll need Homebrew to make sure you have the most recent version of Ruby.
 Periodically run `gem update` and `bundle update` to make sure you have the latest jekyll tooling.
 
 ## Building Docs
-1. `cd` to repo directory
-2. `bundle exec jekyll serve --watch`
-3. Documentation viewable at `localhost:4000`
-4. Modifying sources should auto-regenerate the documentation
+```
+cd ./docs
+bundle exec jekyll serve --watch
+```
+
+Documentation viewable at `localhost:4000`
+Modifying sources should auto-regenerate the documentation
 
 ## Building Examples
 1. `./build.sh` will download dependencies, build, and run all the `*.cpp` files in the `libraries` directory.

docs/libraries/concurrency/await.hpp/f_await.md

@@ -1,8 +1,8 @@
 ---
 layout: function
 title: await
-owner: __MISSING__
-brief: __MISSING__
+owner: sean-parent
+brief: Waits until the future is ready and returns the future value.
 tags:
   - function
 defined_in_file: concurrency/await.hpp

docs/libraries/concurrency/await.hpp/f_await_for.md

@@ -1,8 +1,9 @@
 ---
 layout: function
 title: await_for
-owner: __MISSING__
-brief: __MISSING__
+owner: sean-parent
+brief: |
+  Wait for the specified duration for the future to be ready and either returns a ready future or a new future which can be waited on.
 tags:
   - function
 defined_in_file: concurrency/await.hpp

docs/libraries/concurrency/await.hpp/f_blocking_get.md

@@ -2,7 +2,7 @@
 layout: function
 title: blocking_get
 owner: sean-parent
-brief: Waits until the future is ready
+brief: _Deprecated_ Use [`await()`](./f_await_for.html).
 tags:
   - function
 defined_in_file: concurrency/await.hpp
@@ -35,4 +35,4 @@ namespace:
   - v1
 ---
 
-Waits until the passed future is ready. Using this function causes that one thread resource is consumed which increases contention and possibly causing a deadlock. As well any subsequent non-dependent calculations on the task are also blocked. It is strongly recommended to avoid using this function, but use continuations.
+Waits until the passed future is ready. Using this function causes that one thread resource is consumed which increases contention and possibly causing a deadlock. As well any subsequent non-dependent calculations on the task are also blocked. It is strongly recommended to avoid using this function, but use continuations.

docs/libraries/concurrency/await.hpp/f_blocking_get_for.md

@@ -1,8 +1,8 @@
 ---
 layout: function
 title: blocking_get_for
-owner: __MISSING__
-brief: __MISSING__
+owner: sean-parent
+brief: _Deprecated_ Use [`await_for()`](./f_await_for.html).
 tags:
   - function
 defined_in_file: concurrency/await.hpp

docs/libraries/concurrency/await.hpp/f_invoke_waiting.md

@@ -1,8 +1,8 @@
 ---
 layout: function
 title: invoke_waiting
-owner: __MISSING__
-brief: __MISSING__
+owner: sean-parent
+brief: When calling a waiting operation, other than `await()` or `await_for()`, such as directly waiting on a `std::condition_variable`, the waiting operation should be invoked with `invoke_waiting()`. This will ensure that there are enough threads available in the portable default executor pool to resolve any pending dependent tasks. With the other default executors, this operation has no effect. Platform executors have similar capability but are hooked into blocking primitives to directly detect blocking calls.
 tags:
   - function
 defined_in_file: concurrency/await.hpp

docs/libraries/concurrency/await.hpp/index.md

@@ -1,8 +1,11 @@
 ---
 layout: library
 title: concurrency/await.hpp
-owner: __MISSING__
-brief: __MISSING__
+owner: sean-parent
+brief: |
+  Await provides a way to await the value from a future and to notify the default executor that a task is waiting. Blocking calls are discouraged because they may lead to deadlocks or thread explosions.
+
+  There is a good presentation of the issues [here](https://youtu.be/Z86b3Rd09sE).
 tags:
   - sourcefile
 library-type: sourcefile