diff --git a/shell.nix b/shell.nix
index 0c43c99..b479cd5 100644
--- a/shell.nix
+++ b/shell.nix
@@ -1,5 +1,23 @@
+# shell.nix
+#
+# Prepare a Nix shell with GINsim available.
+#
+# Use nix-shell or nix-shell shell.nix to start.
+
+# The with statement imports the nixpkgs namespace, so the tools like
+# stdenv and callPackage become available.
 with import <nixpkgs> {};
 stdenv.mkDerivation {
   name = "GINsim-shell";
+
+  # Bring the package defined in ginsim.nix in scope.  buildInputs is
+  # therefore a one-element list.  Its only element is the call of the
+  # anonymous function defined in ginsim.nix.  I could have used let
+  # to define a local binding ginsim = callPackage ./ginsim.nix {}; to
+  # explicitly bind a name to this function call.
+  #
+  # callPackage can also be replaced by import.  In this case, the
+  # arguments of the anonymous function defined in ginsim.nix get
+  # their respective default values.
   buildInputs = [ (callPackage ./ginsim.nix {}) ];
 }