Merge pull request #6789 from commercialhaskell/config-cache-docs

Improve Haddock and code documentation

Author: mpilgrem

src/Stack/Build/Cache.hs

@@ -89,15 +89,15 @@ import           Stack.Types.SourceMap ( smRelDir )
 import           System.PosixCompat.Files
                    ( getFileStatus, modificationTime, setFileTimes )
 
--- | Directory containing files to mark an executable as installed
+-- | Directory containing files to mark an executable as installed.
 exeInstalledDir ::
      (HasEnvConfig env)
   => InstallLocation
   -> RIO env (Path Abs Dir)
 exeInstalledDir Snap = (</> relDirInstalledPackages) <$> installationRootDeps
 exeInstalledDir Local = (</> relDirInstalledPackages) <$> installationRootLocal
 
--- | Get all of the installed executables
+-- | Get all of the installed executables.
 getInstalledExes ::
      (HasEnvConfig env)
   => InstallLocation
@@ -115,7 +115,7 @@ getInstalledExes loc = do
     map (\x -> (pkgName x, [x])) $
     mapMaybe (parsePackageIdentifier . toFilePath . filename) files
 
--- | Mark the given executable as installed
+-- | Mark the given executable as installed.
 markExeInstalled ::
      (HasEnvConfig env)
   => InstallLocation
@@ -135,7 +135,7 @@ markExeInstalled loc ident = do
   -- and invalidate this file in getInstalledExes if they no longer exist
   writeBinaryFileAtomic fp "Installed"
 
--- | Mark the given executable as not installed
+-- | Mark the given executable as not installed.
 markExeNotInstalled ::
      (HasEnvConfig env)
   => InstallLocation
@@ -149,7 +149,9 @@ markExeNotInstalled loc ident = do
 buildCacheFile ::
      (HasEnvConfig env, MonadReader env m, MonadThrow m)
   => Path Abs Dir
+     -- ^ Package directory.
   -> NamedComponent
+     -- ^ Package component.
   -> m (Path Abs File)
 buildCacheFile dir component = do
   cachesDir <- buildCachesDir dir
@@ -162,7 +164,9 @@ buildCacheFile dir component = do
 tryGetBuildCache ::
      HasEnvConfig env
   => Path Abs Dir
+     -- ^ Package directory.
   -> NamedComponent
+     -- ^ Package component.
   -> RIO env (Maybe (Map FilePath FileCacheInfo))
 tryGetBuildCache dir component = do
   fp <- buildCacheFile dir component
@@ -171,27 +175,30 @@ tryGetBuildCache dir component = do
       decode = Yaml.decodeFileThrow (toFilePath fp)
   either (const Nothing) (Just . (.times)) <$> liftIO (tryAny decode)
 
--- | Try to read the dirtiness cache for the given package directory.
+-- | Try to read the Cabal configuration cache for the given package directory.
 tryGetConfigCache ::
      HasEnvConfig env
   => Path Abs Dir
+     -- ^ Package directory.
   -> RIO env (Maybe ConfigCache)
 tryGetConfigCache dir =
   loadConfigCache $ configCacheKey dir ConfigCacheTypeConfig
 
--- | Try to read the mod time of the Cabal file from the last build
+-- | Try to read the modification time of the Cabal file from the last build.
 tryGetCabalMod ::
      HasEnvConfig env
   => Path Abs Dir
+     -- ^ Package directory.
   -> RIO env (Maybe CTime)
 tryGetCabalMod dir = do
   fp <- toFilePath <$> configCabalMod dir
   tryGetFileMod fp
 
--- | Try to read the mod time of setup-config file from the last build
+-- | Try to read the modification time of setup-config file from the last build.
 tryGetSetupConfigMod ::
      HasEnvConfig env
   => Path Abs Dir
+     -- ^ Package directory.
   -> RIO env (Maybe CTime)
 tryGetSetupConfigMod dir = do
   fp <- toFilePath <$> configSetupConfigMod dir
@@ -202,7 +209,7 @@ tryGetFileMod fp =
   liftIO $ either (const Nothing) (Just . modificationTime) <$>
     tryIO (getFileStatus fp)
 
--- | Try to read the project root from the last build of a package
+-- | Try to read the project root from the last build of a package.
 tryGetPackageProjectRoot ::
      HasEnvConfig env
   => Path Abs Dir
@@ -220,17 +227,21 @@ tryReadFileBinary fp =
 writeBuildCache ::
      HasEnvConfig env
   => Path Abs Dir
+     -- ^ Package directory.
   -> NamedComponent
+     -- ^ Package component.
   -> Map FilePath FileCacheInfo -> RIO env ()
 writeBuildCache dir component times = do
   fp <- toFilePath <$> buildCacheFile dir component
   liftIO $ Yaml.encodeFile fp BuildCache { times = times }
 
--- | Write the dirtiness cache for this package's configuration.
+-- | Write the given Cabal configuration cache for the given package directory.
 writeConfigCache ::
      HasEnvConfig env
   => Path Abs Dir
+     -- ^ Package directory.
   -> ConfigCache
