more documentation

Author: quasarbright

app/Main.hs

@@ -16,25 +16,35 @@ import Exprs
 -- TODO argparse for something like check -i fma.unit
 -- TODO release packaged binaries on github
 
+-- | Either runs a file or runs the REPL
 main :: IO ()
 main = do
     args <- getArgs
     case args of
+        -- no file, run the repl
         [] -> repl
+        -- run the file
         filePath:_ -> do
             source <- readFile filePath
             runString filePath source
 
+-- | Run the given file name and string, printing output
 runString :: String -> String -> IO ()
 runString filePath source = case parseProgram filePath source of
+    -- report parse error
     Left err -> hPrint stderr err
+    -- run the program
     Right prog ->
         case checkProgram prog of
+            -- report well-formedness/type checking errors
             Left errs -> sequence_ (print <$> errs)
+            -- success! show definitions in their file (don't include the prelude)
             Right env -> print (envDifference env (initialEnv dummySS))
 
+-- | Stateful REPL for running statements and viewing definitions
 type Repl a = HaskelineT (StateT (TyEnv SS) IO) a
 
+-- | run the input as a statement and print any new definitions. The environment is maintained throughout the REPL
 cmd :: String -> Repl ()
 cmd input = do
     env <- get
@@ -47,6 +57,7 @@ cmd input = do
                     put env'
                     liftIO (print (envDifference env' env))
 
+-- | (Stateful) Autocomplete based on keywords and names in scope
 comp :: (Monad m, MonadState (TyEnv SS) m) => WordCompleter m
 comp n = do
     env <- get
@@ -57,38 +68,48 @@ comp n = do
                        ]
     return $ filter (isPrefixOf n) names
 
+-- | :help displays help text
 help :: [String] -> Repl ()
 help _ = liftIO $ putStrLn (unlines helpLines)
 
+-- | :quit exits the repl
 quit :: [String] -> Repl ()
 quit _ = abort
 
+-- | :list shows all names and their units
 listEnv :: [String] -> Repl ()
 listEnv _ = do
     env <- get
     liftIO (print env)
 
+-- | Data for a @:help@-like command
 data Opt = Opt{ synonyms :: [String]
               , arguments :: [String]
               , runOpt :: [String] -> Repl ()
               , usage :: String  
               }
+
+-- | @:help@-like commands
 opts :: [Opt]
 opts = 
     [ Opt ["help", "h"] [] help    "display this help information"
     , Opt ["quit", "q"] [] quit    "exit the repl"
     , Opt ["list", "l"] [] listEnv "list all names currently in scope"
     ]
 
+-- | Help text lines describing available @:help@-like commands
 helpLines :: [String]
 helpLines = "command -> description":[unwords ((":"++) <$> synonyms opt)++" -> "++usage opt | opt <- opts]
 
+-- | @:help@-like commands for defining the repl
 opts' :: [(String, [String] -> Repl ())]
 opts' = [(name, runOpt opt) | opt <- opts, name <- synonyms opt]
 
+-- | Welcome message
 ini :: Repl ()
 ini = liftIO $ putStrLn "Welcome to UnitChecker!" >> putStrLn "for help, use :h or :help. to quit, use :q or :quit"
 
+-- | Actual repl definition. Evaluating this runs the repl until the user exits
 repl :: IO ()
 repl = flip evalStateT (initialEnv dummySS)
      $ evalRepl (pure "UnitChecker> ") cmd opts' (Just ':') (Word comp) ini

src/Check.hs

@@ -42,6 +42,7 @@ instance Show a => Show (Error a) where
 --   from the new program.
 data TyEnv a = TyEnv {derivedMap :: Map String (Unit a, Int), varMap :: Map String (Unit a, Int), funMap :: Map String (Signature a, Int), count :: Int}
 
+-- | Shows environment entries in the order that they were defined (inserted) separated by newlines. Uses ID's to sort
 instance Show (TyEnv a) where
     show env =
         [deriveds, vars, funs]
@@ -50,16 +51,25 @@ instance Show (TyEnv a) where
         |> fmap fst
         |> unlines
         where
+            -- | derived unit names with their insertion ID
+            deriveds :: [(String, Int)]
             deriveds = mapToVersionedLines " = " (derivedMap env)
+            -- | variable names with their insertion ID
+            vars :: [(String, Int)]
             vars = mapToVersionedLines " :: " (varMap env)
+            -- | function names with their insertion ID
+            funs :: [(String, Int)]
             funs = mapToVersionedLines " :: " (funMap env)
+            -- | takes in a separator and an environmental map and returns each entry rendered and ID'ed
+            mapToVersionedLines :: Show a => String -> Map.Map String (a, Int) -> [(String, Int)]
             mapToVersionedLines sep m = --showPair sep . swap . unassoc <$> Map.toList m
                 Map.toList m
                 |> fmap unassoc
                 |> fmap (\(ab,n) -> (showPair sep ab, n))
             unassoc (a, (b, c)) = ((a, b), c)
             showPair sep (name, val) = name++sep++show val
 
+-- | Totally empty type environment
 emptyEnvironment :: TyEnv a
 emptyEnvironment = TyEnv {derivedMap=Map.empty, varMap=Map.empty, funMap=Map.empty, count = 0}
 

src/Exprs.hs

@@ -9,7 +9,8 @@ import Data.Ratio
 type Map k v = Map.Map k v
 
 -- TODO rm radians
--- | Either an SI unit or a derived unit
+-- | Either an SI unit or a derived unit.
+--   Equality ignores tags
 data BaseUnit a = Meter a | Second a | Kilogram a | Ampere a | Kelvin a | Mole a | Candela a | Radian a | Derived String a
 
 -- | All SI units, but they need a tag
@@ -20,11 +21,13 @@ siUnits = [Meter, Second, Kilogram, Ampere, Kelvin, Mole, Candela, Radian]
 siUnitNames :: [String]
 siUnitNames = [show (b()) | b <- siUnits]
 
+-- equality ignores tags
 instance Eq (BaseUnit a) where
     (Derived name1 _) == (Derived name2 _) = name1 == name2
     -- jank, but I don't want to write all those cases and it works
     base1 == base2 = show base1 == show base2
 
+-- comparison ignores tags
 instance Ord (BaseUnit a) where
     compare (Derived name1 _) (Derived name2 _) = compare name1 name2
     compare Derived{} _ = GT