haskell: add more callPackageWithScope docs

pkgs/development/haskell-modules/make-package-set.nix

@@ -44,6 +44,11 @@ self: let
 
   mkDerivation = makeOverridable mkDerivationImpl;
 
+  # manualArgs are the arguments that were explictly passed to `callPackage`, like:
+  #
+  # callPackage foo { bar = null; };
+  #
+  # here `bar` is a manual argument.
   callPackageWithScope = scope: fn: manualArgs:
     let
       # this code is copied from callPackage in lib/customisation.nix
@@ -55,9 +60,16 @@ self: let
       # info that callPackage uses to determine the arguments).
       drv = if builtins.isFunction fn then fn else import fn;
       auto = builtins.intersectAttrs (builtins.functionArgs drv) scope;
+
+      # this wraps the `drv` function to add a `overrideScope` function to the result.
       drvScope = allArgs: drv allArgs // {
         overrideScope = f:
           let newScope = mkScope (fix' (extends f scope.__unfix__));
+          # note that we have to be careful here: `allArgs` includes the auto-arguments that
+          # weren't manually specified. If we would just pass `allArgs` to the recursive call here,
+          # then we wouldn't look up any packages in the scope in the next interation, because it
+          # appears as if all arguments were already manually passed, so the scope change would do
+          # nothing.
           in callPackageWithScope newScope drv manualArgs;
       };
     in stdenv.lib.makeOverridable drvScope (auto // manualArgs);