From aff7b27f25dc2b0c4477d041f623ff0b75c86370 Mon Sep 17 00:00:00 2001
From: Michele Caini <michele.caini@gmail.com>
Date: Mon, 1 Aug 2016 17:28:46 +0200
Subject: [PATCH] docs

---
 src/uvw/async.hpp | 10 ++++------
 src/uvw/check.hpp | 29 +++++++++++++++++++++++++++++
 src/uvw/loop.hpp  |  4 ++++
 3 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/src/uvw/async.hpp b/src/uvw/async.hpp
index d7274e08..41b9fc55 100644
--- a/src/uvw/async.hpp
+++ b/src/uvw/async.hpp
@@ -23,8 +23,8 @@ 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.
+ * Async handles allow the user to _wakeup_ the event loop and get an event
+ * emitted from another thread.
  */
 class AsyncHandle final: public Handle<AsyncHandle, uv_async_t> {
     static void sendCallback(uv_async_t *handle) {
@@ -37,9 +37,7 @@ class AsyncHandle final: public Handle<AsyncHandle, uv_async_t> {
 public:
     /**
      * @brief Creates a new async handle.
-     *
-     * No arguments required.
-     *
+     * @param ref A pointer to the loop from which the handle generated.
      * @return A pointer to the newly created handle.
      */
     template<typename... Args>
@@ -60,7 +58,7 @@ public:
     }
 
     /**
-     * @brief Wakeups the event loop and call the async handle’s callback.
+     * @brief Wakeups the event loop and emits the AsyncEvent event.
      *
      * It’s safe to call this function from any thread.<br/>
      * An AsyncEvent will be emitted on the loop thread.
diff --git a/src/uvw/check.hpp b/src/uvw/check.hpp
index 379bf17f..3345db5f 100644
--- a/src/uvw/check.hpp
+++ b/src/uvw/check.hpp
@@ -12,9 +12,20 @@
 namespace uvw {
 
 
+/**
+ * @brief Trigger event.
+ *
+ * It will be emitted by the CheckHandle according with its functionalities.
+ */
 struct CheckEvent: Event<CheckEvent> { };
 
 
+/**
+ * @brief The CheckHandle handle.
+ *
+ * Check handles will emit a CheckEvent once per loop iteration, right after
+ * polling for I/O.
+ */
 class CheckHandle final: public Handle<CheckHandle, uv_check_t> {
     static void startCallback(uv_check_t *handle) {
         CheckHandle &check = *(static_cast<CheckHandle*>(handle->data));
@@ -24,19 +35,37 @@ class CheckHandle final: public Handle<CheckHandle, uv_check_t> {
     using Handle::Handle;
 
 public:
+    /**
+     * @brief Creates a new check handle.
+     * @param ref A pointer to the loop from which the handle generated.
+     * @return A pointer to the newly created handle.
+     */
     template<typename... Args>
     static std::shared_ptr<CheckHandle> create(Args&&... args) {
         return std::shared_ptr<CheckHandle>{new CheckHandle{std::forward<Args>(args)...}};
     }
 
+    /**
+     * @brief Initializes the handle.
+     * @return True in case of success, false otherwise.
+     */
     bool init() {
         return initialize<uv_check_t>(&uv_check_init);
     }
 
+    /**
+     * @brief Starts the handle.
+     *
+     * A CheckEvent event will be emitted once per loop iteration, right after
+     * polling for I/O.
+     */
     void start() {
         invoke(&uv_check_start, get<uv_check_t>(), &startCallback);
     }
 
+    /**
+     * @brief Stops the handle.
+     */
     void stop() {
         invoke(&uv_check_stop, get<uv_check_t>());
     }
diff --git a/src/uvw/loop.hpp b/src/uvw/loop.hpp
index 102138c9..bab73c92 100644
--- a/src/uvw/loop.hpp
+++ b/src/uvw/loop.hpp
@@ -188,6 +188,8 @@ public:
      * * Loop::Configure::BLOCK_SIGNAL: Block a signal when polling for new
      * events. A second argument is required and it is the signal number.
      *
+     * An ErrorEvent will be emitted in case of errors.
+     *
      * See the official
      * [documentation](http://docs.libuv.org/en/v1.x/loop.html#c.uv_loop_configure)
      * for further details.
@@ -237,6 +239,8 @@ public:
      *
      * Call this function only when the loop has finished executing and all open
      * handles and requests have been closed, or the loop will emit an error.
+     *
+     * An ErrorEvent will be emitted in case of errors.
      */
     void close() {
         auto err = uv_loop_close(loop.get());