diff --git a/swh/storage/storage.py b/swh/storage/storage.py
--- a/swh/storage/storage.py
+++ b/swh/storage/storage.py
@@ -224,6 +224,11 @@
     def content_get(self, content):
         """Retrieve in bulk contents and their data.
 
+        This generator yields exactly as many items than provided sha1
+        identifiers, but callers should not assume this will always be true.
+
+        It may also yield `None` values in case an object was not found.
+
         Args:
             content: iterables of sha1
 
@@ -257,6 +262,10 @@
     def content_get_range(self, start, end, limit=1000, db=None, cur=None):
         """Retrieve contents within range [start, end] bound by limit.
 
+        Note that this function may return more than one blob per hash. The
+        limit is enforced with multiplicity (ie. two blobs with the same hash
+        will count twice toward the limit).
+
         Args:
             **start** (bytes): Starting identifier range (expected smaller
                            than end)