+     -- ^ Cabal configuration cache.
   -> RIO env ()
 writeConfigCache dir =
   saveConfigCache (configCacheKey dir ConfigCacheTypeConfig)
@@ -270,15 +281,21 @@ writePackageProjectRoot dir projectRoot = do
   fp <- configPackageProjectRoot dir
   writeBinaryFileAtomic fp (byteString projectRoot)
 
--- | Delete the caches for the project.
-deleteCaches :: HasEnvConfig env => Path Abs Dir -> RIO env ()
+-- | Delete the Cabal configuration cache for the given package directory.
+deleteCaches ::
+     HasEnvConfig env
+  => Path Abs Dir
+     -- ^ Package directory.
+  -> RIO env ()
 deleteCaches dir =
   {- FIXME confirm that this is acceptable to remove
   bfp <- buildCacheFile dir
   removeFileIfExists bfp
   -}
   deactiveConfigCache $ configCacheKey dir ConfigCacheTypeConfig
 
+-- | For the given installed item, yields the key used to retrieve a record from
+-- the library Cabal flag cache or executable Cabal flag cache.
 flagCacheKey :: (HasEnvConfig env) => Installed -> RIO env ConfigCacheKey
 flagCacheKey installed = do
   installationRoot <- installationRootLocal
@@ -289,7 +306,7 @@ flagCacheKey installed = do
     Executable ident -> pure $
       configCacheKey installationRoot (ConfigCacheTypeFlagExecutable ident)
 
--- | Loads the flag cache for the given installed extra-deps.
+-- | Loads the Cabal flag cache for the given installed extra-deps.
 tryGetFlagCache ::
      HasEnvConfig env
   => Installed
@@ -298,7 +315,7 @@ tryGetFlagCache gid = do
   key <- flagCacheKey gid
   loadConfigCache key
 
--- | Write the flag cache for the given installed extra-deps.
+-- | Write the Cabal flag cache for the given installed extra-deps.
 writeFlagCache ::
      HasEnvConfig env
   => Installed
@@ -313,17 +330,22 @@ successBS = "success"
 failureBS = "failure"
 unknownBS = "unknown"
 
--- | Status of a test suite
+-- | Status of test suite(s).
 data TestStatus
   = TSSuccess
+    -- ^ The test suite(s) succeeded.
   | TSFailure
+    -- ^ One or more test suites failed.
   | TSUnknown
+    -- ^ The outcome of the test suite(s) is unknown.
 
--- | Mark test suite status
+-- | Mark test suite status.
 setTestStatus ::
      HasEnvConfig env
   => Path Abs Dir
+     -- ^ Package directory.
   -> TestStatus
+     -- ^ The status of the test suite(s).
   -> RIO env ()
 setTestStatus dir status = do
   fp <- testSuccessFile dir
@@ -333,10 +355,11 @@ setTestStatus dir status = do
       TSFailure -> failureBS
       TSUnknown -> unknownBS
 
--- | Check if the test suite already passed
+-- | Check if the test suite(s) already passed.
 getTestStatus ::
      HasEnvConfig env
   => Path Abs Dir
+     -- ^ Package directory.
   -> RIO env TestStatus
 getTestStatus dir = do
   fp <- testSuccessFile dir

src/Stack/Build/ConstructPlan.hs

@@ -1082,7 +1082,15 @@ checkDirtiness ps installed package present buildHaddocks = do
       tell mempty { wDirty = Map.singleton package.name reason }
       pure True
 
-describeConfigDiff :: Config -> ConfigCache -> ConfigCache -> Maybe Text
+-- | If the new Cabal configuration cache is the same as the old, yields
+-- 'Nothing'. Otherwise yields 'Just' a textual explanation of how they differ.
+describeConfigDiff ::
+     Config
+  -> ConfigCache
+     -- ^ The old Cabal configuration cache.
+  -> ConfigCache
+     -- ^ The new Cabal configuration cache.
+  -> Maybe Text
 describeConfigDiff config old new
   | old.pkgSrc /= new.pkgSrc = Just $
       "switching from " <>

src/Stack/Build/ExecutePackage.hs

@@ -151,7 +151,7 @@ import           System.PosixCompat.Files
                    ( createLink, getFileStatus, modificationTime )
 import           System.Random ( randomIO )
 
--- | Generate the ConfigCache
+-- | Generate the t'ConfigCache' value.
 getConfigCache ::
      HasEnvConfig env
   => ExecuteEnv
@@ -257,15 +257,14 @@ ensureConfig newConfigCache pkgDir buildOpts announce cabal cabalFP task = do
           -- need proper hashes for package identifiers.
       then pure True
       else do
-        -- We can ignore the components portion of the config
-        -- cache, because it's just used to inform 'construct
-        -- plan that we need to plan to build additional
-        -- components. These components don't affect the actual
-        -- package configuration.
+        -- We can ignore the components field of the Cabal configuration cache,
+        -- because it is only used to inform 'construct plan' that we need to
+        -- plan to build additional components. These components don't affect
+        -- the Cabal configuration for the package.
         let ignoreComponents :: ConfigCache -> ConfigCache
             ignoreComponents cc = cc { ConfigCache.components = Set.empty }
