some documentation

1 files changed, 9 insertions, 3 deletions

diff --git a/lib/Paths.hs b/lib/Paths.hs
index 49c0295..5044673 100644
--- a/lib/Paths.hs
+++ b/lib/Paths.hs
@@ -1,7 +1,7 @@
 {-# 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
+-- 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 _) =