Move types into own modules, for consistency

Also adds missing Haddock documentation.

Author: mpilgrem

package.yaml

@@ -317,10 +317,12 @@ library:
   - Stack.Types.GhcPkgId
   - Stack.Types.GlobalOpts
   - Stack.Types.GlobalOptsMonoid
+  - Stack.Types.HpcReportOpts
   - Stack.Types.Installed
   - Stack.Types.InterfaceOpt
   - Stack.Types.IsMutable
   - Stack.Types.LockFileBehavior
+  - Stack.Types.LsOpts
   - Stack.Types.MsysEnvironment
   - Stack.Types.NamedComponent
   - Stack.Types.Nix

src/Stack/Build/ExecutePackage.hs

@@ -347,22 +347,24 @@ announceTask ee taskType action = logInfo $
        (packageNamePrefix ee (pkgName (taskTypePackageIdentifier taskType)))
   <> action
 
--- Implements running a package's build, used to implement 'ATBuild' and
--- 'ATBuildFinal' tasks.  In particular this does the following:
+-- | Implements running a package's build, used to implement
+-- 'Control.Concurrent.Execute.ATBuild' and
+-- 'Control.Concurrent.Execute.ATBuildFinal' tasks. In particular this does the
+-- following:
 --
--- * Checks if the package exists in the precompiled cache, and if so,
---   add it to the database instead of performing the build.
+-- * 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 build step
 --
 -- * Generates haddocks
 --
--- * Registers the library and copies the built executables into the
---   local install directory. Note that this is literally invoking Cabal
---   with @copy@, and not the copying done by @stack install@ - that is
---   handled by 'copyExecutables'.
+-- * Registers the library and copies the built executables into the local
+--   install directory. Note that this is literally invoking Cabal with @copy@,
+--   and not the copying done by @stack install@ - that is handled by
+--   'Stack.Build.copyExecutables'.
 singleBuild ::
      forall env. (HasEnvConfig env, HasRunner env)
   => ActionContext

src/Stack/Coverage.hs

@@ -14,12 +14,10 @@ Generate HPC (Haskell Program Coverage) reports.
 -}
 
 module Stack.Coverage
-  ( HpcReportOpts (..)
-  , hpcReportCmd
+  ( hpcReportCmd
   , deleteHpcReports
   , updateTixFile
   , generateHpcReport
-  , generateHpcReportForTargets
   , generateHpcUnifiedReport
   , generateHpcMarkupIndex
   ) where
@@ -67,6 +65,7 @@ import           Stack.Types.BuildOptsCLI
                    ( BuildOptsCLI (..), defaultBuildOptsCLI )
 import           Stack.Types.EnvConfig
                    ( EnvConfig (..), HasEnvConfig (..), hpcReportDir )
+import           Stack.Types.HpcReportOpts ( HpcReportOpts (..) )
 import           Stack.Types.NamedComponent ( NamedComponent (..) )
 import           Stack.Types.Package ( Package (..), packageIdentifier )
 import           Stack.Types.Runner ( Runner )
@@ -112,15 +111,6 @@ instance Pretty CoveragePrettyException where
 
 instance Exception CoveragePrettyException
 
--- | Type representing command line options for the @stack hpc report@ command.
-data HpcReportOpts = HpcReportOpts
-  { inputs :: [Text]
-  , all :: Bool
-  , destDir :: Maybe String
-  , openBrowser :: Bool
-  }
-  deriving Show
-
 -- | Function underlying the @stack hpc report@ command.
 hpcReportCmd :: HpcReportOpts -> RIO Runner ()
 hpcReportCmd hropts = do
@@ -431,6 +421,7 @@ generateHpcReportForTargets opts tixFiles targetNames = do
         void $ liftIO $ openBrowser (toFilePath reportPath)
       else displayReportPath "The" report (pretty reportPath)
 
+-- | Generates the HTML unified coverage report.
 generateHpcUnifiedReport :: HasEnvConfig env => RIO env ()
 generateHpcUnifiedReport = do
   outputDir <- hpcReportDir
@@ -528,6 +519,7 @@ unionTixes tixes = (Map.keys errs, Tix (Map.elems outputs))
         Right (TixModule k hash1 len1 (zipWith (+) tix1 tix2))
   merge _ _ = Left ()
 
+-- | Generates the HTML index report.
 generateHpcMarkupIndex :: HasEnvConfig env => RIO env ()
 generateHpcMarkupIndex = do
   outputDir <- hpcReportDir

src/Stack/IDE.hs

@@ -37,15 +37,15 @@ import           Stack.Types.SourceMap
                    ( ProjectPackage (..), SMWanted (..), ppComponentsMaybe )
 import           System.IO ( putStrLn )
 
--- Type representing output stream choices for the @stack ide packages@ and
+-- | Type representing output stream choices for the @stack ide packages@ and
 -- @stack ide targets@ commands.
 data OutputStream
   = OutputLogInfo
     -- ^ To the same output stream as other log information.
   | OutputStdout
     -- ^ To the standard output stream.
 
--- Type representing output choices for the @stack ide packages@ command.
+-- | Type representing output choices for the @stack ide packages@ command.
 data ListPackagesCmd
   = ListPackageNames
     -- ^ Package names.

src/Stack/Ls.hs

@@ -12,18 +12,7 @@ Types and functions related to Stack's @ls@ command.
 -}
 
 module Stack.Ls
