Add module documentation

yesod-auth/Yesod/Auth/Hardcoded.hs

@@ -5,6 +5,81 @@
 {-# LANGUAGE RankNTypes            #-}
 {-# LANGUAGE TemplateHaskell       #-}
 {-# LANGUAGE TypeFamilies          #-}
+{-|
+Module      : Yesod.Auth.Hardcoded
+Description : Very simple auth plugin for harcoded auth pairs.
+Copyright   : (c) Arthur Fayzrakhmanov, 2015
+License     : MIT
+Maintainer  : heraldhoi@gmail.com
+Stability   : experimental
+
+Sometimes you may want to have some hardcoded set of users (e.g. site managers)
+that allowed to log in and visit some specific sections of your website without
+ability to register new managers.  This simple plugin is designed exactly for
+this purpose.
+
+Here is a quick example usage instruction.
+
+= Enable plugin
+First of all, add plugin to 'authPlugins' list:
+
+@
+instance YesodAuth App where
+  authPlugins _ = [authHardcoded]
+@
+
+= Define a manager data type
+
+@
+data SiteManager = SiteManager
+  { manUserName :: Text
+  , manPassWord :: Text }
+
+siteManagers :: [SiteManager]
+siteManagers = [SiteManager "content editor" "top secret"]
+@
+
+= Describe a plugin instance of your app
+
+@
+instance YesodAuthHardcoded App where
+  validatePassword u = return . validPassword u
+  isUserNameExists   = return . lookupUser
+
+lookupUser :: Text -> Bool
+lookupUser username =
+  case find (\m -> manUserName m == username) siteManagers of
+    Just _ -> True
+    _      -> False
+
+validPassword :: Text -> Text -> Bool
+validPassword u p =
+  case find (\m -> manUserName m == u && manPassWord m == p) siteManagers of
+    Just _ -> True
+    _      -> False
+@
+
+= One caveat: 'authenticate' action of 'YesodAuth'.
+
+You may want to store additional information for harcoded users in database, but
+in this example let's cheat a bit:
+
+@
+instance YesodAuth App where
+  authenticate _ =
+    return (Authenticated (toSqlKey 0))
+@
+
+It is also possible to make 'authenticate' action smart enough to examine which
+plugin was used to log in user, e.g.
+
+@
+authenticate creds =
+  case credsPlugin creds of
+    "hardcoded" -> -- ...
+    -- ...
+@
+-}
 module Yesod.Auth.Hardcoded
   ( YesodAuthHardcoded(..)
   , authHardcoded