Merge pull request #6737 from commercialhaskell/haddock

Add missing Haddock documentation

Author: mpilgrem

src/Stack/Build/Cache.hs

@@ -259,7 +259,7 @@ writeSetupConfigMod dir (Just x) = do
   writeBinaryFileAtomic fp "Just used for its modification time"
   liftIO $ setFileTimes (toFilePath fp) x x
 
--- | See 'tryGetPackageProjectRoot'
+-- | See 'tryGetPackageProjectRoot'.
 writePackageProjectRoot ::
      HasEnvConfig env
   => Path Abs Dir
@@ -288,7 +288,7 @@ flagCacheKey installed = do
     Executable ident -> pure $
       configCacheKey installationRoot (ConfigCacheTypeFlagExecutable ident)
 
--- | Loads the flag cache for the given installed extra-deps
+-- | Loads the flag cache for the given installed extra-deps.
 tryGetFlagCache ::
      HasEnvConfig env
   => Installed
@@ -297,6 +297,7 @@ tryGetFlagCache gid = do
   key <- flagCacheKey gid
   loadConfigCache key
 
+-- | Write the flag cache for the given installed extra-deps.
 writeFlagCache ::
      HasEnvConfig env
   => Installed

src/Stack/Build/ExecutePackage.hs

@@ -355,7 +355,7 @@ announceTask ee taskType action = logInfo $
 -- * Checks if the package exists in the precompiled cache, and if so, add it to
 --   the database instead of performing the build.
 --
--- * Runs the configure step if needed ('ensureConfig')
+-- * Runs the configure step if needed (@ensureConfig@)
 --
 -- * Runs the build step
 --

src/Stack/Ghci.hs

@@ -186,8 +186,10 @@ data GhciPkgDesc = GhciPkgDesc
 
 -- | Type synonym representing maps from a module name to a map with all of the
 -- paths that use that name. Each of those paths is associated with a set of
--- components that contain it. The purpose of this complex structure is for use
--- in 'checkForDuplicateModules'.
+-- components that contain it.
+
+-- The purpose of this complex structure is for use in
+-- 'checkForDuplicateModules'.
 type ModuleMap =
   Map ModuleName (Map (Path Abs File) (Set (PackageName, NamedComponent)))
 

src/Stack/Lock.hs

@@ -57,6 +57,7 @@ instance Pretty LockPrettyException where
 
 instance Exception LockPrettyException
 
+-- | Type representing locked locations.
 data LockedLocation a b = LockedLocation
   { original :: a
   , completed :: b
@@ -90,6 +91,7 @@ instance FromJSON (WithJSONWarnings (Unresolved SingleRPLI)) where
       let withWarnings x = WithJSONWarnings x ws
       pure $ withWarnings $ SingleRPLI . NE.head <$> unresolvedRPLIs
 
+-- | Type representing the contents of lock files.
 data Locked = Locked
   { snapshotLocations :: [LockedLocation RawSnapshotLocation SnapshotLocation]
   , pkgImmutableLocations :: [LockedLocation RawPackageLocationImmutable PackageLocationImmutable]
@@ -127,10 +129,14 @@ loadYamlThrow parser path = do
         logJSONWarnings (toFilePath path) warnings
         pure res
 
+-- | Yields a t'Stack.Types.SourceMap.SMWanted' taking into account the relevant
+-- lock file, if one is applicable and it exists.
 lockCachedWanted ::
      (HasPantryConfig env, HasRunner env)
   => Path Abs File
+     -- ^ The relevant Stack project-level configuration file.
   -> RawSnapshotLocation
+     -- ^ The relevant snapshot.
   -> (  Map RawPackageLocationImmutable PackageLocationImmutable
      -> WantedCompiler
      -> Map PackageName (Bool -> RIO env DepPackage)

src/Stack/Path.hs

@@ -14,6 +14,7 @@ Types and functions related to Stack's @path@ command.
 
 module Stack.Path
   ( EnvConfigPathInfo
+  , UseHaddocks
   , path
   , pathsFromRunner
   , pathsFromConfig
@@ -223,9 +224,12 @@ instance HasBuildConfig EnvConfigPathInfo where
   buildConfigL =
     lens (.buildConfig) (\x y -> x { buildConfig = y }) . buildConfigL
 
+-- | Type representing whether or not building Haddocks is required.
 data UseHaddocks a
   = UseHaddocks a
+    -- ^ Building Haddocks is required.
   | WithoutHaddocks a
+    -- ^ Building Haddocks is not required.
 
 -- | The paths of interest to a user which do require a t'Config' or
 -- 'EnvConfig'. The first tuple string is used for a description that the

src/Stack/SourceMap.hs

@@ -16,7 +16,6 @@ module Stack.SourceMap
   , getPLIVersion
   , loadGlobalHints
   , actualFromGhc
-  , actualFromHints
   , globalCondCheck
   , pruneGlobals
   , globalsFromHints
@@ -39,7 +38,7 @@ import           Stack.Constants ( stackProgName' )
 import           Stack.PackageDump ( conduitDumpPackage, ghcPkgDump )
 import           Stack.Prelude
 import           Stack.Types.Compiler
-                   ( ActualCompiler, actualToWanted, wantedToActual )
+                   ( ActualCompiler, wantedToActual )
 import           Stack.Types.CompilerPaths
                    ( CompilerPaths (..), GhcPkgExe, HasCompiler (..) )
 import           Stack.Types.Config ( HasConfig )
@@ -112,6 +111,8 @@ additionalDepPackage buildHaddocks location = do
           }
     }
 
+-- | Given a t'PackageName' and its t'SnapshotPackage', yields the corresponding
+-- t'DepPackage'.
 snapToDepPackage ::
      forall env. (HasPantryConfig env, HasLogFunc env, HasProcessContext env)
   => Bool
@@ -136,16 +137,22 @@ snapToDepPackage buildHaddocks name sp = do
           }
     }
 
+-- | For the given t'CommonPackage', load its generic package description and
+-- yield its version.
 loadVersion :: MonadIO m => CommonPackage -> m Version
 loadVersion common = do
   gpd <- liftIO common.gpd
-  pure (pkgVersion $ PD.package $ PD.packageDescription gpd)
+  pure gpd.packageDescription.package.pkgVersion
 
+-- | For the given t'PackageLocationImmutable', yield the version of the
+-- referenced package.
 getPLIVersion :: PackageLocationImmutable -> Version
 getPLIVersion (PLIHackage (PackageIdentifier _ v) _ _) = v
 getPLIVersion (PLIArchive _ pm) = pkgVersion $ pmIdent pm
 getPLIVersion (PLIRepo _ pm) = pkgVersion $ pmIdent pm
 
+-- | For the given @ghc-pkg@ executable, yield the contents of the global
+-- package database.
 globalsFromDump ::
      (HasProcessContext env, HasTerm env)
   => GhcPkgExe
@@ -157,21 +164,24 @@ globalsFromDump pkgexe = do
         Map.fromList $ map (pkgName . (.packageIdent) &&& id) $ Map.elems ds
   toGlobals <$> ghcPkgDump pkgexe [] pkgConduit
 
+-- | For the given wanted compiler, yield the global hints (if available).
 globalsFromHints ::
      HasConfig env
   => WantedCompiler
   -> RIO env (Map PackageName Version)
-globalsFromHints compiler = do
-  mglobalHints <- loadGlobalHints compiler
-  case mglobalHints of
-    Just hints -> pure hints
-    Nothing -> do
+globalsFromHints compiler = loadGlobalHints compiler >>= maybe
+  ( do
       prettyWarnL
         [ flow "Unable to load global hints for"
         , fromString $ T.unpack $ textDisplay compiler
         ]
       pure mempty
+  )
+  pure
 
+-- | When the environment 'HasCompiler', for the
+-- given t'Stack.Types.SourceMap.SMWanted' and 'ActualCompiler', yield
+-- a t'SMActual' parameterised by t'DumpedGlobalPackage'.
 actualFromGhc ::
      (HasConfig env, HasCompiler env)
   => SMWanted
@@ -187,21 +197,6 @@ actualFromGhc smw compiler = do
       , globals
       }
 
