Document the code

Author: NickSeagull

app/Main.hs

@@ -1,3 +1,4 @@
+-- | Main entry point for the layer
 module Main
   ( main
   ) where

default.nix

@@ -17,8 +17,11 @@ import qualified Aws.Lambda.Meta.Main as Main
 import qualified Aws.Lambda.Meta.Run as Run
 import qualified Aws.Lambda.Runtime.IPC as IPC
 
+{-| Generates a @main@ function to be used with the
+AWS Lambda layer.
+-}
 configureLambda :: Meta.DecsQ
 configureLambda = do
   main <- Main.generate
   run <- Run.generate
-  return $ main <> [run]
+  return (main <> [run])

shell.nix

@@ -1,3 +1,4 @@
+{-| Helper functions to make code generation easier -}
 module Aws.Lambda.Meta.Common
   ( declarationName
   , expressionName

src/Aws/Lambda/Configuration.hs

@@ -1,5 +1,10 @@
+{-| Discovery of AWS Lambda handlers
+A handler is basically a function that has a type definition that
+starts with "handler :: ".
+ -}
 module Aws.Lambda.Meta.Discover
-  (handlers) where
+  ( handlers
+  ) where
 
 import qualified Control.Monad as Monad
 import Data.Function ((&))
@@ -10,6 +15,13 @@ import qualified Data.Text as Text
 import Path
 import qualified Path.IO as PathIO
 
+{-| Returns a list of handler paths that look like
+
+@src/Foo/Bar/Quux.handler@
+
+It is the path to the source file, but changing the
+extension for ".handler"
+-}
 handlers :: IO [Text]
 handlers = do
   (_, files) <- PathIO.listDirRecurRel [reldir|.|]

src/Aws/Lambda/Meta/Common.hs

@@ -1,3 +1,4 @@
+{-| Dispatcher generation -}
 module Aws.Lambda.Meta.Dispatch
   ( generate
   , decodeObj
@@ -13,16 +14,27 @@ import qualified Language.Haskell.TH as Meta
 
 import Aws.Lambda.Meta.Common
 
+{-| Helper function that the dispatcher will use to
+decode the JSON that comes as an AWS Lambda event into the
+appropriate type expected by the handler.
+-}
 decodeObj :: FromJSON a => String -> a
 decodeObj x =
   case (eitherDecode $ LazyByteString.pack x) of
     Left e  -> error e
     Right v -> v
 
+{-| Generates the dispatcher out of a list of
+handler names in the form @src/Foo/Bar.handler@
+
+This dispatcher has a case for each of the handlers that calls
+the appropriate qualified function. In the case of the example above,
+the dispatcher will call @Foo.Bar.handler@.
+-}
 generate :: [Text] -> Meta.ExpQ
-generate fileNames = do
+generate handlerNames = do
   caseExp <- expressionName "functionHandler"
-  matches <- traverse handlerCase fileNames
+  matches <- traverse handlerCase handlerNames
   unmatched <- unmatchedCase
   pure $ Meta.CaseE caseExp (matches <> [unmatched])
 

src/Aws/Lambda/Meta/Discover.hs

@@ -1,3 +1,4 @@
+{-| main function generation for interoperation with the layer -}
 module Aws.Lambda.Meta.Main
   ( LambdaOptions(..)
   , generate
@@ -11,13 +12,15 @@ import qualified Options.Generic as Options
 
 import Aws.Lambda.Meta.Common
 
+-- | Options that the generated main expects
 data LambdaOptions = LambdaOptions
   { eventObject     :: !String
   , contextObject   :: !String
   , functionHandler :: !String
   , executionUuid   :: !String
   } deriving (Generic, Options.ParseRecord)
 
+-- | Generate the main function that the layer will call
 generate :: Meta.DecsQ
 generate = [d|
   $(declarationName "main") = getRecord "" >>= run

src/Aws/Lambda/Meta/Dispatch.hs

@@ -8,6 +8,12 @@ import Aws.Lambda.Meta.Common
 import qualified Aws.Lambda.Meta.Discover as Discover
 import qualified Aws.Lambda.Meta.Dispatch as Dispatch
 
+{-| Generate the run function
+
+It will create a dispatcher that is a huge @case@ expression that
+expects the name of the handler provided by AWS Lambda, and will
+execute the appropriate user function
+ -}
 generate :: Meta.DecQ
 generate = do
   handlers <- Meta.runIO Discover.handlers

src/Aws/Lambda/Meta/Main.hs

@@ -12,6 +12,8 @@ import qualified Aws.Lambda.Runtime.Error as Error
 import qualified Aws.Lambda.Runtime.IPC as IPC
 import qualified Aws.Lambda.Runtime.Publish as Publish
 
+-- | Runs the user @haskell_lambda@ executable and posts back the
+-- results
 runLambda
   :: Http.Manager
   -> IO ()