CPM: add comments

cpm/Cpm.icl

 module Cpm
 
+/**
+ * Imports
+ */
 import CommandLine
 import Environment
 import Error
@@ -20,6 +23,31 @@ import Text
 import UtilIO
 import UtilStrictLists
 
+/**
+ * CPM: Clean Project Management
+ *
+ * CPM is a tool for managing CleanIDE-compatible projects on the commandline
+ * and is targeted at OS X and Linux users who do not have access to the
+ * CleanIDE.
+ *
+ * Currently, only basic project management features are supported:
+ * - Build a project
+ * - Create a new project
+ * - Show project info
+ * - Manage project paths
+ * - Create new modules
+ *
+ * In the future, all aspects of a CleanIDE project file should be manageable
+ * via CPM.
+ *
+ * CPM is written to display help messages when an incomplete command is
+ * entered. Users are encouraged to explore CPM by themselves by reading these
+ * help messages.
+ */
+
+/**
+ * Datatypes
+ */
 :: CpmAction
   =  Project FilePath ProjectAction
   |  Module String ModuleAction
@@ -51,15 +79,32 @@ import UtilStrictLists
   =  ApplicationModule
   |  LibraryModule
 
+/**
+ * Parsers
+ */
+
+/**
+ * Parse one or more non-whitespace characters
+ */
 pNotSpace :: CParser Char [Char] a
 pNotSpace = sp (<+> (satisfy (not o isWhite)))
 
+/**
+ * Top-level parser for CPM commands
+ */
 pCpm :: CParser Char CpmAction a
 pCpm = pProject <|> pModule <!> (yield CpmHelp)
 
+/**
+ * Wrapper around the token parser that converts a Clean string to a list of
+ * charactersm for easier parsing
+ */
 spstrtok :: (String -> CParser Char [Char] a)
 spstrtok = sptoken o fromString
 
+/**
+ * Parser for the project commands
+ */
 pProject :: CParser Char CpmAction a
 pProject = spstrtok "project" &> (pProjectWithName <|> yield (Project "" ProjectHelp))
   where  pProjectWithName  =  pNotSpace <&> \pn -> pProjectAction <@ Project (toString pn)
@@ -69,6 +114,9 @@ pProject = spstrtok "project" &> (pProjectWithName <|> yield (Project "" Project
                          <|>  (spstrtok "path"    &>  pPathAction)
                          <!>  (pHelp ProjectHelp)
 
+/**
+ * Parser for all path-related actions
+ */
 pPathAction :: CParser Char ProjectAction a
 pPathAction = pPathAction <@ ProjectPath
    where  pPathAction  =  (spstrtok "add"     &>  pNotSpace  <@   AddPathAction o toString)
@@ -78,13 +126,22 @@ pPathAction = pPathAction <@ ProjectPath
                      <!>  (pHelp PathHelp)
           pPathDirection = sp nat <&> \i -> ((spstrtok "up" <@ const PathUp) <|> (spstrtok "down" <@ const PathDown)) <@ MovePathAction i
 
+/**
+ * Parser to toggle the --force flag
+ */
 pForce :: CParser Char Bool a
 pForce = (spstrtok "--force" <@ const True) <|> (yield False)
 
+/**
+ * Parser for the argument to specify where the IDEEnvs file is
+ */
 pIDEEnvs :: CParser Char String a
 pIDEEnvs =  (spstrtok "--envs" &> (<?> (spsymbol '=')) &> pNotSpace <@ toString)
        <!>  (yield EnvsFileName)
 
+/**
+ * Parser for module-related actions
+ */
 pModule :: CParser Char CpmAction a
 pModule = spstrtok "module" &> (pModuleWithName <|> yield (Module "" ModuleHelp))
   where  pModuleWithName  =  pNotSpace <&> \mn -> pModuleAction <@ Module (toString mn)
@@ -93,9 +150,16 @@ pModule = spstrtok "module" &> (pModuleWithName <|> yield (Module "" ModuleHelp)
          pModuleType      =  (spstrtok "application" <@ const ApplicationModule)
                         <|>  (yield LibraryModule)
 
+/**
+ * Parser for the help command
+ */
 pHelp :: c -> CParser Char c a
 pHelp c = (spstrtok "help" <@ const c) <|> (yield c)
 
+/**
+ * Start function which reads the program arguments, starts the parser and
+ * starts processing the parse results.
+ */
 Start :: *World -> *World
 Start world
   # (cmd, world)  = getCommandLine world
@@ -107,9 +171,16 @@ Start world
                       (_, world)        -> (pwd, world)
   = doCpmAction ch pwd cpm world
 
+/**
+ * Parse the a list of characters to get the action to be executed. If parsing
+ * fails, CpmHelp is returned as default action so help may be displayed.
+ */
 startParse :: [.Char] -> CpmAction
 startParse args = maybe CpmHelp snd (find (null o fst) (begin pCpm args))
 
+/**
+ * Execute a general CPM action
+ */
 doCpmAction :: String String .CpmAction *World -> .World
 doCpmAction cleanhome  pwd  (Project pn pa)  world = doProjectAction cleanhome pwd pn pa world
 doCpmAction cleanhome  pwd  (Module mn ma)   world = doModuleAction cleanhome mn ma world
@@ -121,9 +192,16 @@ doCpmAction _          _    _                world =
     ,  ""
     ,  "Execute `cpm <target> help` to get help for specific actions."] world
 
+/**
+ * Default compiler options. Currently it is a simple alias for
+ * forwards-compatibility.
+ */
 compilerOptions :: CompilerOptions
 compilerOptions = DefaultCompilerOptions
 
+/**
+ * Execute project-specific actions
+ */
 doProjectAction :: .String .String .String .ProjectAction *World -> .World
 doProjectAction cleanhome pwd  pn  CreateProject world
   //Check if main module exists
@@ -184,6 +262,9 @@ doProjectAction _          _  _   _    world             =
     ,  "                                        Optionally specify the environments file (default: 'IDEEnvs')"
     ,  "  path                                : manage project paths"] world
 
+/**
+ * Execute path-related project actions
+ */
 doProjectPathAction :: .String .String Project .PathAction *World -> .World
 doProjectPathAction cleanhome pn project (AddPathAction path) world =
   doModPaths cleanhome pn project (\paths -> path :! paths) world
@@ -206,6 +287,11 @@ doProjectPathAction _         _   _     _  world =
     ,  "  remove <i>          : remove path <i> from the list of projects"
     ,  "  move <i> <up|down>  : move path <i> up or down one position" ] world
 
