diff --git a/synapse/storage/_base.py b/synapse/storage/_base.py
index 99c0948754..0872a438f1 100644
--- a/synapse/storage/_base.py
+++ b/synapse/storage/_base.py
@@ -132,6 +132,9 @@ class Cache(object):
 class CacheDescriptor(object):
     """ A method decorator that applies a memoizing cache around the function.
 
+    This caches deferreds, rather than the results themselves. Deferreds that
+    fail are removed from the cache.
+
     The function is presumed to take zero or more arguments, which are used in
     a tuple as the key for the cache. Hits are served directly from the cache;
     misses use the function body to generate the value.