From 0ed968af49b21bc37ca53d10ff04651c5627da11 Mon Sep 17 00:00:00 2001
From: Vinicius Guedes <viniciusgued@gmail.com>
Date: Sat, 9 May 2020 12:03:25 -0300
Subject: [PATCH] docs: python docstring explaining functions

---
 Makefile          |  3 +++
 onany/__init__.py | 66 +++++++++++++++++++++++++++++++++++++++++++++++
 setup.py          |  1 +
 3 files changed, 70 insertions(+)

diff --git a/Makefile b/Makefile
index 87dd49b..561d30e 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,9 @@
 citest:
 	coverage run -m unittest discover
 	coverage xml
+
+clear:
+	rm -rf build coverage dist onany.egg-info .coverage
 	
 deploy:
 	python setup.py sdist bdist_wheel
diff --git a/onany/__init__.py b/onany/__init__.py
index 726f120..dd80f1b 100644
--- a/onany/__init__.py
+++ b/onany/__init__.py
@@ -5,14 +5,30 @@
 
 
 def clear_listeners():
+    """Clear listeners registered"""
+
     EventManager.clear()
 
 
 def dispatch(event: str, *args, **kwargs) -> None:
+    """Dispatch an event to registered listeners.
+    
+    :param event: Event to be triggered
+    :param *args: Optional args to be redirect to listeners
+    :param **kwargs: Optional keyed args to be redirect to listeners
+    """
+
     return EventManager.emit(event, *args, **kwargs)
 
 
 def disthread(event: str, *args, **kwargs) -> Thread:
+    """Through a thread dispatch an event to registered listeners.
+
+    :param event: Event to be triggered
+    :param *args: Optional args to be redirect to listeners
+    :param **kwargs: Optional keyed args to be redirect to listeners
+    """
+
     thread: Thread = Thread(
         target=EventManager.emit,
         args=(event, *args,),
@@ -23,6 +39,56 @@ def disthread(event: str, *args, **kwargs) -> Thread:
 
 
 def listener(event: str, callback: Union[callable, Dict[str, Any]] = None) -> callable:
+    """Register a listener to be triggered by defined event on the future.
+    
+    There're two different types of listeners:
+        1. Callable: The common one, listener is defined as a callable
+        and can be triggered whenever desired.
+        2. Hook: Listener is defined as a dictionary with rules indicating
+        how an API andpoint can be called.
+
+    Callable:
+        Decorator:
+            >>> from onany import dispatch, listener
+            
+            @listener("event.name")
+            def on_event():
+                print("Do something")
+
+            >>> dispatch("event.name")
+
+        Register:
+            >>> from onany import dispatch, listener
+
+            def on_event():
+                print("Do something")
+
+            >>> listener("event.name", on_event)
+            >>> dispatch("event.name")
+
+    Hook:
+        >>> from onany import dispatch, listener
+
+        def api_callback_if_i_need_to_know_response(response):
+            if response.status_code !== 200:
+                print("some thing happen'd")
+
+        >>> listener("event.name", {
+            "route": "https://my.api.io/hook",
+            "callback": api_callback_if_i_need_to_know_response
+        })
+
+        >>> data = {
+            "optional": "hook",
+            "json": "payload"
+        }
+
+        >>> dispatch("event.name", data=data)
+
+    :param event: Event to be listened
+    :param callback: (Optional) can be a listener or rules to a hook dispatch
+    """
+
     if callable(callback):
         return EventManager.listen(event, callback)
 
diff --git a/setup.py b/setup.py
index e4e68c7..10420f3 100644
--- a/setup.py
+++ b/setup.py
@@ -9,6 +9,7 @@
 with open(os.path.join("requirements.txt")) as file:
     requirements = file.read().split("\n")
 
+
 setup(
     name="onany",
     packages=["onany"],