* documentation for Language.Elm

elm/src/Language/Elm.hs

@@ -1,5 +1,10 @@
 {-# LANGUAGE QuasiQuotes, TemplateHaskell #-}
+{- | This module re-exports the modules necessary for compiling Elm code into the
+     respective HTML, JS and CSS code.
 
+     It also provides a predefined generateHtml function for use with the Blaze markup library
+     as well as a simple QuasiQuoter for embedding literal elm code in a Haskell file.
+-}
 module Language.Elm (
     module Language.Elm.Initialize,
     module Language.Elm.CompileToJS,
@@ -15,8 +20,32 @@ import Language.Elm.GenerateHtml
 import Language.Haskell.TH
 import Language.Haskell.TH.Quote
 
+{- | This QuasiQuoter allows for literal embedding of elm source code within
+     Haskell files. It is not responsible for the actual compilation Process.
+     Usage:
+
+   @
+     elmPage = [elm|
+      main = image \"someImage.jpg\"
+     |]
+   @
+
+     How the elm code is compiled depends on how you intend to use it.
+     Example uses are the included 'generateHtml' function as well as the
+     "Language.Elm.Yesod" module.
+-}
 elm :: QuasiQuoter
 elm = QuasiQuoter {quoteExp = \s -> [|s|] }
 
+{- | elmFile is a quoteFile wrapper around the 'elm' QuasiQuoter and allows for
+     external elm source files to be embedded.
+     Usage:
+
+   @
+     [elmFile|elm-source/page.elm|]
+   @
+
+     Please note that no spaces should be added before and after the filename.
+-}
 elmFile :: QuasiQuoter
 elmFile = quoteFile elm

elm/src/Language/Elm/GenerateHtml.hs

@@ -2,6 +2,7 @@
 module Language.Elm.GenerateHtml (generateHtml) where
 
 import Text.Blaze (preEscapedToMarkup)
+import Text.Blaze.Html (Html)
 import qualified Text.Blaze.Html5 as H
 import Text.Blaze.Html5 ((!))
 import qualified Text.Blaze.Html5.Attributes as A
@@ -23,6 +24,15 @@ css = preEscapedToMarkup $
 makeScript :: String -> H.Html
 makeScript s = H.script ! A.type_ "text/javascript" ! A.src (H.toValue s) $ ""
 
+-- |This function compiles Elm code into simple HTML.
+--
+--  Usage example:
+--
+-- > generateHtml "/elm-min.js" "Some title" [elmFile|elm-source/somePage.elm|]
+generateHtml :: String -- ^ Location of elm-min.js as expected by the browser
+             -> String -- ^ The page title
+             -> String -- ^ The elm source code.
+             -> Html
 generateHtml libLoc title source =
     let expr = initialize source
         js = compileToJS expr