Move types relating to command line options into their own modules

Also adds some missing Haddock documentation.

Author: mpilgrem

package.yaml

@@ -335,13 +335,15 @@ library:
   - Stack.Types.PvpBounds
   - Stack.Types.Runner
   - Stack.Types.SCM
+  - Stack.Types.SDistOpts
   - Stack.Types.SetupInfo
   - Stack.Types.Snapshot
   - Stack.Types.SourceMap
   - Stack.Types.StackYamlLoc
   - Stack.Types.Storage
   - Stack.Types.TemplateName
   - Stack.Types.UnusedFlags
+  - Stack.Types.UpgradeOpts
   - Stack.Types.UploadOpts
   - Stack.Types.Version
   - Stack.Types.VersionedDownloadInfo

src/Stack/Build.hs

@@ -233,9 +233,11 @@ build msetLocalFiles = do
         sourceMap.targets.targets
         plan
 
+-- | Build one or more local targets.
 buildLocalTargets ::
      HasEnvConfig env
   => NonEmpty Text
+     -- ^ Local targets to build.
   -> RIO env (Either SomeException ())
 buildLocalTargets targets =
   tryAny $ withNewLocalBuildTargets (NE.toList targets) $ build Nothing
@@ -377,6 +379,7 @@ warnAboutSplitObjs bopts |  bopts.splitObjs =
     ]
 warnAboutSplitObjs _ = pure ()
 
+-- | Text warning about the experimental nature of Stack's @--split-objs@ flag.
 splitObjsWarning :: String
 splitObjsWarning =
   "Note that this feature is EXPERIMENTAL, and its behavior may be changed and \

src/Stack/Options/SDistParser.hs

@@ -18,7 +18,7 @@ import           Options.Applicative
                    )
 import           Options.Applicative.Builder.Extra ( boolFlags, dirCompleter )
 import           Stack.Prelude
-import           Stack.SDist ( SDistOpts (..) )
+import           Stack.Types.SDistOpts ( SDistOpts (..) )
 import           Stack.Options.PvpBoundsParser ( pvpBoundsParser )
 
 -- | Parse command line arguments for Stack's @sdist@ command.

src/Stack/Options/UpgradeParser.hs

@@ -5,7 +5,7 @@ Module      : Stack.Options.UpgradeParser
 Description : Parse arguments for Stack's @upgrade@ command.
 License     : BSD-3-Clause
 
-Functions to parse command line arguments for Stack's @upgrade@ command.
+Function to parse command line arguments for Stack's @upgrade@ command.
 -}
 
 module Stack.Options.UpgradeParser
@@ -18,7 +18,7 @@ import         Options.Applicative
                  )
 import         Options.Applicative.Builder.Extra ( boolFlags )
 import         Stack.Prelude
-import         Stack.Upgrade
+import         Stack.Types.UpgradeOpts
                  ( BinaryOpts (..), SourceOpts (..), UpgradeOpts (..) )
 
 -- | Parse command line arguments for Stack's @upgrade@ command.

src/Stack/SDist.hs

@@ -92,6 +92,7 @@ import           Stack.Types.Package
 import           Stack.Types.Platform ( HasPlatform (..) )
 import           Stack.Types.PvpBounds ( PvpBounds (..), PvpBoundsType (..) )
 import           Stack.Types.Runner ( HasRunner, Runner )
