some documentation

lib/CheckDir.hs

@@ -32,11 +32,13 @@ setFromList  = M.fromList . flip zip (repeat ())
 listFromSet :: Set a -> [a]
 listFromSet = map fst . M.toList
 
+-- | Result of linting an entire directory / repository
 data DirResult = DirResult
   { dirresultMaps :: Map FilePath MapResult
   , dirresultDeps :: [Text]
   } deriving (Generic, ToJSON)
 
+
 instance PrettyPrint DirResult where
   prettyprint res = T.concat
     (map (\(p,lints) -> "\nin " <> T.pack p <> ":\n" <> prettyprint lints) $ M.toList $ dirresultMaps res)
@@ -54,11 +56,18 @@ instance Monoid DirResult where
     }
 
 
--- TODO: options?
+-- | The nice function to check an entire repository with.
+-- gets a prefix (i.e. the bare path to the repository) and
+-- a root (i.e. the name of the file containing the entrypoint
+-- map within that file)
 recursiveCheckDir :: FilePath -> FilePath -> IO DirResult
 recursiveCheckDir prefix root = recursiveCheckDir' prefix [root] mempty mempty
 
-
+-- | The less-nice function for checking an entire repository.
+--
+-- Strictly speaking it probably doesn't need to have `done` and
+-- `acc` since they are essentially the same thing, but doing it
+-- like this seemed convenient at the time
 recursiveCheckDir' :: FilePath -> [FilePath] -> Set FilePath -> DirResult -> IO DirResult
 recursiveCheckDir' prefix paths done acc = do
   putStrLn $ "linting " <> show paths

lib/Paths.hs

 {-# LANGUAGE OverloadedStrings #-}
 
--- |
-
+-- | Paths are horrible, so they have their own module now.
+-- I just hope you are running this on some kind of Unix
 module Paths where
 
 import           Data.Text             (Text)
@@ -12,7 +12,8 @@ import           Text.Regex.TDFA
 import           Util                  (PrettyPrint (prettyprint))
 
 -- | a normalised path: a number of "upwards" steps, and
+-- a path without any . or .. in it. Also possibly a
+-- fragment, mostly for map links.
 data RelPath = Path Int Text (Maybe Text)
   deriving (Show, Eq, Ord)
 
@@ -37,6 +38,11 @@ instance PrettyPrint RelPath where
   prettyprint (Path up rest _) = ups <> rest
     where ups = T.concat $ replicate up "../"
 
+-- | Normalises a path.
+--
+-- It takes a `prefix`, and will "truncate" the .. operator
+-- at the end of the prefix, i.e. it will never return paths
+-- that lie (naïvely) outside of the prefix.
 normalise :: FilePath -> RelPath ->  FilePath
 normalise prefix (Path 0 path _) = prefix </> T.unpack path
 normalise prefix (Path i path _) =