diff --git a/lib/tfw/decorators/rate_limiter.py b/lib/tfw/decorators/rate_limiter.py
index fdfa992..e0c87d1 100644
--- a/lib/tfw/decorators/rate_limiter.py
+++ b/lib/tfw/decorators/rate_limiter.py
@@ -7,8 +7,32 @@ from time import time, sleep
 from tfw.decorators.lazy_property import lazy_property
 
 
+# TODO: add this to sphinx docs
 class RateLimiter:
+    """
+    Decorator class for rate limiting.
+
+    When applied to a function this decorator will apply rate limiting
+    if the function is invoked more frequently than rate_per_seconds.
+
+    By default rate limiting means sleeping until the next invocation time
+    as per __init__ parameter rate_per_seconds.
+
+    Note that this decorator BLOCKS THE THREAD it is being executed on,
+    so it is only acceptable for stuff running on a separate thread.
+
+    If this is no good for you please refer to AsyncRateLimiter in this module,
+    which is designed not to block and use the IOLoop it is being called from,
+    or redefine the action argument of __init__ (which defaults to time.sleep).
+    """
     def __init__(self, rate_per_second, action=sleep):
+        """
+        :param rate_per_second: max frequency the decorated method should be
+                                invoked with
+        :param action: what to do when rate limiting. defaults to time.sleep,
+                       receives the number of seconds until the next invocation
+                       should occour as an argument
+        """
         self.min_interval = 1 / float(rate_per_second)
         self.action = action
         self.fun = None