Document the new rebuildInstallPlan return type

Author: dcoutts

cabal-install/Distribution/Client/ProjectPlanning.hs

@@ -231,13 +231,27 @@ sanityCheckElaboratedConfiguredPackage sharedConfig
 -- * Deciding what to do: making an 'ElaboratedInstallPlan'
 ------------------------------------------------------------------------------
 
+-- | Return an up-to-date elaborated install plan and associated config.
+--
+-- Two variants of the install plan are returned: with and without packages
+-- from the store. That is, the \"improved\" plan where source packages are
+-- replaced by pre-existing installed packages from the store (when their ids
+-- match), and also the original elaborated plan which uses primarily source
+-- packages.
+
+-- The improved plan is what we use for building, but the original elaborated
+-- plan is useful for reporting and configuration. For example the @freeze@
+-- command needs the source package info to know about flag choices and
+-- dependencies of executables and setup scripts.
+--
 rebuildInstallPlan :: Verbosity
                    -> FilePath -> DistDirLayout -> CabalDirLayout
                    -> ProjectConfig
-                   -> IO ( ElaboratedInstallPlan
-                         , ElaboratedInstallPlan
+                   -> IO ( ElaboratedInstallPlan  -- with store packages
+                         , ElaboratedInstallPlan  -- with source packages
                          , ElaboratedSharedConfig
                          , ProjectConfig )
+                      -- ^ @(improvedPlan, elaboratedPlan, _, _)@
 rebuildInstallPlan verbosity
                    projectRootDir
                    distDirLayout@DistDirLayout {