From b024a7a5404dc1697ea72d1d84676e73a11616c1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arthur=20Fayzrakhmanov=20=28=D0=90=D1=80=D1=82=D1=83=D1=80?=
 =?UTF-8?q?=20=D0=A4=D0=B0=D0=B9=D0=B7=D1=80=D0=B0=D1=85=D0=BC=D0=B0=D0=BD?=
 =?UTF-8?q?=D0=BE=D0=B2=29?= <heraldhoi@gmail.com>
Date: Tue, 24 Nov 2015 21:20:24 +0500
Subject: [PATCH] Add module documentation

---
 yesod-auth/Yesod/Auth/Hardcoded.hs | 75 ++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/yesod-auth/Yesod/Auth/Hardcoded.hs b/yesod-auth/Yesod/Auth/Hardcoded.hs
index 2e90645d..a898818f 100644
--- a/yesod-auth/Yesod/Auth/Hardcoded.hs
+++ b/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