diff --git a/include/ucore/rate_limit.h b/include/ucore/rate_limit.h
index fa7ec01..51c70b4 100644
--- a/include/ucore/rate_limit.h
+++ b/include/ucore/rate_limit.h
@@ -62,8 +62,35 @@ struct RateLimit {
     long last_ts;
 };
 
+/**
+ * Initialize a struct RateLimit, which can hand out @tickets per @period
+ * the perioid must be in the same units as the current_ts
+ *
+ * @param r RateLimit to initialize
+ * @param tickets number of tickets (bucket depth)
+ * @param period per this period
+ * @param current_ts the current timestamp
+ */
 void uc_ratelimit_init(struct RateLimit *r, long tickets, long period, long current_ts);
+
+/**
+ * Reset a RateLimit, filling up the tickets again.
+ *
+ * @param r RateLimit to reset
+ * @param current ts, if non-zero, re-sets the last_ts to the current_ts
+ */
 void uc_ratelimit_reset(struct RateLimit *r, long current_ts);
+
+/**
+ * Check if we have 1 ticket available, and can therefore allow
+ * the work. Removes 1 ticket if we can, and replenishes the tickets
+ * based on the elapsed time since last time the function was called.
+ *
+ * @param r the RateLimit
+ * @param current_ts the current timestamp. Used to calculate the 
+ *                   replenisment of tichets since the previous check.
+ * @return 1 if we can allow, 0 if we don't.
+ */
 int uc_ratelimit_allow(struct RateLimit *r, long current_ts);
 
 #endif