core: improve haddocks for Build, use trailing haddocks for records

hnix-store-core/src/System/Nix/Build.hs

@@ -18,23 +18,24 @@ import GHC.Generics (Generic)
 -- Keep the order of these Enums to match enums from reference implementations
 -- src/libstore/store-api.hh
 data BuildMode
-  = BuildMode_Normal
-  | BuildMode_Repair
-  | BuildMode_Check
+  = BuildMode_Normal -- ^ Perform normal build
+  | BuildMode_Repair -- ^ Try to repair corrupted or missing paths by re-building or re-downloading them
+  | BuildMode_Check -- ^ Check if the build is reproducible (rebuild and compare to previous build)
   deriving (Eq, Generic, Ord, Enum, Show)
 
+-- | Build result status
 data BuildStatus =
-    BuildStatus_Built
-  | BuildStatus_Substituted
-  | BuildStatus_AlreadyValid
+    BuildStatus_Built -- ^ Build performed successfully
+  | BuildStatus_Substituted -- ^ Path substituted from cache
+  | BuildStatus_AlreadyValid -- ^ Path is already valid (available in local store)
   | BuildStatus_PermanentFailure
   | BuildStatus_InputRejected
   | BuildStatus_OutputRejected
-  | BuildStatus_TransientFailure -- possibly transient
-  | BuildStatus_CachedFailure    -- no longer used
-  | BuildStatus_TimedOut
+  | BuildStatus_TransientFailure -- ^ Possibly transient build failure
+  | BuildStatus_CachedFailure -- ^ Obsolete
+  | BuildStatus_TimedOut -- ^ Build timed out
   | BuildStatus_MiscFailure
-  | BuildStatus_DependencyFailed
+  | BuildStatus_DependencyFailed -- ^ Build dependency failed to build
   | BuildStatus_LogLimitExceeded
   | BuildStatus_NotDeterministic
   | BuildStatus_ResolvesToAlreadyValid
@@ -43,18 +44,18 @@ data BuildStatus =
 
 -- | Result of the build
 data BuildResult = BuildResult
-  { -- | Build status, MiscFailure should be the default
-    buildResultStatus             :: !BuildStatus
-  , -- | Possible build error message
-    buildResultErrorMessage       :: !(Maybe Text)
-  , -- | How many times this build was performed
-    buildResultTimesBuilt         :: !Int
-  , -- | If timesBuilt > 1, whether some builds did not produce the same result
-    buildResultIsNonDeterministic :: !Bool
-  ,  -- Start time of this build
-    buildResultStartTime          :: !UTCTime
-  ,  -- Stop time of this build
-    buildResultStopTime           :: !UTCTime
+  { buildResultStatus             :: !BuildStatus
+  -- ^ Build status, MiscFailure should be the default
+  , buildResultErrorMessage       :: !(Maybe Text)
+  -- ^ Possible build error message
+  , buildResultTimesBuilt         :: !Int
+  -- ^ How many times this build was performed
+  , buildResultIsNonDeterministic :: !Bool
+  -- ^ If timesBuilt > 1, whether some builds did not produce the same result
+  , buildResultStartTime          :: !UTCTime
+  -- ^ Start time of this build
+  , buildResultStopTime           :: !UTCTime
+  -- ^ Stop time of this build
   }
   deriving (Eq, Generic, Ord, Show)
 
@@ -68,9 +69,9 @@ buildSuccess x =
 
 -- | Result of the build, for protocol version <= 1.27
 data OldBuildResult = OldBuildResult
-  { -- | Build status, MiscFailure should be the default
-    oldBuildResultStatus       :: !BuildStatus
-  , -- | Possible build error message
-    oldBuildResultErrorMessage :: !(Maybe Text)
+  { oldBuildResultStatus       :: !BuildStatus
+  -- ^ Build status, MiscFailure should be the default
+  , oldBuildResultErrorMessage :: !(Maybe Text)
+  -- ^ Possible build error message
   }
   deriving (Eq, Generic, Ord, Show)