Merge pull request #6732 from commercialhaskell/refactor

Author: mpilgrem

src/Stack/Build/Installed.hs

@@ -44,6 +44,9 @@ import           Stack.Types.Installed
 import           Stack.Types.SourceMap
                    ( DepPackage (..), ProjectPackage (..), SourceMap (..) )
 
+-- | For the given t'SourceMap', yield a dictionary of package names for a
+-- project's packages and dependencies, and pairs of their relevant database
+-- (write-only or mutable) and package versions.
 toInstallMap :: MonadIO m => SourceMap -> m InstallMap
 toInstallMap sourceMap = do
   projectInstalls <-

src/Stack/Build/Target.hs

@@ -64,7 +64,6 @@ module Stack.Build.Target
   ( -- * Types
     Target (..)
   , NeedTargets (..)
-  , PackageType (..)
   , parseTargets
     -- * Convenience helpers
   , gpdVersion
@@ -245,6 +244,7 @@ parseRawTarget t =
 -- Resolve the raw targets
 --------------------------------------------------------------------------------
 
+-- | A type representing results of resolving a raw target.
 data ResolveResult = ResolveResult
   { name :: !PackageName
   , rawInput :: !RawInput
@@ -559,10 +559,13 @@ combineResolveResults results = do
 -- OK, let's do it!
 --------------------------------------------------------------------------------
 
+-- | Parse targets and dependencies from the given command line arguments and
+-- source map.
 parseTargets ::
      HasBuildConfig env
   => NeedTargets
   -> Bool
+     -- ^ Should Haddock documentation be built for the package?
   -> BuildOptsCLI
   -> SMActual GlobalPackage
   -> RIO env SMTargets

src/Stack/BuildPlan.hs

@@ -20,7 +20,6 @@ module Stack.BuildPlan
   , DepErrors
   , removeSrcPkgDefaultFlags
   , selectBestSnapshot
-  , showItems
   ) where
 
 import qualified Data.Foldable as F
@@ -194,8 +193,8 @@ gpdPackageDeps gpd compilerVersion platform flags =
     , platform
     }
 
--- Remove any src package flags having default values
--- Remove any package entries with no flags set
+-- | For the given list of packages and dictionary of packages and Cabal flags,
+-- remove flags that have defaults and packages with no remaining flags.
 removeSrcPkgDefaultFlags ::
      [C.GenericPackageDescription]
   -> Map PackageName (Map FlagName Bool)
@@ -210,12 +209,8 @@ removeSrcPkgDefaultFlags gpds flags =
     in  Just $ Map.differenceWith diff f1 f2
 
   gpdDefaultFlags gpd =
-    let tuples = map getDefault (C.genPackageFlags gpd)
-    in  Map.singleton (gpdPackageName gpd) (Map.fromList tuples)
-
-  getDefault f
-    | C.flagDefault f = (C.flagName f, True)
-    | otherwise       = (C.flagName f, False)
+    let pairs = map (C.flagName &&& C.flagDefault) (C.genPackageFlags gpd)
+    in  Map.singleton (gpdPackageName gpd) (Map.fromList pairs)
 
 -- | Find the set of @FlagName@s necessary to get the given
 -- @GenericPackageDescription@ to compile against the given @BuildPlan@. Will
@@ -305,11 +300,17 @@ checkPackageDeps myName deps packages =
             , neededBy = Map.singleton myName range
             }
 
+-- | A type synoynm for a dictionary of packages and failures to satisfy
+-- packages' dependency constraints.
 type DepErrors = Map PackageName DepError
 
+-- | A type representing failures to satisfy packages' dependency constraints.
 data DepError = DepError
   { version :: !(Maybe Version)
+    -- ^ If available, the available version of the package.
   , neededBy :: !(Map PackageName VersionRange)
+    -- ^ A dictionary of the packages requiring the package and the permitted
+    -- range of versions.
   }
   deriving Show
 
@@ -344,6 +345,8 @@ checkBundleBuildPlan platform compiler pool flags gpds =
 
   dupError _ _ = impureThrow DuplicatePackagesBug
 
+-- | A type representing the results of evaluating how well a snapshot satisfies
+-- the dependencies of a set of packages and a set of Cabal flags.
 data BuildPlanCheck
   = BuildPlanCheckOk (Map PackageName (Map FlagName Bool))
   | BuildPlanCheckPartial (Map PackageName (Map FlagName Bool)) DepErrors

src/Stack/Package.hs

@@ -828,11 +828,11 @@ topSortPackageComponent package target includeDirectTarget =
     | not includeDirectTarget && packageType == PTProject = id
     | otherwise = \v -> v |> component.qualifiedName
 
--- | Process a package's internal components in the order of their topological sort.
--- The first iteration will effect the component depending on no other component etc,
--- iterating by increasing amount of required dependencies.
--- 'PackageType' with value 'PTProject' here means the component is a direct target
--- and 'PTDependency' means it's a dependency of a direct target.
+-- | Process a package's internal components in the order of their topological
+-- sort. The first iteration will effect the component depending on no other
+-- component etc, iterating by increasing amount of required dependencies.
+-- 'PackageType' with value 'PTProject' here means the component is a direct
+-- target and 'PTDependency' means it's a dependency of a direct target.
 topProcessPackageComponent ::
      forall b.
      Package

src/Stack/Types/SourceMap.hs

@@ -111,7 +111,12 @@ data Target
   | TargetComps !(Set NamedComponent)
     -- ^ Only build specific components
 
-data PackageType = PTProject | PTDependency
+-- | A type representing types of packages.
+data PackageType
+  = PTProject
+    -- ^ The package is a project package.
+  | PTDependency
+    -- ^ The package is other than a project package and a dependency.
   deriving (Eq, Show)
 
 -- | A source map with information on the wanted (but not actual) compiler. This