+import           Stack.Types.SDistOpts ( SDistOpts (..) )
 import           Stack.Types.SourceMap
                    ( CommonPackage (..), ProjectPackage (..), SMWanted (..)
                    , SourceMap (..), ppRoot
@@ -137,20 +138,6 @@ instance Pretty SDistPrettyException where
 
 instance Exception SDistPrettyException
 
--- | Type representing command line options for @stack sdist@ command.
-data SDistOpts = SDistOpts
-  { dirsToWorkWith :: [String]
-    -- ^ Directories to package
-  , pvpBounds :: Maybe PvpBounds
-    -- ^ PVP Bounds overrides
-  , ignoreCheck :: Bool
-    -- ^ Whether to ignore check of the package for common errors
-  , buildTarball :: Bool
-    -- ^ Whether to build the tarball
-  , tarPath :: Maybe FilePath
-    -- ^ Where to copy the tarball
-  }
-
 -- | Function underlying the @stack sdist@ command.
 sdistCmd :: SDistOpts -> RIO Runner ()
 sdistCmd sdistOpts =

src/Stack/Types/Build.hs

@@ -258,9 +258,13 @@ instance NFData (PrecompiledCache Abs)
 
 instance NFData (PrecompiledCache Rel)
 
+-- | Type representing treatments of GHC's informational messages during
+-- compilation when it evaluates Template Haskell code.
 data ExcludeTHLoading
   = ExcludeTHLoading
+    -- ^ Suppress the messages.
   | KeepTHLoading
+    -- ^ Do not suppress the messages.
 
 data ConvertPathsToAbsolute
   = ConvertPathsToAbsolute

src/Stack/Types/SDistOpts.hs

@@ -0,0 +1,31 @@
+{-# LANGUAGE NoImplicitPrelude     #-}
+{-# LANGUAGE NoFieldSelectors      #-}
+
+{-|
+Module      : Stack.Types.SDistOpts
+Description : Types related to Stack's @sdist@ command.
+License     : BSD-3-Clause
+
+Types related to Stack's @sdist@ command.
+-}
+
+module Stack.Types.SDistOpts
+  ( SDistOpts (..)
+  ) where
+
+import           Stack.Prelude
+import           Stack.Types.PvpBounds ( PvpBounds )
+
+-- | Type representing command line options for @stack sdist@ command.
+data SDistOpts = SDistOpts
+  { dirsToWorkWith :: [String]
+    -- ^ Directories to package
+  , pvpBounds :: Maybe PvpBounds
+    -- ^ PVP Bounds overrides
+  , ignoreCheck :: Bool
+    -- ^ Whether to ignore check of the package for common errors
+  , buildTarball :: Bool
+    -- ^ Whether to build the tarball
+  , tarPath :: Maybe FilePath
+    -- ^ Where to copy the tarball
+  }

src/Stack/Types/UpgradeOpts.hs

@@ -0,0 +1,46 @@
+{-# LANGUAGE NoImplicitPrelude #-}
+{-# LANGUAGE NoFieldSelectors  #-}
+
+{-|
+Module      : Stack.Types.UpgradeOpts
+Description : Types for command line options for Stack's @upgrade@ command.
+License     : BSD-3-Clause
+
+Types for command line options for Stack's @upgrade@ command.
+-}
+
+module Stack.Types.UpgradeOpts
+  ( UpgradeOpts (..)
+  , BinaryOpts (..)
+  , SourceOpts (..)
+  ) where
+
+import           Stack.Prelude
+
+-- | Type representing command line options for the @stack upgrade@ command.
+data UpgradeOpts = UpgradeOpts
+  { binary :: !(Maybe BinaryOpts)
+  , source :: !(Maybe SourceOpts)
+  }
+  deriving Show
+
+-- | Type representing options for upgrading Stack with a binary executable
+-- file.
+data BinaryOpts = BinaryOpts
+  { platform :: !(Maybe String)
+  , force :: !Bool
+    -- ^ Force a download, even if the downloaded version is older than what we
+    -- are.
+  , onlyLocalBin :: !Bool
+    -- ^ Only download to Stack's local binary directory.
+  , version :: !(Maybe String)
+    -- ^ Specific version to download
+  , gitHubOrg :: !(Maybe String)
+  , gitHubRepo :: !(Maybe String)
+  }
+  deriving Show
+
+-- | Type representing options for upgrading Stack from source code.
+newtype SourceOpts
+  = SourceOpts (Maybe (String, String)) -- repo and branch
+  deriving Show

src/Stack/Types/UploadOpts.hs

@@ -3,10 +3,10 @@
 
 {-|
 Module      : Stack.Types.UploadOpts
-Description : Types for command line options for the @stack upload@ command.
+Description : Types for command line options for Stack's @upload@ command.
 License     : BSD-3-Clause
 
-Types for command line options for the @stack upload@ command.
+Types for command line options for Stack's @upload@ command.
 -}
 
 module Stack.Types.UploadOpts

src/Stack/Upgrade.hs

@@ -5,18 +5,14 @@
 
 {-|
 Module      : Stack.Upgrade
-Description : Types and functions related to Stack's @upgrade@ command.
+Description : Function related to Stack's @upgrade@ command.
 License     : BSD-3-Clause
 
-Types and functions related to Stack's @upgrade@ command.
+Function related to Stack's @upgrade@ command.
 -}
 
 module Stack.Upgrade
-  ( UpgradeOpts (..)
-  , BinaryOpts (..)
-  , SourceOpts (..)
-  , upgradeCmd
-  , upgrade
+  ( upgradeCmd
   ) where
 
 import qualified Data.Text as T
@@ -41,6 +37,8 @@ import           Stack.Types.Config ( Config (..), HasConfig (..), buildOptsL )
 import           Stack.Types.GlobalOpts ( GlobalOpts (..) )
 import           Stack.Types.Runner ( Runner, globalOptsL )
 import           Stack.Types.StackYamlLoc ( StackYamlLoc (..) )
+import           Stack.Types.UpgradeOpts
+                   ( BinaryOpts (..), SourceOpts (..), UpgradeOpts (..) )
 import           System.Process ( rawSystem, readProcess )
 
 -- | Type representing \'pretty\' exceptions thrown by functions in the
@@ -93,34 +91,6 @@ instance Pretty UpgradePrettyException where
 
 instance Exception UpgradePrettyException
 
--- | Type representing options for upgrading Stack with a binary executable
--- file.
-data BinaryOpts = BinaryOpts
-  { platform :: !(Maybe String)
-  , force :: !Bool
-    -- ^ Force a download, even if the downloaded version is older than what we
-    -- are.
-  , onlyLocalBin :: !Bool
-    -- ^ Only download to Stack's local binary directory.
-  , version :: !(Maybe String)
-    -- ^ Specific version to download
-  , gitHubOrg :: !(Maybe String)
-  , gitHubRepo :: !(Maybe String)
-  }
-  deriving Show
-
--- | Type representing options for upgrading Stack from source code.
-newtype SourceOpts
-  = SourceOpts (Maybe (String, String)) -- repo and branch
-  deriving Show
-
--- | Type representing command line options for the @stack upgrade@ command.
-data UpgradeOpts = UpgradeOpts
-  { binary :: !(Maybe BinaryOpts)
-  , source :: !(Maybe SourceOpts)
-  }
-  deriving Show
-
 -- | Function underlying the @stack upgrade@ command.
 upgradeCmd :: UpgradeOpts -> RIO Runner ()
 upgradeCmd upgradeOpts = do