diff --git a/build.rs b/build.rs
index 76367df0b..46d07742d 100644
--- a/build.rs
+++ b/build.rs
@@ -1,3 +1,10 @@
+/// This file customizes debug builds for Wrangler
+///
+/// 1) sets the debug flag for rustc so Wrangler can feature detect
+///    https://doc.rust-lang.org/cargo/reference/build-scripts.html#rustc-cfg
+/// 2) set the source directory for Wrangler so debug builds know where to
+///    look for wranglerjs source files
+///    https://doc.rust-lang.org/cargo/reference/build-scripts.html#cargorustc-envvarvalue
 use std::env;
 
 fn main() {