Add some haddock, rename 'functionName'

servant-jquery/src/Servant/JQuery/Angular.hs

@@ -5,23 +5,29 @@ import Control.Lens
 import Data.List
 import Data.Monoid
 
-data AngularOptions = AngularOptions {
+data AngularOptions = AngularOptions
-        serviceName :: String,
+  { serviceName :: String                         -- ^ When generating code with wrapInService,
-        prologue :: String -> String -> String,
+                                                  -- ^ name of the service to generate
-        epilogue :: String
+  , prologue :: String -> String -> String        -- ^ beginning of the service definition
+  , epilogue :: String                            -- ^ end of the service definition
   }
 
 defAngularOptions :: AngularOptions
-defAngularOptions = AngularOptions {
+defAngularOptions = AngularOptions
-        serviceName = "",
+  { serviceName = ""
-        prologue = \svc m -> m <> "service('" <> svc <> "', function($http) {\n"
+  , prologue = \svc m -> m <> "service('" <> svc <> "', function($http) {\n"
-                               <> "  return ({",
+                           <> "  return ({"
-                               epilogue = "});\n});\n"
+  , epilogue = "});\n});\n"
     }
 
+-- | Instead of simply generating top level functions, generates a service instance
+-- on which your controllers can depend to access your API
+-- This variant uses default AngularOptions
 wrapInService :: AngularOptions -> [AjaxReq] -> String
 wrapInService ngOpts reqs = wrapInServiceWith ngOpts defCommonGeneratorOptions reqs
 
+-- | Instead of simply generating top level functions, generates a service instance
+-- on which your controllers can depend to access your API
 wrapInServiceWith :: AngularOptions -> CommonGeneratorOptions -> [AjaxReq] -> String
 wrapInServiceWith ngOpts opts reqs = 
     ((prologue ngOpts) svc mName)
@@ -34,10 +40,11 @@ wrapInServiceWith ngOpts opts reqs =
                    then "app."
                    else (moduleName opts) <> "."
     
+-- js codegen using $http service from Angular using default options
 generateAngularJS :: AngularOptions -> AjaxReq -> String
 generateAngularJS ngOpts = generateAngularJSWith ngOpts defCommonGeneratorOptions
     
--- js codegen using $http
+-- js codegen using $http service from Angular
 generateAngularJSWith ::  AngularOptions -> CommonGeneratorOptions -> AjaxReq -> String
 generateAngularJSWith ngOptions opts req = "\n" <>
     fname <> fsep <> " function(" <> argsStr <> ")\n"
@@ -105,7 +112,7 @@ generateAngularJSWith ngOptions opts req = "\n" <>
                 
         fsep = if hasService then ":" else " ="
                 
-        fname = namespace <> (functionName opts $ req ^. funcName)
+        fname = namespace <> (functionRenamer opts $ req ^. funcName)
         
         method = req ^. reqMethod
         url = if url' == "'" then "'/'" else url'

servant-jquery/src/Servant/JQuery/Internal.hs

@@ -25,23 +25,25 @@ import GHC.Exts (Constraint)
 import GHC.TypeLits
 import Servant.API
 
-data CommonGeneratorOptions = CommonGeneratorOptions {
+-- | this structure is used by JavaScriptGenerator implementations to let you
-        -- Function transforming function names
+-- customize the output
-        functionName :: String -> String,
+data CommonGeneratorOptions = CommonGeneratorOptions
-        -- Name used when a user want to send the request body (to let you redefine it)
+  { 
-        requestBody :: String,
+    functionRenamer :: String -> String  -- ^ function transforming function names
-        successCallback :: String,
+  , requestBody :: String                -- ^ name used when a user want to send the request body (to let you redefine it)
-        errorCallback :: String,
+  , successCallback :: String            -- ^ name of the callback parameter when the request was successful
-        moduleName :: String
+  , errorCallback :: String              -- ^ name of the callback parameter when the request reported an error
+  , moduleName :: String                 -- ^ namespace on which we define the js function (empty mean local var)
   }
 
 defCommonGeneratorOptions :: CommonGeneratorOptions
-defCommonGeneratorOptions = CommonGeneratorOptions {
+defCommonGeneratorOptions = CommonGeneratorOptions
-      functionName = id,
+  {
-      requestBody = "body",
+    functionRenamer = id
-      successCallback = "onSuccess",
+  , requestBody = "body"
-      errorCallback = "onError",
+  , successCallback = "onSuccess"
-      moduleName = ""
+  , errorCallback = "onError"
+  , moduleName = ""
   }
     
 type Arg = String

servant-jquery/src/Servant/JQuery/JQuery.hs

@@ -5,10 +5,11 @@ import Control.Lens
 import Data.List
 import Data.Monoid
 
+-- | js codegen using JQuery using default options
 generateJQueryJS :: AjaxReq -> String
 generateJQueryJS = generateJQueryJSWith defCommonGeneratorOptions
 
--- js codegen using  JQuery
+-- | js codegen using JQuery
 generateJQueryJSWith :: CommonGeneratorOptions -> AjaxReq -> String
 generateJQueryJSWith opts req = "\n" <>
     fname <> " = function(" <> argsStr <> ")\n"
@@ -64,7 +65,7 @@ generateJQueryJSWith opts req = "\n" <>
         namespace = if null (moduleName opts)
                        then "var "
                        else (moduleName opts) <> "."
-        fname = namespace <> (functionName opts $ req ^. funcName)
+        fname = namespace <> (functionRenamer opts $ req ^. funcName)
         
         method = req ^. reqMethod
         url = if url' == "'" then "'/'" else url'

servant-jquery/src/Servant/JQuery/Vanilla.hs

@@ -5,10 +5,11 @@ import Control.Lens
 import Data.List
 import Data.Monoid
 
+-- | js codegen using XmlHttpRequest using default generation options
 generateVanillaJS :: AjaxReq -> String
 generateVanillaJS = generateVanillaJSWith defCommonGeneratorOptions
 
--- js codegen using XmlHttpRequest
+-- | js codegen using XmlHttpRequest
 generateVanillaJSWith :: CommonGeneratorOptions -> AjaxReq -> String
 generateVanillaJSWith opts req = "\n" <>
     fname <> " = function(" <> argsStr <> ")\n"
@@ -70,7 +71,7 @@ generateVanillaJSWith opts req = "\n" <>
         namespace = if null (moduleName opts)
                        then "var "
                        else (moduleName opts) <> "."
-        fname = namespace <> (functionName opts $ req ^. funcName)
+        fname = namespace <> (functionRenamer opts $ req ^. funcName)
         
         method = req ^. reqMethod
         url = if url' == "'" then "'/'" else url'