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 85a396e11..6c6af239d 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,14 +1,26 @@
 package org.briarproject.bramble.api.cleanup;
 
+import org.briarproject.bramble.api.cleanup.event.MessagesCleanedUpEvent;
 import org.briarproject.bramble.api.db.DbException;
 import org.briarproject.bramble.api.db.Transaction;
 import org.briarproject.bramble.api.nullsafety.NotNullByDefault;
 import org.briarproject.bramble.api.sync.GroupId;
 import org.briarproject.bramble.api.sync.MessageId;
 
+/**
+ * An interface for registering a hook with the {@link CleanupManager}
+ * that will be called when a message's cleanup deadline is reached.
+ */
 @NotNullByDefault
 public interface CleanupHook {
 
+	/**
+	 * Called when a message's cleanup deadline is reached. If this method
+	 * returns true, a {@link MessagesCleanedUpEvent} will be broadcast.
+	 *
+	 * @return True if the message has been deleted, or false if it has not,
+	 * in which case the message's cleanup timer will be stopped
+	 */
 	boolean deleteMessage(Transaction txn, GroupId g, MessageId m)
 			throws DbException;
 }
diff --git a/bramble-api/src/main/java/org/briarproject/bramble/api/cleanup/CleanupManager.java b/bramble-api/src/main/java/org/briarproject/bramble/api/cleanup/CleanupManager.java
index 87764e62f..d416d8fed 100644
--- a/bramble-api/src/main/java/org/briarproject/bramble/api/cleanup/CleanupManager.java
+++ b/bramble-api/src/main/java/org/briarproject/bramble/api/cleanup/CleanupManager.java
@@ -1,10 +1,27 @@
 package org.briarproject.bramble.api.cleanup;
 
+import org.briarproject.bramble.api.cleanup.event.CleanupTimerStartedEvent;
 import org.briarproject.bramble.api.crypto.SecretKey;
+import org.briarproject.bramble.api.db.DatabaseComponent;
+import org.briarproject.bramble.api.db.Transaction;
 import org.briarproject.bramble.api.lifecycle.LifecycleManager;
 import org.briarproject.bramble.api.nullsafety.NotNullByDefault;
 import org.briarproject.bramble.api.sync.ClientId;
+import org.briarproject.bramble.api.sync.MessageId;
 
+/**
+ * The CleanupManager is responsible for tracking the cleanup deadlines of
+ * messages and passing them to their respective
+ * {@link CleanupHook CleanupHooks} when the deadlines are reached.
+ * <p>
+ * The CleanupManager responds to
+ * {@link CleanupTimerStartedEvent CleanupTimerStartedEvents} broadcast by the
+ * {@link DatabaseComponent}.
+ * <p>
+ * See {@link DatabaseComponent#setCleanupTimerDuration(Transaction, MessageId, long)},
+ * {@link DatabaseComponent#startCleanupTimer(Transaction, MessageId)},
+ * {@link DatabaseComponent#stopCleanupTimer(Transaction, MessageId)}.
+ */
 @NotNullByDefault
 public interface CleanupManager {