-  ( LsCmdOpts (..)
-  , LsCmds (..)
-  , SnapshotOpts (..)
-  , LsView (..)
-  , ListDepsOpts (..)
-  , ListDepsFormat (..)
-  , ListDepsFormatOpts (..)
-  , ListDepsTextFilter (..)
-  , ListGlobalsOpts (..)
-  , ListStylesOpts (..)
-  , ListToolsOpts (..)
-  , lsCmd
+  ( lsCmd
   ) where
 
 import           Control.Monad.Extra ( whenJust )
@@ -67,6 +56,13 @@ import           Stack.Types.DependencyTree
 import           Stack.Types.DotOpts ( DotOpts (..) )
 import           Stack.Types.DumpPackage ( DumpPackage (..) )
 import           Stack.Types.EnvConfig ( EnvConfig (..), installationRootDeps )
+import           Stack.Types.LsOpts
+                   ( LsCmdOpts (..), LsCmds (..), ListDepsFormat (..)
+                   , ListDepsFormatOpts (..), ListDepsOpts (..)
+                   , ListDepsTextFilter (..), ListGlobalsOpts (..)
+                   , ListStylesOpts (..), ListToolsOpts (..), LsView (..)
+                   , SnapshotOpts (..)
+                   )
 import           Stack.Types.Runner ( HasRunner, Runner, terminalL )
 import           Stack.Types.SourceMap ( SMWanted (..) )
 import           System.Console.ANSI.Codes
@@ -87,33 +83,6 @@ instance Exception LsException where
     ++ "Failure to parse values as a snapshot: "
     ++ show val
 
--- | Type representing command line options for the @stack ls@ command.
-newtype LsCmdOpts
-  = LsCmdOpts { lsCmds :: LsCmds }
-
--- | Type representing subcommands for the @stack ls@ command.
-data LsCmds
-  = LsSnapshot SnapshotOpts
-  | LsGlobals ListGlobalsOpts
-  | LsDependencies ListDepsOpts
-  | LsStyles ListStylesOpts
-  | LsTools ListToolsOpts
-
--- | Type representing command line options for the @stack ls snapshots@
--- command.
-data SnapshotOpts = SnapshotOpts
-  { viewType :: LsView
-  , ltsSnapView :: Bool
-  , nightlySnapView :: Bool
-  }
-  deriving (Eq, Ord, Show)
-
--- | Type representing subcommands for the @stack ls snapshots@ command.
-data LsView
-  = Local
-  | Remote
-  deriving (Eq, Ord, Show)
-
 -- | Type representing Stackage snapshot types.
 data SnapshotType
   = Lts
@@ -122,57 +91,6 @@ data SnapshotType
     -- ^ Stackage Nightly
   deriving (Eq, Ord, Show)
 
--- | Type representing command line options for the @stack ls globals@ command.
-newtype ListGlobalsOpts = ListGlobalsOpts
-  { globalHints :: Bool
-    -- ^ Use global hints instead of relying on an actual GHC installation.
-  }
-
--- | Type representing command line options for the @stack ls dependencies@
--- command.
-data ListDepsOpts = ListDepsOpts
-  { format :: !ListDepsFormat
-    -- ^ Format of printing dependencies
-  , dotOpts :: !DotOpts
-    -- ^ The normal dot options.
-  }
-
--- | Type representing formats for printing dependencies.
-data ListDepsFormat
-  = ListDepsText ListDepsFormatOpts [ListDepsTextFilter]
-  | ListDepsTree ListDepsFormatOpts
-  | ListDepsJSON
-  | ListDepsConstraints
-
--- | Type representing command line options for the @stack ls dependencies text@
--- command and similar @cabal@, @tree@ and @json@ commands.
-data ListDepsFormatOpts = ListDepsFormatOpts
-  { sep :: !Text
-    -- ^ Separator between the package name and details.
-  , license :: !Bool
-    -- ^ Print dependency licenses instead of versions.
-  }
-
--- | Type representing items to filter the results of @stack ls dependencies@.
-data ListDepsTextFilter
-  = FilterPackage PackageName
-    -- ^ Item is a package name.
-  | FilterLocals
-    -- ^ Item represents all project packages.
-
--- | Type representing command line options for the @stack ls stack-colors@ and
--- @stack ls stack-colours@ commands.
-data ListStylesOpts = ListStylesOpts
-  { basic   :: Bool
-  , sgr     :: Bool
-  , example :: Bool
-  }
-  deriving (Eq, Ord, Show)
-
--- | Type representing command line options for the @stack ls tools@ command.
-newtype ListToolsOpts
-  = ListToolsOpts { filter  :: String }
-
 data Snapshot = Snapshot
   { snapId :: Text
   , title :: Text

src/Stack/Options/HpcReportParser.hs

@@ -16,9 +16,9 @@ import           Options.Applicative
                    ( Parser, completer, help, long, metavar, strOption, switch )
 import           Options.Applicative.Builder.Extra
                    ( dirCompleter, fileExtCompleter, textArgument )
-import           Stack.Coverage ( HpcReportOpts (..) )
 import           Stack.Options.Completion ( targetCompleter )
 import           Stack.Prelude
+import           Stack.Types.HpcReportOpts ( HpcReportOpts (..) )
 
 -- | Parser for @stack hpc report@.
 hpcReportOptsParser :: Parser HpcReportOpts

src/Stack/Options/LsParser.hs

@@ -19,15 +19,15 @@ import qualified Options.Applicative as OA
 import           Options.Applicative ( idm )
 import           Options.Applicative.Builder.Extra ( boolFlags, textOption )
 import           Stack.Constants ( globalFooter )
-import           Stack.Ls
+import           Stack.Options.DotParser ( dotOptsParser )
+import           Stack.Prelude hiding ( sep )
+import           Stack.Types.LsOpts
                    ( ListDepsFormat (..), ListDepsFormatOpts (..)
                    , ListDepsOpts (..), ListDepsTextFilter (..)
                    , ListGlobalsOpts (..), ListStylesOpts (..)
                    , ListToolsOpts (..), LsCmdOpts (..), LsCmds (..)
                    , LsView (..), SnapshotOpts (..), ListGlobalsOpts
                    )
-import           Stack.Options.DotParser ( dotOptsParser )
-import           Stack.Prelude hiding ( sep )
 
 -- | Parse command line arguments for Stack's @ls@ command.
 lsOptsParser :: OA.Parser LsCmdOpts

src/Stack/Options/SetupParser.hs

@@ -19,7 +19,7 @@ import qualified Options.Applicative as OA
 import qualified Options.Applicative.Builder.Extra as OA
 import qualified Options.Applicative.Types as OA
 import           Stack.Prelude
-import           Stack.SetupCmd ( SetupCmdOpts (..) )
+import           Stack.Types.SetupOpts ( SetupCmdOpts (..) )
 
 -- | Parse command line arguments for Stack's @setup@ command.
 setupOptsParser :: OA.Parser SetupCmdOpts

src/Stack/Path.hs

@@ -14,7 +14,6 @@ Types and functions related to Stack's @path@ command.
 
 module Stack.Path
   ( EnvConfigPathInfo
-  , UseHaddocks
   , path
   , pathsFromRunner
   , pathsFromConfig
@@ -170,6 +169,8 @@ fillEnvConfigPathInfo = do
     , compiler
     }
 
+-- | Type representing information needed to generate an appropriate string for
+-- paths of interest to a user which require an 'EnvConfig'.
 data EnvConfigPathInfo = EnvConfigPathInfo
   { buildConfig  :: !BuildConfig
   , snapDb       :: !(Path Abs Dir)
@@ -240,7 +241,7 @@ pathsFromRunner = ("Global Stack root directory", stackRootOptionName')
 -- can choose a specific path to list like @--stack-root@. But really it's
 -- mainly for the documentation aspect.
 --
--- When printing output we generate @Config@ and pass it to the function
+-- When printing output we generate t'Config' and pass it to the function
 -- to generate an appropriate string. Trailing slashes are removed, see #506.
 pathsFromConfig :: [(String, Text, Config -> Text)]
 pathsFromConfig =
@@ -264,7 +265,7 @@ pathsFromConfig =
 -- can choose a specific path to list like @--project-root@. But really it's
 -- mainly for the documentation aspect.
 --
--- When printing output we generate @EnvConfigPathInfo@ and pass it to the
+-- When printing output we generate t'EnvConfigPathInfo' and pass it to the
 -- function to generate an appropriate string. Trailing slashes are removed, see
 -- #506.
 pathsFromEnvConfig :: [(String, Text, UseHaddocks (EnvConfigPathInfo -> Text))]

src/Stack/Setup.hs

@@ -624,6 +624,7 @@ defaultSetupInfoYaml :: String
 defaultSetupInfoYaml =
   "https://raw.githubusercontent.com/commercialhaskell/stackage-content/master/stack/stack-setup-2.yaml"
 
+-- | Type representing setup configurations.
 data SetupOpts = SetupOpts
   { installGhcIfMissing :: !Bool
   , installMsysIfMissing :: !Bool
@@ -2638,7 +2639,7 @@ utf8EnvVars =
 
 -- Binary Stack upgrades
 
--- | Information on a binary release of Stack
+-- | Information on a binary release of Stack.
 data StackReleaseInfo
   = SRIGitHub !Value
     -- ^ Metadata downloaded from GitHub releases about available binaries.
@@ -2651,11 +2652,14 @@ data HaskellStackOrg = HaskellStackOrg
   }
   deriving Show
 
+-- | Download information on a binary release of Stack. If there is no given
+-- GitHub user, GitHub repository and version, then first tries
+-- @haskellstack.org@.
 downloadStackReleaseInfo ::
      (HasLogFunc env, HasPlatform env)
-  => Maybe String -- GitHub org
-  -> Maybe String -- GitHub repo
-  -> Maybe String -- ^ optional version
+  => Maybe String -- ^ Optional GitHub user.
+  -> Maybe String -- ^ Optional GitHub repository.
+  -> Maybe String -- ^ Optional version.
   -> RIO env StackReleaseInfo
 downloadStackReleaseInfo Nothing Nothing Nothing = do
   platform <- view platformL
@@ -2762,6 +2766,9 @@ downloadStackReleaseInfoGitHub morg mrepo mver = liftIO $ do
     then pure $ SRIGitHub $ getResponseBody res
     else prettyThrowIO $ StackReleaseInfoNotFound url
 
+-- | Yield a list of the preferred GHC variants for the platform. The first item
+-- of each pair indicates if the operating system is Windows. The second item
+-- is the name of the GHC variant in Stack's @setup-info@ dictionary.
 preferredPlatforms ::
      (MonadReader env m, HasPlatform env, MonadThrow m)
   => m [(Bool, String)]
@@ -2790,6 +2797,7 @@ preferredPlatforms = do
         | otherwise = ["-static", ""]
   pure $ map (\suffix -> (isWindows, concat [os, "-", arch, suffix])) suffixes
 
+-- | Download a Stack executable.
 downloadStackExe ::
      HasConfig env
   => [(Bool, String)] -- ^ acceptable platforms
@@ -3000,6 +3008,7 @@ performPathChecking newExeFile currExeFile = do
                   <> flow "sudo file copy worked!"
         | otherwise -> throwM e
 
+-- | If available, yields the version of the given binary release of Stack.
 getDownloadVersion :: StackReleaseInfo -> Maybe Version
 getDownloadVersion (SRIGitHub val) = do
   Object o <- Just val