diff --git a/bramble-api/src/main/java/org/briarproject/bramble/api/cleanup/CleanupHook.java b/bramble-api/src/main/java/org/briarproject/bramble/api/cleanup/CleanupHook.java
index afc8443a3..1cb930d39 100644
--- a/bramble-api/src/main/java/org/briarproject/bramble/api/cleanup/CleanupHook.java
+++ b/bramble-api/src/main/java/org/briarproject/bramble/api/cleanup/CleanupHook.java
@@ -1,6 +1,7 @@
 package org.briarproject.bramble.api.cleanup;
 
 import org.briarproject.bramble.api.cleanup.event.MessagesCleanedUpEvent;
+import org.briarproject.bramble.api.db.DatabaseComponent;
 import org.briarproject.bramble.api.db.DbException;
 import org.briarproject.bramble.api.db.Transaction;
 import org.briarproject.bramble.api.nullsafety.NotNullByDefault;
@@ -20,6 +21,11 @@ public interface CleanupHook {
 	 * Called when the cleanup deadlines of one or more messages are reached.
 	 * When this method returns, a {@link MessagesCleanedUpEvent} will be
 	 * broadcast.
+	 * <p>
+	 * The callee is not required to delete the messages, but the hook won't be
+	 * called again for these messages unless another cleanup timer is set (see
+	 * {@link DatabaseComponent#setCleanupTimerDuration(Transaction, MessageId, long)}
+	 * and {@link DatabaseComponent#startCleanupTimer(Transaction, MessageId)}).
 	 */
 	void deleteMessages(Transaction txn, GroupId g,
 			Collection<MessageId> messageIds) throws DbException;