adding meaning introduction to some modules

Author: Anton-Latukha

src/Nix/Builtins.hs

@@ -22,6 +22,7 @@
 {-# OPTIONS_GHC -Wno-missing-signatures #-}
 {-# OPTIONS_GHC -fno-warn-name-shadowing #-}
 
+-- | Code that implements Nix builtins. Lists the functions that are built into the Nix expression evaluator. Some built-ins (aka `derivation`), are always in the scope, so they can be accessed by the name. To keap the namespace clean, most built-ins are inside the `builtins` scope - a set that contains all what is a built-in.
 module Nix.Builtins (withNixContext, builtins) where
 
 import           Control.Comonad

src/Nix/Cache.hs

@@ -1,5 +1,6 @@
 {-# LANGUAGE CPP #-}
 
+-- | Reading and writing Nix cache files
 module Nix.Cache where
 
 import qualified Data.ByteString.Lazy          as BS
@@ -38,11 +39,11 @@ readCache path = do
 writeCache :: FilePath -> NExprLoc -> IO ()
 writeCache path expr =
 #ifdef USE_COMPACT
-    C.writeCompact path =<< C.compact expr
+  C.writeCompact path =<< C.compact expr
 #else
 #ifdef MIN_VERSION_serialise
   BS.writeFile path (S.serialise expr)
 #else
     error "writeCache not implemented for this platform"
 #endif
-#endif
+#endif

src/Nix/Frames.hs

@@ -4,6 +4,7 @@
 {-# LANGUAGE FlexibleInstances #-}
 {-# LANGUAGE ScopedTypeVariables #-}
 
+-- | Definitions of Frames. Frames are messages that gather and ship themself with a context related to the message. For example - the message about some exception would also gather, keep and bring with it the tracing information.
 module Nix.Frames
   ( NixLevel(..)
   , Frames

src/Nix/Normal.hs

@@ -9,6 +9,9 @@
 {-# LANGUAGE TypeApplications #-}
 {-# LANGUAGE TypeFamilies #-}
 
+-- | Code for normalization (reduction into a normal form) of Nix expressions.
+-- Nix language allows recursion, so some expressions do not converge.
+-- And so do not converge into a normal form.
 module Nix.Normal where
 
 import           Control.Monad
@@ -117,7 +120,7 @@ removeEffects
 removeEffects =
   iterNValueM
     id
-    (flip queryM (pure opaque))
+    (`queryM` pure opaque)
     (fmap Free . sequenceNValue' id)
 
 opaque :: Applicative f => NValue t f m

src/Nix/Options.hs

@@ -1,3 +1,4 @@
+-- | Definitions & defaults for the CLI options
 module Nix.Options where
 
 import           Data.Text                      ( Text )

src/Nix/Options/Parser.hs

@@ -1,5 +1,6 @@
 {-# LANGUAGE TemplateHaskell #-}
 
+-- | Code that configures presentation parser for the CLI options
 module Nix.Options.Parser where
 
 import           Control.Arrow                  ( second )

src/Nix/Parser.hs

@@ -9,6 +9,7 @@
 {-# OPTIONS_GHC -fno-warn-name-shadowing #-}
 {-# OPTIONS_GHC -Wno-missing-signatures #-}
 
+-- | Main module for parsing Nix expressions.
 module Nix.Parser
   ( parseNixFile
   , parseNixFileLoc

src/Nix/Render.hs

@@ -128,5 +128,5 @@ sourceContext path (unPos -> begLine) (unPos -> _begCol) (unPos -> endLine) (unP
             | otherwise         = "    " ++ n
       ls' = zipWith (<+>)
                     (map (pretty . pad) nums')
-                    (map ((<+>) "| ") ls)
+                    (map ("| " <+>) ls)
     pure $ vsep $ ls' ++ [msg]

src/Nix/Render/Frame.hs

@@ -10,6 +10,8 @@
 {-# LANGUAGE TypeApplications #-}
 {-# LANGUAGE TypeFamilies #-}
 
+
+-- | Code for rendering/representation of the messages packaged with their context (Frames).
 module Nix.Render.Frame where
 
 import           Control.Monad.Reader
@@ -152,8 +154,7 @@ renderExpr _level longLabel shortLabel e@(Fix (Compose (Ann _ x))) = do
           | otherwise = prettyNix (Fix (Fix (NSym "<?>") <$ x))
   pure $ if verbose opts >= Chatty
     then
-      vsep
-        $ [pretty (longLabel ++ ":\n>>>>>>>>"), indent 2 rendered, "<<<<<<<<"]
+      vsep [pretty (longLabel ++ ":\n>>>>>>>>"), indent 2 rendered, "<<<<<<<<"]
     else pretty shortLabel <> fillSep [": ", rendered]
 
 renderValueFrame

src/Nix/String.hs

@@ -205,7 +205,7 @@ principledMakeNixStringWithSingletonContext s c = NixString s (S.singleton c)
 
 -- | Create a NixString from a Text and context
 principledMakeNixString :: Text -> S.HashSet StringContext -> NixString
-principledMakeNixString s c = NixString s c
+principledMakeNixString = NixString
 
 -- | A monad for accumulating string context while producing a result string.
 newtype WithStringContextT m a = WithStringContextT (WriterT (S.HashSet StringContext) m a)