add comments

parser-typechecker/src/Unison/CommandLine/InputPattern.hs

@@ -17,9 +17,11 @@ import           Unison.Codebase.Editor         (Input (..))
 import qualified Unison.Util.ColorText          as CT
 import qualified Unison.Util.Pretty             as P
 
+-- InputPatterns accept some fixed number of Required arguments of various
+-- types, followed by a variable number of a single type of argument.
 data IsOptional
-  = Optional -- 0 or 1, at the end
-  | Required -- 1, at the start
+  = Required -- 1, at the start
+  | Optional -- 0 or 1, at the end
   | ZeroPlus -- 0 or more, at the end
   | OnePlus -- 1 or more, at the end
   deriving Show
@@ -43,17 +45,27 @@ data ArgumentType = ArgumentType
 instance Show ArgumentType where
   show at = "ArgumentType " <> typeName at
 
--- `argType` gets called when the user tries to autocomplete an `i`th argument.
+-- `argType` gets called when the user tries to autocomplete an `i`th argument (zero-indexed).
 -- todo: would be nice if we could alert the user if they try to autocomplete
--- past the end.
+-- past the end.  It would also be nice if
 argType :: InputPattern -> Int -> Maybe ArgumentType
 argType ip i = go (i, args ip) where
+  -- Strategy: all of these input patterns take some number of arguments.
+  -- If it takes no arguments, then don't autocomplete.
   go (_, []) = Nothing
+  -- If requesting the 0th of >=1 arguments, return it.
   go (0, (_, t) : _) = Just t
+  -- If requesting a later parameter, decrement and drop one.
   go (n, (Required, _) : args) = go (n - 1, args)
+  -- Vararg parameters should appear at the end of the arg list, and work for
+  -- any later argument number.
   go (_, (ZeroPlus, t) : []) = Just t
   go (_, (OnePlus, t) : []) = Just t
-  go _ = Nothing
+  -- Optional parameters only work at position 0, under this countdown scheme.
+  go (_, (Optional, _): []) = Nothing
+  -- The argument list spec is invalid if something follows optional or vararg
+  go _ = error $ "Input pattern " <> show (patternName ip)
+    <> " has an invalid argument list: " <> (show . fmap fst) (args ip)
 
 minArgs :: InputPattern -> Int
 minArgs ip@(fmap fst . args -> args) = go args where