diff --git a/doc/stack_root.md b/doc/stack_root.md
index a39bb92732..52b9fc124c 100644
--- a/doc/stack_root.md
+++ b/doc/stack_root.md
@@ -221,6 +221,23 @@ that Stack uses to build the executable.
 If the contents of the directory are deleted, and Stack needs the executable,
 Stack will recreate them.
 
+The hash in the names of the source files is a hash of arguments passed to GHC
+when building the executable and the contents of the two source files.
+
+The content of the `setup-<hash>.hs` file is the familiar:
+
+~~~haskell
+import Distribution.Simple
+main = defaultMain
+~~~
+
+The content of the `setup-shim-<hash>.hs` file uses `main` except when the
+executable is called with arguments `repl` and `stack-initial-build-steps`. Then
+Stack makes use of Cabal's `defaultMainWithHooks` and `replHook` field to create
+the autogenerated files for every configured component; the `replHook` function
+is provided with the information that `initialBuildSteps` needs. Stack's
+`stack ghci` or `stack repl` commands call the executable with those arguments.
+
 ### `snapshots` directory
 
 This contains a directory for each snapshot that Stack creates when building