diff --git a/pageserver/src/disk_usage_eviction_task.rs b/pageserver/src/disk_usage_eviction_task.rs
index 6ae41c71d0..7b8b5ca95c 100644
--- a/pageserver/src/disk_usage_eviction_task.rs
+++ b/pageserver/src/disk_usage_eviction_task.rs
@@ -1,5 +1,7 @@
 //! This module implements the pageserver-global disk-usage-based layer eviction task.
 //!
+//! # Mechanics
+//!
 //! Function `launch_disk_usage_global_eviction_task` starts a pageserver-global background
 //! loop that evicts layers in response to a shortage of available bytes
 //! in the $repo/tenants directory's filesystem.
@@ -13,6 +15,8 @@
 //! We're good if that second statvfs shows that we're _actually_ below the configured thresholds.
 //! If we're still above one or more thresholds, we emit a warning log message, leaving it to the operator to investigate further.
 //!
+//! # Eviction Policy
+//!
 //! There are two thresholds:
 //! `max_usage_pct` is the relative available space, expressed in percent of the total filesystem space.
 //! If the actual usage is higher, the threshold is exceeded.