Expand comment

overlays/cabal-pkg-config.nix

@@ -1,10 +1,32 @@
 final: prev:
 {
-  # This is a wrapper for `cabal configure` use only.  It returns
-  # package names and versions based on lib/pkgconf-nixpkgs-map.nix.
-  # It works because cabal calls `--list-all` then passes all the
-  # packages returned by that to `--modversion`.
-  # If that ever changes we will need to update this wrapper!
+  # This is a wrapper for `cabal configure` use only.
+  #
+  # When creating a plan for building a project cabal first
+  # runs `pkg-config --list-all` for a list of all the available
+  # packages installed on the system.
+  #
+  # It then gets the corresponding versions by passing that list
+  # on the command line to `pkg-config --modversion`.
+  #
+  # This gives cabal a full picture of what versions are available
+  # when building the plan.
+  #
+  # When we run `cabal configure` in `lib/call-cabal-project-to-nix.nix`
+  # we do not want to depend on every pkg-config package in `nixpkgs`
+  # that could be used.  We also do not want the user to have to specify
+  # every pkg-config package that their project requires.
+  #
+  # Instead this wrapper provides a list based on the contents
+  # of `lib/pkgconf-nixpkgs-map.nix`.  To avoid depending
+  # on the packages it gets the versions for `--modversions` from
+  # the `.version` attribute of the derivation.
+  #
+  # In most cases this `.version` will be suitable, however there
+  # are some packages where that is not the case.  If these cause
+  # issues we should first try to fix `lib/pkgconf-nixpkgs-map.nix`
+  # or the package.  If that does not work we may need a way to include
+  # overrides here.
   allPkgConfigWrapper =
     let
       pkgconfigPkgs =