-        -- Determine the old and new configuration in the local directory, to
-        -- determine if we need to reconfigure.
+        -- Determine the old and new Cabal configuration for the package
+        -- directory, to determine if we need to reconfigure.
         mOldConfigCache <- tryGetConfigCache pkgDir
 
         mOldCabalMod <- tryGetCabalMod pkgDir

src/Stack/Storage/Project.hs

@@ -9,10 +9,10 @@
 
 {-|
 Module      : Stack.Storage.Project
-Description : Work with SQLite DB for caches across a project.
+Description : Work with the SQLite database for a project's caches.
 License     : BSD-3-Clause
 
-Work with SQLite database used for caches across a single project.
+Work with the SQLite database used for a project's caches.
 -}
 
 module Stack.Storage.Project
@@ -51,6 +51,25 @@ import           Stack.Types.ConfigureOpts
 import           Stack.Types.GhcPkgId ( GhcPkgId )
 import           Stack.Types.Storage ( ProjectStorage (..) )
 
+-- Uses the Persistent entity syntax to generate entities for five tables in a
+-- SQLite database:
+--
+-- config_cache
+-- config_cache_dir_option
+-- config_cache_no_dir_option
+-- config_cache_dep
+-- config_cache_component
+--
+-- The ID column for each table is automatically generated.
+--
+-- The other tables have a foreign key referring to the config_cache table, via:
+--
+--   parent ConfigCacheParentId sql="config_cache_id" OnDeleteCascade
+--
+-- The tables have UNIQUE constraints on multiple columns.
+--
+-- Creates a function migrateAll to perform all migrations for the generated
+-- entities.
 share [ mkPersist sqlSettings
       , mkMigrate "migrateAll"
       ]
@@ -92,11 +111,14 @@ ConfigCacheComponent
   deriving Show
 |]
 
--- | Initialize the database.
+-- | Initialize the project database for caches.
 initProjectStorage ::
      HasLogFunc env
-  => Path Abs File -- ^ storage file
+  => Path Abs File
+     -- ^ The storage file.
   -> (ProjectStorage -> RIO env a)
+     -- ^ Action, given a SQL database connection to the project database for
+     -- caches.
   -> RIO env a
 initProjectStorage fp f = handleMigrationException $
   initStorage "Stack" migrateAll fp $ f . ProjectStorage
@@ -110,11 +132,19 @@ withProjectStorage inner = do
   storage <- view (buildConfigL . to (.projectStorage.projectStorage))
   withStorage_ storage inner
 
--- | Key used to retrieve configuration or flag cache
+-- | Type synonym representing keys used to retrieve a record from the Cabal
+-- configuration cache or the library or executable Cabal flag cache.
 type ConfigCacheKey = Unique ConfigCacheParent
 
--- | Build key used to retrieve configuration or flag cache
-configCacheKey :: Path Abs Dir -> ConfigCacheType -> ConfigCacheKey
+-- | For the given directory and type of cache, yields the key used to retrieve
+-- a record from the Cabal configuration cache or the library or executable
+-- Cabal flag cache.
+configCacheKey ::
+     Path Abs Dir
+     -- ^ Directory.
+  -> ConfigCacheType
+     -- ^ Type of cache.
+  -> ConfigCacheKey
 configCacheKey dir = UniqueConfigCacheParent (toFilePath dir)
 
 -- | Internal helper to read the t'ConfigCache'
@@ -150,7 +180,7 @@ readConfigCache (Entity parentId configCacheParent) = do
     , pathEnvVar
     }
 
--- | Load t'ConfigCache' from the database.
+-- | Load a t'ConfigCache' value from the project database for caches.
 loadConfigCache ::
      (HasBuildConfig env, HasLogFunc env)
   => ConfigCacheKey
@@ -164,7 +194,7 @@ loadConfigCache key =
             Just <$> readConfigCache parentEntity
         | otherwise -> pure Nothing
 
--- | Insert or update t'ConfigCache' to the database.
+-- | Insert or update a t'ConfigCache' value to the project database for caches.
 saveConfigCache ::
      (HasBuildConfig env, HasLogFunc env)
   => ConfigCacheKey

src/Stack/Storage/Util.hs

@@ -37,10 +37,16 @@ updateCollection ::
      , Foldable collection
      )
   => (collection rawValue -> collection rawValue -> ([Filter record], [value]))
+     -- ^ Function to yield items in old not in new, to delete, and values in
+     -- new not in old, to add, from the old and new collections of values.
   -> (value -> record)
+     -- ^ Function to yield new records from values in new not in old.
   -> [Filter record]
+     -- ^ Extra items to delete, if there are other items to delete.
   -> collection rawValue
+     -- ^ The old collection of values.
   -> collection rawValue
+     -- ^ The new collection of values.
   -> ReaderT backend m ()
 updateCollection fnDiffer recordCons extra old new =
   when (old /= new) $ do