From 3673362c5cc92cd01ee3cc230a7e40524e59bb55 Mon Sep 17 00:00:00 2001
From: Michele Caini <michele.caini@gmail.com>
Date: Mon, 1 Aug 2016 17:20:45 +0200
Subject: [PATCH] docs: async.hpp

---
 src/uvw/async.hpp | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/src/uvw/async.hpp b/src/uvw/async.hpp
index 6e6baa03..d7274e08 100644
--- a/src/uvw/async.hpp
+++ b/src/uvw/async.hpp
@@ -12,9 +12,20 @@
 namespace uvw {
 
 
+/**
+ * @brief Trigger event.
+ *
+ * It will be emitted by the AsyncHandle according with its functionalities.
+ */
 struct AsyncEvent: Event<AsyncEvent> { };
 
 
+/**
+ * @brief The AsyncHandle handle.
+ *
+ * Async handles allow the user to _wakeup_ the event loop and get a callback
+ * called from another thread.
+ */
 class AsyncHandle final: public Handle<AsyncHandle, uv_async_t> {
     static void sendCallback(uv_async_t *handle) {
         AsyncHandle &async = *(static_cast<AsyncHandle*>(handle->data));
@@ -24,15 +35,40 @@ class AsyncHandle final: public Handle<AsyncHandle, uv_async_t> {
     using Handle::Handle;
 
 public:
+    /**
+     * @brief Creates a new async handle.
+     *
+     * No arguments required.
+     *
+     * @return A pointer to the newly created handle.
+     */
     template<typename... Args>
     static std::shared_ptr<AsyncHandle> create(Args&&... args) {
         return std::shared_ptr<AsyncHandle>{new AsyncHandle{std::forward<Args>(args)...}};
     }
 
+    /**
+     * @brief Initializes the handle.
+     *
+     * Unlike other handle initialization functions, it immediately starts the
+     * handle.
+     *
+     * @return True in case of success, false otherwise.
+     */
     bool init() {
         return initialize<uv_async_t>(&uv_async_init, &sendCallback);
     }
 
+    /**
+     * @brief Wakeups the event loop and call the async handle’s callback.
+     *
+     * It’s safe to call this function from any thread.<br/>
+     * An AsyncEvent will be emitted on the loop thread.
+     *
+     * See the official
+     * [documentation](http://docs.libuv.org/en/v1.x/async.html#c.uv_async_send)
+     * for further details.
+     */
     void send() {
         invoke(&uv_async_send, get<uv_async_t>());
     }