diff --git a/legacy/eio/doc/eio.dox.in b/legacy/eio/doc/eio.dox.in
index e4ec167eb5..0d48034d41 100644
--- a/legacy/eio/doc/eio.dox.in
+++ b/legacy/eio/doc/eio.dox.in
@@ -26,7 +26,8 @@
  * @author Stephen "okra" Houston <unixtitan@@gmail.com>
  * @author Gustavo Sverzut Barbieri <barbieri@@gmail.com>
  * @author Vincent "caro" Torri  <vtorri at univ-evry dot fr>
- * @date 2010-2011
+ * @author Guillaume "kuri" Friloux <guillaume.friloux@@asp64.com>
+ * @date 2010-2012
  *
  * @section eio_intro_sec Introduction
  * @version @PACKAGE_VERSION@
@@ -284,3 +285,60 @@
  * @endcode
  */
 
+/**
+ * @page tutorial_monitor_add eio_monitor_add() tutorial
+ *
+ * To use eio_monitor_add(), you have to define callbacks
+ * for events declared by eio.
+ * Available events are :
+ * - EIO_MONITOR_FILE_CREATED
+ * - EIO_MONITOR_FILE_DELETED
+ * - EIO_MONITOR_FILE_MODIFIED
+ * - EIO_MONITOR_FILE_CLOSED
+ * - EIO_MONITOR_DIRECTORY_CREATED
+ * - EIO_MONITOR_DIRECTORY_DELETED
+ * - EIO_MONITOR_DIRECTORY_CLOSED
+ * - EIO_MONITOR_SELF_RENAME
+ * - EIO_MONITOR_SELF_DELETED
+ *
+ * As nothing is worth an example, here it is :
+ * @code
+ * #include <Eina.h>
+ * #include <Ecore.h>
+ * #include <Eio.h>
+ *
+ * void file_modified(void *data, int type, void *event)
+ * {
+ *    const char *filename = (const char *)data;
+ *    printf("file %s ", filename);
+ *    if( type == EIO_MONITOR_FILE_MODIFIED )
+ *       printf("is being modified");
+ *    else if( type == EIO_MONITOR_FILE_CLOSED )
+ *       printf("is not more being modified");
+ *    else printf("got unexpected changes");
+ *    printf("\n");
+ * }
+ *
+ * int main(int argc, char **argv) {
+ *    Eio_Monitor *monitor  = NULL,
+ *                *monitor2 = NULL;
+ *    eio_init();
+ *    const char *filename = eina_stringshare_add("/tmp/eio_notify_testfile");
+ *
+ *    monitor  = eio_monitor_add(filename);
+ *    ecore_event_handler_add(EIO_MONITOR_FILE_MODIFIED, (Ecore_Event_Handler_Cb)file_modified, filename);
+ *    ecore_event_handler_add(EIO_MONITOR_FILE_CLOSED, (Ecore_Event_Handler_Cb)file_modified, filename);
+ *
+ *    ecore_main_loop_begin();
+ *    eio_shutdown();
+ *    eina_stringshare_del(filename);
+ * }
+ * @endcode
+ * Build the example doing :
+ * @verbatim gcc -o tutorial_monitor_add tutorial_monitor_add.c `pkg-config --libs --cflags eio ecore ecore-file eina`
+ * then create the file /tmp/eio_notify_testfile :
+ * @verbatim touch /tmp/eio_notify_testfile
+ * and launch tutorial_monitor_add, and in another terminal, write into /tmp/eio_notify_testfile, doing for example :
+ * @verbatim echo "test" >> /tmp/eio_notify_testfile
+ */
+
diff --git a/legacy/eio/src/lib/Eio.h b/legacy/eio/src/lib/Eio.h
index 53c34a5393..1f09345492 100644
--- a/legacy/eio/src/lib/Eio.h
+++ b/legacy/eio/src/lib/Eio.h
@@ -815,9 +815,41 @@ struct _Eio_Monitor_Event
    const char *filename;
 };
 
