Add comments

src/Shrun/Configuration/Data/CmdLogging.hs

@@ -29,6 +29,7 @@ import Shrun.Data.Truncation
   )
 import Shrun.Prelude
 
+-- Cmd log line truncation is truly optional, the default being none.
 type CmdLogLineTruncF :: ConfigPhase -> Type
 type family CmdLogLineTruncF p where
   CmdLogLineTruncF ConfigPhaseArgs = WithDisable (Maybe LineTruncation)

src/Shrun/Configuration/Data/Core.hs

@@ -39,6 +39,7 @@ data CoreConfigP p = MkCoreConfigP
     -- | How often to poll commands for logs, in microseconds.
     pollInterval :: ConfigPhaseF p PollInterval,
     -- | Determines the max log size we read from commands in one go.
+    -- Note this is not on cmdLogging or fileLogging since it affects both.
     cmdLogSize :: ConfigPhaseF p (Bytes B Natural),
     -- | How to format the timer.
     timerFormat :: ConfigPhaseF p TimerFormat,

src/Shrun/Configuration/Data/FileLogging.hs

@@ -25,6 +25,25 @@ import Shrun.Data.FileSizeMode (FileSizeMode, defaultFileSizeMode)
 import Shrun.Data.StripControl (StripControl (StripControlAll))
 import Shrun.Prelude
 
+-- NOTE: [Args vs. Toml mandatory fields]
+--
+-- Some fields are mandatory e.g. FileLogging's path if we are actually
+-- doing file logging. The latter is determined by the FileLoggingP itself
+-- being Just (cf. Nothing), thus the path itself is mandatory on Toml and
+-- Merged.
+--
+-- So why is it optional on Args? Because Args' FileLoggingP is _always_
+-- present, unlike Toml and Merged's Maybe. We need this behavior because the
+-- former's fields can be used to override toml fields, even if file-logging is
+-- not specified on the CLI.
+--
+-- For example, 'shrun --file-log-mode write cmd' _should_ overwrite toml's
+-- file-log.mode even though we did not specify --file-log. Therefore Args'
+-- FileLoggingP always needs to be present hence all its field must be
+-- optional, even when some are mandatory on Merged.
+
+-- File logging's path is only optional for the Args. For Toml and merged,
+-- it must be present if file logging is active.
 type FileLogPathF :: ConfigPhase -> Type
 type family FileLogPathF p where
   FileLogPathF ConfigPhaseArgs = WithDisable (Maybe FilePathDefault)

src/Shrun/Configuration/Data/Notify.hs

@@ -27,6 +27,10 @@ import Shrun.Notify.Types
   )
 import Shrun.Prelude
 
+-- Notify action is mandatory if we are running notifications.
+--
+-- See NOTE: [Args vs. Toml mandatory fields]
+
 type NotifyActionF :: ConfigPhase -> Type
 type family NotifyActionF p where
   NotifyActionF ConfigPhaseArgs = WithDisable (Maybe NotifyAction)