diff --git a/lib/tfw/decorators/rate_limiter.py b/lib/tfw/decorators/rate_limiter.py
index 371e732..134dd3e 100644
--- a/lib/tfw/decorators/rate_limiter.py
+++ b/lib/tfw/decorators/rate_limiter.py
@@ -7,10 +7,9 @@ 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.
+    Decorator class for rate limiting, blocking.
 
     When applied to a function this decorator will apply rate limiting
     if the function is invoked more frequently than rate_per_seconds.
@@ -59,9 +58,22 @@ class RateLimiter:
         return 0
 
 
-# TODO document this
 class AsyncRateLimiter(RateLimiter):
+    """
+    Decorator class for rate limiting, non-blocking.
+
+    The semantics of the rate limiting are similar to that of RateLimiter,
+    but this decorator never blocks, instead it adds an async callback version
+    of the decorated function to the IOLoop to be executed after the rate limiting
+    has expired.
+    """
     def __init__(self, rate_per_second, ioloop_factory):
+        """
+        :param rate_per_second: max frequency the decorated method should be
+                                invoked with
+        :param ioloop_factory: callable that should return an instance of the
+                               IOLoop of the application
+        """
         self._ioloop_factory = ioloop_factory
         self._ioloop = None
         self._last_callback = None