Update Haddock documentation related to building with Haddock

Author: mpilgrem

src/Stack/Build/ConstructPlan.hs

@@ -502,7 +502,13 @@ mkUnregisterLocal tasks dirtyReason localDumpPkgs initialBuildSteps =
 -- This will also add all the deps needed to build the tests / benchmarks. If
 -- @isAllInOne@ is 'True' (the common case), then all of these should have
 -- already been taken care of as part of the build step.
-addFinal :: LocalPackage -> Package -> Bool -> Bool -> M ()
+addFinal ::
+     LocalPackage
+  -> Package
+  -> Bool
+  -> Bool
+     -- ^ Should Haddock documentation be built?
+  -> M ()
 addFinal lp package isAllInOne buildHaddocks = do
   depsRes <- addPackageDeps package
   res <- case depsRes of
@@ -760,12 +766,14 @@ installPackage name ps minstalled = do
     pure $ Set.member name (curatorExpectTestFailure curator) ||
            Set.member name (curatorExpectBenchmarkFailure curator)
 
-resolveDepsAndInstall :: Bool
-                      -> Bool
-                      -> PackageSource
-                      -> Package
-                      -> Maybe Installed
-                      -> M (Either ConstructPlanException AddDepRes)
+resolveDepsAndInstall ::
+     Bool
+  -> Bool
+     -- ^ Should Haddock documentation be built?
+  -> PackageSource
+  -> Package
+  -> Maybe Installed
+  -> M (Either ConstructPlanException AddDepRes)
 resolveDepsAndInstall isAllInOne buildHaddocks ps package minstalled = do
   res <- addPackageDeps package
   case res of
@@ -778,15 +786,17 @@ resolveDepsAndInstall isAllInOne buildHaddocks ps package minstalled = do
 -- | Checks if we need to install the given 'Package', given the results
 -- of 'addPackageDeps'. If dependencies are missing, the package is dirty, or
 -- it's not installed, then it needs to be installed.
-installPackageGivenDeps :: Bool
-                        -> Bool
-                        -> PackageSource
-                        -> Package
-                        -> Maybe Installed
-                        -> ( Set PackageIdentifier
-                           , Map PackageIdentifier GhcPkgId
-                           , IsMutable )
-                        -> M AddDepRes
+installPackageGivenDeps ::
+     Bool
+  -> Bool
+     -- ^ Should Haddock documentation be built?
+  -> PackageSource
+  -> Package
+  -> Maybe Installed
+  -> ( Set PackageIdentifier
+     , Map PackageIdentifier GhcPkgId
+     , IsMutable )
+  -> M AddDepRes
 installPackageGivenDeps isAllInOne buildHaddocks ps package minstalled
   (missing, present, minMutable) = do
     let name = packageName package
@@ -1046,12 +1056,14 @@ addPackageDeps package = do
       HasLibraries _ -> True
       NoLibraries -> False
 
-checkDirtiness :: PackageSource
-               -> Installed
-               -> Package
-               -> Map PackageIdentifier GhcPkgId
-               -> Bool
-               -> M Bool
+checkDirtiness ::
+     PackageSource
+  -> Installed
+  -> Package
+  -> Map PackageIdentifier GhcPkgId
+  -> Bool
+     -- ^ Is Haddock documentation being built?
+  -> M Bool
 checkDirtiness ps installed package present buildHaddocks = do
   ctx <- ask
   moldOpts <- runRIO ctx $ tryGetFlagCache installed

src/Stack/SourceMap.hs

@@ -56,6 +56,7 @@ mkProjectPackage ::
   => PrintWarnings
   -> ResolvedPath Dir
   -> Bool
+     -- ^ Should Haddock documentation be built for the package?
   -> RIO env ProjectPackage
 mkProjectPackage printWarnings dir buildHaddocks = do
   (gpd, name, cabalfp) <-

src/Stack/Types/Package.hs

@@ -290,11 +290,11 @@ psVersion :: PackageSource -> Version
 psVersion (PSFilePath lp) = packageVersion $ lpPackage lp
 psVersion (PSRemote _ v _ _) = v
 
--- | Information on a locally available package of source code
+-- | Information on a locally available package of source code.
 data LocalPackage = LocalPackage
   { lpPackage       :: !Package
-     -- ^ The @Package@ info itself, after resolution with package flags,
-     -- with tests and benchmarks disabled
+     -- ^ The @Package@ info itself, after resolution with package flags, with
+     -- tests and benchmarks disabled
   , lpComponents    :: !(Set NamedComponent)
     -- ^ Components to build, not including the library component.
   , lpUnbuildable   :: !(Set NamedComponent)
@@ -304,11 +304,12 @@ data LocalPackage = LocalPackage
                              -- terminology, it's unclear
     -- ^ Whether this package is wanted as a target.
   , lpTestBench     :: !(Maybe Package)
-    -- ^ This stores the 'Package' with tests and benchmarks enabled, if
-    -- either is asked for by the user.
+    -- ^ This stores the 'Package' with tests and benchmarks enabled, if either
+    -- is asked for by the user.
   , lpCabalFile     :: !(Path Abs File)
     -- ^ The Cabal file
   , lpBuildHaddocks :: !Bool
+    -- ^ Is Haddock documentation being built for this package?
   , lpForceDirty    :: !Bool
   , lpDirtyFiles    :: !(MemoizedWith EnvConfig (Maybe (Set FilePath)))
     -- ^ Nothing == not dirty, Just == dirty. Note that the Set may be empty if

src/Stack/Types/SourceMap.hs

@@ -38,7 +38,8 @@ import           Stack.Prelude
 import           Stack.Types.Compiler ( ActualCompiler )
 import           Stack.Types.NamedComponent ( NamedComponent (..) )
 
--- | Common settings for both dependency and project package.
+-- | Settings common to dependency packages ('Stack.Types.SourceMap.DepPackage')
+-- and project packages ('Stack.Types.SourceMap.ProjectPackage').
 data CommonPackage = CommonPackage
   { cpGPD :: !(IO GenericPackageDescription)
   , cpName :: !PackageName
@@ -48,6 +49,7 @@ data CommonPackage = CommonPackage
     -- also lets us know if we're doing profiling
   , cpCabalConfigOpts :: ![Text]
   , cpHaddocks :: !Bool
+    -- ^ Should Haddock documentation be built for this package?
   }
 
 -- | Flag showing if package comes from a snapshot needed to ignore dependency
@@ -72,7 +74,7 @@ data DepPackage = DepPackage
 -- | A view of a project package needed for resolving components
 data ProjectPackage = ProjectPackage
   { ppCommon :: !CommonPackage
-  , ppCabalFP    :: !(Path Abs File)
+  , ppCabalFP :: !(Path Abs File)
   , ppResolvedDir :: !(ResolvedPath Dir)
   }