From 29e7909db272a1d083c8a711ffe7724292ea7bdf Mon Sep 17 00:00:00 2001
From: jgk <justin.g.kruger@gmail.com>
Date: Sat, 3 Apr 2021 00:30:10 +0200
Subject: [PATCH] Add haddock comments

---
 src/Loop.hs | 68 ++++++++++++++++++++++++++++-------------------------
 1 file changed, 36 insertions(+), 32 deletions(-)

diff --git a/src/Loop.hs b/src/Loop.hs
index 0f087c304..4ed1f8e0c 100644
--- a/src/Loop.hs
+++ b/src/Loop.hs
@@ -1,3 +1,9 @@
+{-|
+Module      : Loop
+Description : A minimal game loop
+
+This module sets up an SDL window which may be updated using a simple game loop.
+-}
 module Loop
     ( setupLoop
     ) where
@@ -12,25 +18,17 @@ import Foreign.C
 
 import Control.Lens ((.~),(&),(+~))
 
-winConfig :: Int -> Int -> WindowConfig
-winConfig x y = defaultWindow 
-    { windowGraphicsContext
-        = OpenGLContext (defaultOpenGL { glProfile = Core Normal 4 3
-                                       , glColorPrecision = V4 8 8 8 8
-                                       } 
-                        )
-    , windowInitialSize = V2 (fromIntegral x) (fromIntegral y)
-    , windowResizable =True
-    }
-
-setupLoop 
-    :: (Int,Int)
-    -> IO params
-    -> (params -> IO ())
-    -> IO world
-    -> (params -> world -> IO params)
+-- | Create a game loop with an SDL window.
+setupLoop
+    :: (Int,Int)            -- ^ The window size.
+    -> IO params            -- ^ Initial parameters.
+    -> (params -> IO ())    -- ^ Function for cleaning up parameters, applied when exiting loop.
+    -> IO world             -- ^ Initial simulation state.
+    -> (params -> world -> IO params)   -- ^ Parameter update, called once per frame. Allows for side effects such as rendering.
     -> (world -> Event -> Maybe world)
+                            -- ^ SDL Event handling, once per frame. Evaluating 'Nothing' exits the loop.
     -> (world -> Maybe world)
+                            -- ^ Simulation update, once per frame. 'Nothing' exits the loop.
     -> IO ()
 setupLoop 
     (xSize,ySize)
@@ -53,13 +51,14 @@ setupLoop
                     paramCleanup 
                     $ doLoop window startWorld sideEffects eventFn worldFn
 
+-- | The internal loop.
 doLoop 
-    :: Window 
-    -> world
-    -> (params -> world -> IO params) 
-    -> (world -> Event -> Maybe world) 
-    -> (world -> Maybe world) 
-    -> params 
+    :: Window   -- ^ The SDL window.
+    -> world    -- ^ Current simulation state.
+    -> (params -> world -> IO params) -- ^ Parameter update. 
+    -> (world -> Event -> Maybe world) -- ^ SDL Event handling.
+    -> (world -> Maybe world) -- ^ Simulation update
+    -> params -- ^ Current parameters.
     -> IO ()
 doLoop 
     window 
@@ -92,15 +91,8 @@ applyEventsIO
     -> IO (Maybe world)
 applyEventsIO fn w = foldM (applyEventIO fn) (Just w)
 
---eventCloseOrResize :: Event -> IO (Maybe Event)
---eventCloseOrResize e = case eventPayload e of
---    QuitEvent           -> return Nothing
---    WindowClosedEvent _ -> return Nothing
---    WindowSizeChangedEvent (WindowSizeChangedEventData {windowSizeChangedEventSize = V2 x y})
---                        -> GL.viewport $= (GL.Position 0 0,GL.Size x y) >> return (Just e)
---    _                   -> return $ Just e
---
-
+-- | Handle quit events in a manner to exit the loop. Other events handled as
+-- determined by the custom function, although resize events also change the viewport.
 applyEventIO :: (world -> Event -> Maybe world) -> Maybe world -> Event -> IO (Maybe world)
 applyEventIO fn mw e = case eventPayload e of
     QuitEvent           -> return Nothing
@@ -109,3 +101,15 @@ applyEventIO fn mw e = case eventPayload e of
                         -> GL.viewport $= (GL.Position 0 0,GL.Size x y) >> return (mw >>= \w -> fn w e)
     _                   -> return $ mw >>= flip fn e
 
+-- | Create an OpenGL SDL window configuration with a given x and y size.
+winConfig :: Int -> Int -> WindowConfig
+winConfig x y = defaultWindow 
+    { windowGraphicsContext
+        = OpenGLContext (defaultOpenGL { glProfile = Core Normal 4 3
+                                       , glColorPrecision = V4 8 8 8 8
+                                       } 
+                        )
+    , windowInitialSize = V2 (fromIntegral x) (fromIntegral y)
+    , windowResizable =True
+    }
+