+/**
+ * Modify the list of paths in a project given a modification function which
+ * takes a strict list of project paths and returns a strict list of project
+ * paths.
+ */
 doModPaths :: String String Project .([!String!] -> [!String!]) *World -> .World
 doModPaths cleanhome pn project f world
   # (ok, world)  = saveProject cleanhome prj pn world
@@ -214,20 +300,34 @@ doModPaths cleanhome pn project f world
   where  paths   = PR_GetPaths project
          prj     = PR_SetPaths False paths (f paths) project
 
+/**
+ * Open a project file
+ */
 openProject :: !FilePath !FilePath !*World -> (!MaybeErrorString Project,!*World)
 openProject cleanhome projectfile world
   # ((prj, ok, err), world) = accFiles (ReadProjectFile projectfile cleanhome) world
   | ok  = (Ok prj, world)
         = (Error err, world)
 
+/**
+ * Save a project back to its project file
+ */
 saveProject :: !FilePath !Project !FilePath !*World -> (Bool, !*World)
 saveProject cleanhome prj projectfile world = accFiles (SaveProjectFile projectfile prj cleanhome) world
 
+/**
+ * Remove an item from a strict list at a given index. Abort execution if the
+ * index is out of bounds.
+ */
 rmStrictListIdx :: Int u:[!.a!] -> v:[!.a!], [u <= v]
 rmStrictListIdx 0  (_ :! t)          = t
 rmStrictListIdx n  (h :! t) | n > 0  = h :! (rmStrictListIdx (n - 1) t)
 rmStrictListIdx n  _                 = abort ("Index " +++ toString n +++ " out of bounds")
 
+/**
+ * Move a path at a given index up or down the list of paths. Abort execution
+ * if the index is out of bounds.
+ */
 moveStrictListIdx :: .Int .PathDirection .[!a!] -> .[!a!]
 moveStrictListIdx i dir xs
   | i < 0 || i > (LLength xs - 1)  = abort ("Index " +++ toString i +++ " out of bounds")
@@ -239,6 +339,9 @@ moveStrictListIdx i dir xs
          msl PathDown  (xs, [y])       = xs ++ [y]
          msl PathDown  (xs, [x:y:ys])  = (xs ++ [y:x:ys])
 
+/**
+ * Execute module-related actions
+ */
 doModuleAction :: .String .String .ModuleAction *World -> .World
 doModuleAction cleanhome mn  (CreateModule mt) world
   # (dclexists, world)  = fileExists dclnm world
@@ -278,13 +381,19 @@ doModuleAction _ _   _  world                =
     [  "Where <action> is one of the following"
     ,  "  create [application|library]  : create a new module. Optionally specify module type (default: 'library')"] world
 
-error :: {#.Char} *World -> .World
+/**
+ * Show an error message
+ */
+error :: String *World -> .World
 error message world
   # stderr      = fwrites message stderr
   # (ok,world)  = fclose stderr world
   # world       = set_return_code_world (-1) world
   = world
 
+/**
+ * Show a help message
+ */
 help :: !String ![String] !*World -> *World
 help cmd lines world = showLines lines` world
   where lines` = [  "CPM: Clean Project Management"
@@ -292,6 +401,10 @@ help cmd lines world = showLines lines` world
                  :  "Usage: " +++ cmd
                  :  lines]
 
+/**
+ * Given a list of strings, concatenate them to a single string with newlines
+ * in between, then print that new string to console.
+ */
 showLines :: ![String] !*World -> *World
 showLines lines world
   # (console,world)  = stdio world