EZConfig: add documentation and a warning, so no one repeats my silly hard-to-track-down mistake.

darcs-hash:20080311172610-bd4d7-3119b86f77cf8e26b17c68e074ce634bbee22009.gz

1 files changed, 12 insertions, 1 deletions

diff --git a/XMonad/Util/EZConfig.hs b/XMonad/Util/EZConfig.hs
index caffc5d..8dce949 100644
--- a/XMonad/Util/EZConfig.hs
+++ b/XMonad/Util/EZConfig.hs
@@ -313,10 +313,21 @@ specialKeys = [ ("Backspace", xK_BackSpace)
 -- > myConfig = defaultConfig {
 -- >     ...
 -- >     keys = \c -> mkKeymap c myKeymap
--- >     startupHook = checkKeymap myConfig myKeymap
+-- >     startupHook = return () >> checkKeymap myConfig myKeymap
 -- >     ...
 -- > }
 --
+-- NOTE: the @return ()@ in the example above is very important!
+-- Otherwise, you might run into problems with infinite mutual
+-- recursion: the definition of myConfig depends on the definition of
+-- startupHook, which depends on the definition of myConfig, ... and
+-- so on.  Actually, it's likely that the above example in particular
+-- would be OK without the @return ()@, but making @myKeymap@ take
+-- @myConfig@ as a parameter would definitely lead to
+-- problems. Believe me.  It, uh, happened to my friend. In... a
+-- dream. Yeah. In any event, the @return () >>@ introduces enough
+-- laziness to break the deadlock.
+--
 checkKeymap :: XConfig l -> [(String, a)] -> X ()
 checkKeymap conf km = warn (doKeymapCheck conf km)
   where warn ([],[])   = return ()