+/**
+ * @brief Adds a file/directory to monitor (inotify mechanism)
+ * @param path file/directory to monitor
+ * @return NULL in case of a failure.
+ *
+ * This function will add the given path to its internal
+ * list of files to monitor. Its using inotify mechanism
+ * introduced in kernel 2.6.13 to get non active monitoring.
+ */
 EAPI Eio_Monitor *eio_monitor_add(const char *path);
+
+/**
+ * @param path file/directory to monitor
+ * @return NULL in case of a failure.
+ * Does the same thing than eio_monitor_add() but
+ * expects an eina_stringshared buffer.
+ * @warning dont give anything else than a stringshared buffer!
+ *  if you dont know what you do, use eio_monitor_add().
+ */
 EAPI Eio_Monitor *eio_monitor_stringshared_add(const char *path);
+
+/**
+ * @brief Deletes a path from the “watched” list
+ * @param monitor Eio_Monitor you want to stop watching.
+ *  it can only be an Eio_Monitor given to you when calling
+ *  eio_monitor_add() or eio_monitor_stringshared_add()
+ */
 EAPI void eio_monitor_del(Eio_Monitor *monitor);
+
+/**
+ * @brief returns the path being watched by the given
+ *  Eio_Monitor.
+ * @param monitor Eio_Monitor that you want to get path
+ * @return returns a stringshared buffer, do not free it!
+ */
 EAPI const char *eio_monitor_path_get(Eio_Monitor *monitor);
 
 /**
diff --git a/legacy/eio/src/lib/eio_inotify.c b/legacy/eio/src/lib/eio_inotify.c
index 8de90df156..9eb3e88c64 100644
--- a/legacy/eio/src/lib/eio_inotify.c
+++ b/legacy/eio/src/lib/eio_inotify.c
@@ -196,6 +196,8 @@ void eio_monitor_backend_add(Eio_Monitor *monitor)
    backend->hwnd = inotify_add_watch(ecore_main_fd_handler_fd_get(_inotify_fdh), monitor->path, mask);
    if (!backend->hwnd)
      return eio_monitor_fallback_add(monitor);
+
+   eina_hash_direct_add(_inotify_monitors, &backend->hwnd, backend);
 }
 
 void eio_monitor_backend_del(Eio_Monitor *monitor)
diff --git a/legacy/eio/src/lib/eio_monitor.c b/legacy/eio/src/lib/eio_monitor.c
index f7f94cc77f..1119e6dadb 100644
--- a/legacy/eio/src/lib/eio_monitor.c
+++ b/legacy/eio/src/lib/eio_monitor.c
@@ -112,7 +112,7 @@ _eio_monitor_error_cb(void *data, Eio_File *handler __UNUSED__, int error)
    monitor->error = error;
    monitor->exist = NULL;
 
-   if (EINA_REFCOUNT_GET(monitor) > 1)
+   if (EINA_REFCOUNT_GET(monitor) >= 1)
      _eio_monitor_error(monitor, error);
 
    EINA_REFCOUNT_UNREF(monitor)
@@ -195,6 +195,7 @@ eio_monitor_stringshared_add(const char *path)
    monitor->rename = EINA_FALSE;
 
    EINA_REFCOUNT_INIT(monitor);
+   EINA_REFCOUNT_REF(monitor); /* as we spawn a thread for this monitor, we need to refcount specifically for it */
 
    monitor->exist = eio_file_direct_stat(monitor->path,
                                          _eio_monitor_stat_cb,
@@ -263,6 +264,8 @@ _eio_monitor_rename(Eio_Monitor *monitor, const char *newpath)
       return ;
     }
 
+  EINA_REFCOUNT_REF(monitor); /* as we spawn a thread for this monitor, we need to refcount specifically for it */
+
   /* restart */
   monitor->rename = EINA_TRUE;
   monitor->exist = eio_file_direct_stat(monitor->path,