From 0c1dde8209c06901866a1e62def43050d5d558fa Mon Sep 17 00:00:00 2001
From: Arash Rouhani <miffoljud@gmail.com>
Date: Mon, 15 Aug 2011 00:01:42 +0200
Subject: [PATCH] Added documentation for Kerberos module

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

diff --git a/yesod-auth/Yesod/Auth/Kerberos.hs b/yesod-auth/Yesod/Auth/Kerberos.hs
index b3196248..319ee72d 100644
--- a/yesod-auth/Yesod/Auth/Kerberos.hs
+++ b/yesod-auth/Yesod/Auth/Kerberos.hs
@@ -2,6 +2,22 @@
 {-# LANGUAGE CPP #-}
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# LANGUAGE OverloadedStrings #-}
+-- | In-built kerberos authentication for Yesod.
+--
+-- Please note that all configuration should have been done
+-- manually on the machine prior to running the code.
+--
+-- On linux machines the configuration might be in /etc/krb5.conf.
+-- It's worth checking if the Kerberos service provider (e.g. your university)
+-- already provide a complete configuration file.
+--
+-- Be certain that you can manually login from a shell by typing
+--
+-- > kinit username
+--
+-- If you fill in your password and the program returns no error code,
+-- then your kerberos configuration is setup properly.
+-- Only then can this module be of any use.
 module Yesod.Auth.Kerberos
     ( authKerberos,
       genericAuthKerberos,
@@ -29,9 +45,12 @@ data KerberosConfig = KerberosConfig {
   , identifierModifier :: Text -> Text
   }
 
+-- | A configuration where the username the user provides is the one passed
+-- to both kerberos and yesod
 defaultKerberosConfig :: KerberosConfig
 defaultKerberosConfig = KerberosConfig id id
 
+-- | A configurable version of 'authKerberos'
 genericAuthKerberos :: YesodAuth m => KerberosConfig -> AuthPlugin m
 genericAuthKerberos config = AuthPlugin "kerberos" dispatch $ \tm -> addHamlet
     [hamlet|
@@ -66,6 +85,7 @@ genericAuthKerberos config = AuthPlugin "kerberos" dispatch $ \tm -> addHamlet
 login :: AuthRoute
 login = PluginR "kerberos" ["login"]
 
+-- | Kerberos with 'defaultKerberosConfig'
 authKerberos :: YesodAuth m => AuthPlugin m
 authKerberos = genericAuthKerberos defaultKerberosConfig