Add code documentation

Author: mpilgrem

src/Stack/Ghci.hs

@@ -182,6 +182,7 @@ data GhciPkgDesc = GhciPkgDesc
   { package :: !Package
   , cabalFP :: !(Path Abs File)
   , target :: !Target
+    -- ^ How the package is intended to be built.
   }
 
 -- | Type synonym representing maps from a module name to a map with all of the
@@ -292,15 +293,20 @@ ghci opts = do
     localTargets
     mainFile
     pkgs
+    -- Files targets with unknown GHC options:
     (maybe [] snd mfileTargets)
+    -- The names of packages to be exposed:
     (nonLocalTargets ++ addPkgs)
+    -- A map of package names and sequences of their sublibrary components
+    -- depended upon (if any):
     relevantDependencies
 
 preprocessTargets ::
      HasEnvConfig env
   => BuildOptsCLI
   -> SMActual GlobalPackage
   -> [Text]
+     -- ^ Raw (unprocessed) targets from the command line.
   -> RIO env (Either [Path Abs File] (Map PackageName Target))
 preprocessTargets buildOptsCLI sma rawTargets = do
   let (fileTargetsRaw, normalTargetsRaw) =
@@ -349,7 +355,12 @@ findFileTargets ::
      HasEnvConfig env
   => [LocalPackage]
   -> [Path Abs File]
-  -> RIO env (Map PackageName Target, Map PackageName [Path Abs File], [Path Abs File])
+  -> RIO
+       env
+       ( Map PackageName Target
+       , Map PackageName [Path Abs File]
+       , [Path Abs File]
+       )
 findFileTargets locals fileTargets = do
   filePackages <- forM locals $ \lp -> do
     PackageComponentFile _ compFiles _ _ <- getPackageFile lp.package lp.cabalFP
@@ -486,10 +497,17 @@ runGhci ::
   => GhciOpts
   -> [(PackageName, (Path Abs File, Target))]
   -> Maybe (Path Abs File)
+     -- ^ Path to source file for selected main module. 'Nothing' if no main
+     -- module is to be loaded and imported.
   -> [GhciPkgInfo]
   -> [Path Abs File]
+     -- ^ Files targets with unknown GHC options.
   -> [PackageName]
+     -- ^ The names of packages to be exposed.
   -> Map PackageName (Seq NamedComponent)
+     -- ^ A map of package names and their sublibraries depended on (if
+     -- any), the package names to be exposed if any sublibraries are
+     -- depended on.
   -> RIO env ()
 runGhci
     ghciOpts
@@ -650,8 +668,12 @@ writeHashedFile outputDirectory relFile contents = do
 renderScript ::
      [GhciPkgInfo]
   -> Maybe (Path Abs File)
+     -- ^ Path to source file for selected main module. 'Nothing' if no main
+     -- module is to be loaded and imported.
   -> Bool
+     -- ^ Only load and import the main module?
   -> [Path Abs File]
+     -- ^ Files targets with unknown GHC options.
   -> GhciScript
 renderScript pkgs mainFile onlyMain extraFiles = do
   let addPhase = cmdAdd $ S.fromList (map Left allModules ++ addMain)

src/Stack/Ghci/Script.hs

@@ -35,7 +35,15 @@ instance Monoid GhciScript where
 
 data GhciCommand
   = AddCmd (Set (Either ModuleName (Path Abs File)))
+    -- ^ Add the specified modules (specified by module name or source file) to
+    -- the current target set and perform a reload (that is, load the target set
+    -- of modules and the all the modules they depend on in dependency order).
+    -- The modules specified by name are added first (in ascending order), then
+    -- the modules specified by source file (in ascending order). The context is
+    -- set to the most recently successfully loaded module.
   | ModuleCmd (Set ModuleName)
+    -- ^ Add the specified modules to the context. The modules are added in
+    -- ascending order.
   deriving Show
 
 cmdAdd :: Set (Either ModuleName (Path Abs File)) -> GhciScript

src/Stack/Package.hs

@@ -818,6 +818,7 @@ setOfPackageDeps pkg = runIdentity $
 topSortPackageComponent ::
      Package
   -> Target
+     -- ^ How the package is intended to be built.
   -> Bool
      -- ^ Include directTarget or not. False here means we won't include the
      -- actual targets in the result, only their deps. Using it with False here
@@ -845,6 +846,7 @@ topProcessPackageComponent ::
      forall b.
      Package
   -> Target
+     -- ^ How the package is intended to be built.
   -> (    forall component. (HasComponentInfo component)
        => PackageType
        -> component

src/Stack/Types/GhciOpts.hs

@@ -20,6 +20,7 @@ import           Stack.Types.BuildOptsCLI ( ApplyCLIFlag (..) )
 -- commands.
 data GhciOpts = GhciOpts
   { targets            :: ![Text]
+    -- ^ Raw (unprocessed) targets from the command line.
   , args               :: ![String]
   , ghcOptions         :: ![String]
   , flags              :: !(Map ApplyCLIFlag (Map FlagName Bool))
@@ -31,5 +32,6 @@ data GhciOpts = GhciOpts
   , hidePackages       :: !(Maybe Bool)
   , noBuild            :: !Bool
   , onlyMain           :: !Bool
+    -- ^ Only load and import the main module?
   }
   deriving Show