Improve docs for aws_future (#724)

- move getter/setter API docs to top of file, along with other API docs
- document how to use _DECLARATION and _IMPLEMENTATION macros
- remove experimental/unstable comment to encourage more use

Author: graebm