-actualFromHints ::
-     (HasConfig env)
-  => SMWanted
-  -> ActualCompiler
-  -> RIO env (SMActual GlobalPackageVersion)
-actualFromHints smw compiler = do
-  globals <- globalsFromHints (actualToWanted compiler)
-  pure
-    SMActual
-      { compiler
-      , project = smw.project
-      , deps = smw.deps
-      , globals = Map.map GlobalPackageVersion globals
-      }
-
 -- | Simple cond check for boot packages - checks only OS and Arch
 globalCondCheck ::
      (HasConfig env)
@@ -214,9 +209,12 @@ globalCondCheck = do
       condCheck c = Left c
   pure condCheck
 
+-- | Prune the given packages from GHC's global package database.
 pruneGlobals ::
      Map PackageName DumpedGlobalPackage
+     -- ^ Packages in GHC's global package database.
   -> Set PackageName
+     -- ^ Package names to prune.
   -> Map PackageName GlobalPackage
 pruneGlobals globals deps =
   let (prunedGlobals, keptGlobals) =
@@ -225,9 +223,12 @@ pruneGlobals globals deps =
   in  Map.map (GlobalPackage . pkgVersion . (.packageIdent)) keptGlobals <>
       Map.map ReplacedGlobalPackage prunedGlobals
 
+-- | Get the output of @ghc --info@ for the compiler in the environment.
 getCompilerInfo :: (HasConfig env, HasCompiler env) => RIO env Builder
 getCompilerInfo = view $ compilerPathsL . to (byteString . (.ghcInfo))
 
+-- | For the given 'PackageLocationImmutable', yield its 256-bit cryptographic
+-- hash.
 immutableLocSha :: PackageLocationImmutable -> Builder
 immutableLocSha = byteString . treeKeyToBs . locationTreeKey
  where
@@ -236,9 +237,13 @@ immutableLocSha = byteString . treeKeyToBs . locationTreeKey
   locationTreeKey (PLIRepo _ pm) = pmTreeKey pm
   treeKeyToBs (TreeKey (BlobKey sha _)) = SHA256.toHexBytes sha
 
+-- | Type synonym for functions that yield a t'SMActual' parameterised by
+-- t'GlobalPackageVersion' for a given list of project package directories.
 type SnapshotCandidate env
   = [ResolvedPath Dir] -> RIO env (SMActual GlobalPackageVersion)
 
+-- | For the given raw snapshot location, yield a function to yield a
+-- t'SMActual' from a list of project package directories.
 loadProjectSnapshotCandidate ::
      (HasConfig env)
   => RawSnapshotLocation